Aw terrain set

From ActiveWiki
Jump to: navigation, search


Minimum requirements
Added in version 3.3
SDKbuild 24


int aw_terrain_set (int cell_x, int cell_z, int count, int texture, int *heights)

Description

Uploads a single row of terrain data.

Callback

AW_CALLBACK_TERRAIN_SET_RESULT

Notes

This is the primary method for uploading terrain data from SDK applications. It uploads a single row of count cells of terrain data, up to a maximum of 1000 cells, starting at the cell identified by x and z and extending in the positive X direction (West). The elevation values are specified in an array of shorts pointed to by heights. All the cells are assigned the texture value of texture. If the row of terrain data requires multiple texture values then it must be uploaded via multiple calls to this method.

Only world server administration instances or those owned by a caretaker (i.e. aw_bool (AW_WORLD_CARETAKER_CAPABILITY) returns 1) or those that have emiment domain (i.e. aw_bool (AW_WORLD_EMINENT_DOMAIN_CAPABILITY) returns 1) may use this method.

For version 4.1 and later: The application must set AW_TERRAIN_VERSION_NEEDED to the required version. Version 1 of the terrain (pre 4.1) represented heights in short integers (16 bits) and textures in bytes (8 bits). Version 2 of terrain data represents heights in integers (32 bits) and textures in short integerts (16 bits). Version 2 is the default for version 4.1 applications and is reset to a value of 2 each entering a world.

See the terrain section for more information on manipulating terrain from the SDK.


Arguments

cell_x
Cell X coordinate (East - West)
cell_z
Cell Z coordinate (South - North)
count
Number of cells.
texture
Texture to use for the cells.
heights
Heights to use for the cells.

Argument attributes

AW_TERRAIN_VERSION_NEEDED

Return values

RC_SUCCESS
RC_NOT_INITIALIZED
RC_NO_INSTANCE
RC_NO_CONNECTION
The connection to the world is down.

Returned attributes

AW_TERRAIN_X
AW_TERRAIN_Z

Usage

Upload a GRID_SIZE x GRID_SIZE grid of terrain data, centered at GZ.

#define GRID_SIZE 100
#define TEXTURE   0

int heights[GRID_SIZE][GRID_SIZE];

void upload_terrain (void)
{
  int rc;
  int z;
  
  // terrain version 1 requires signed short integer (2 bytes = 16 bits) for heights (limited to about +/- 320 meters)
  // terrain version 2 requires signed integer (4 bytes = 32 bits) for heights
  // terrain version 2 is the default since SDK 4.1, heights required as 32 bit signed integers
  // aw_int_set (AW_TERRAIN_VERSION_NEEDED, 2);
  
  for (cell_z = 0; cell_z < GRID_SIZE; cell_z++)
  {
    rc = aw_terrain_set (-GRID_SIZE / 2, cell_z - GRID_SIZE / 2, GRID_SIZE, TEXTURE, heights[cell_z]);
    if (rc != RC_SUCCESS)
    {
      printf ("Unable to upload terrain (reason %d)\n", rc);
      break;
    }
  }
}

Holes

#include <limits.h>
#define HOLE          (USHRT_MAX - 1)
#define MAXIMUM_ELEV  (1000 * 100)  // max height of 1000 meters
#define MINIMUM_ELEV  (-1000 * 100) // min height of -1000 meters

int my_set_terrain_hole (int cell_x, int cell_z, int height)
{
  //<-- validate arguments
  if (height > MAXIMUM_ELEV)      height = MAXIMUM_ELEV;
  else if (height < MINIMUM_ELEV) height = MINIMUM_ELEV;
  
  if (abs(cell_x) > aw_int (AW_WORLD_SIZE) + 10 || abs(cell_z) > aw_int (AW_WORLD_SIZE) + 10)
    return -1; // invalid argument
  //-->
  
  return aw_terrain_set (cell_x, cell_z, 1, HOLE, &height);
}


Texture Rotation

#include <limits.h>

#define MAX_TEXTURES  500
#define HOLE          (USHRT_MAX - 1)
#define MAXIMUM_ELEV  (1000 * 100)  // max height of 1000 meters
#define MINIMUM_ELEV  (-1000 * 100) // min height of -1000 meters
#define TEXTURE_MASK  0x3FFF
#define ROTATE_90     0x4000

int my_set_terrain_rotation (int cell_x, int cell_z, int height, int tex, int degrees)
{
  int tex_rotated   = 0;
  int tex_unrotated = tex & TEXTURE_MASK;
  int prev_rotation = tex >> 14; // just for reference, not used here
  
  //<-- validate arguments
  if (tex == HOLE || tex_unrotated < 0 || tex_unrotated > MAX_TEXTURES)
    return -1; // n/a, invalid argument
  
  if (abs(cell_x) > aw_int (AW_WORLD_SIZE) + 10 || abs(cell_z) > aw_int (AW_WORLD_SIZE) + 10)
    return -1; // invalid argument
  
  if (height > MAXIMUM_ELEV)      height = MAXIMUM_ELEV;
  else if (height < MINIMUM_ELEV) height = MINIMUM_ELEV;
  //-->
  
  // generic form:
  // tex_rotated = tex_unrotated | (ROTATE_90 * max(abs(degrees / 90), 3));
  // accept degrees in range of -360° to +360°, in steps of 90°:
  switch (degrees) {
    case 0:    // no rotation
    case 360:
    case -360:
      tex_rotated = tex_unrotated;
      break;
    case 90:   // left
    case -270:
      tex_rotated = tex_unrotated | ROTATE_90;
      break;
    case 180:
    case -180:
      tex_rotated = tex_unrotated | (ROTATE_90 * 2);
      break;
    case 270:  // right
    case -90:
      tex_rotated = tex_unrotated | (ROTATE_90 * 3);
      break;
    default:
      return -1; // invalid argument
  }
  
  return aw_terrain_set (cell_x, cell_z, 1, tex_rotated, &height);
}


See also