Aw terrain set
| Minimum requirements | ||
|---|---|---|
| Added in version 3.3 | ||
| SDK | build 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
Return values
- RC_SUCCESS
- RC_NOT_INITIALIZED
- RC_NO_INSTANCE
- RC_NO_CONNECTION
- The connection to the world is down.
Returned attributes
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);
}