Aw terrain query
| Minimum requirements | ||
|---|---|---|
| Added in version 3.3 | ||
| SDK | build 24 | |
int aw_terrain_query (int page_x, int page_z, unsigned long sequence)
Description
Queries a terrain page for changes.
Callback
None (returns immediately)
Notes
This is the primary method for downloading terrain data from a world server.
Terrain nodes for the terrain page specified by page_x and page_z that have changed since the sequence number sequence are returned via the events AW_EVENT_TERRAIN_BEGIN, AW_EVENT_TERRAIN_DATA, and AW_EVENT_TERRAIN_END. Since not all nodes may be returned in a given call to this method, multiple calls may be necessary in order to query all terrain for a given page. To get the entire contents of a terrain page, call this method until AW_TERRAIN_COMPLETE is 1 (true) within the context of the AW_EVENT_TERRAIN_END event handler, updating the sequence number with each call based on the value of AW_TERRAIN_SEQUENCE.
Note that an unmodified terrain page will not return any terrain nodes when queried. The SDK application should assume that the terrain page is flat and uses texture #0 until it receives terrain nodes that say otherwise. Also, the terrain nodes received for a modified terrain page might only cover a portion of it.
For version 4.1 and later: The SDK 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 integers (16 bits). Version 2 is the default for version 4.1 applications and is reset to a value of 2 when entering a world.
See the terrain section for more information.
Arguments
- page_x
- Terrain page X coordinate (East - West).
- page_z
- Terrain page Z coordinate (South - North).
- sequence
- Sequence number.
Argument attributes
Return values
- RC_SUCCESS
- RC_NOT_INITIALIZED
- RC_NO_INSTANCE
- RC_NO_CONNECTION
- Network connection to the world is down.
Returned attributes
None
Usage
Download all terrain data for a given page.
#define PAGE_SIZE 128
int height[PAGE_SIZE][PAGE_SIZE];
unsigned short texture[PAGE_SIZE][PAGE_SIZE];
int sequence = 0;
int up_to_date = 0;
int query_in_progress = 0;
static void handle_terrain_data (void)
{
unsigned int len;
int cell_x;
int cell_z;
int node_x;
int node_z;
int node_size;
int* heights;
unsigned short* textures;
// receive one node's worth of terrain data
node_x = aw_int (AW_TERRAIN_NODE_X);
node_z = aw_int (AW_TERRAIN_NODE_Z);
node_size = aw_int (AW_TERRAIN_NODE_SIZE);
textures = (unsigned short*)aw_data (AW_TERRAIN_NODE_TEXTURES, &len);
heights = (int*)aw_data (AW_TERRAIN_NODE_HEIGHTS, &len);
for (cell_z = 0; cell_z < node_size; cell_z++)
{
for (cell_x = 0; cell_x < node_size; cell_x++)
{
if (aw_int (AW_TERRAIN_NODE_HEIGHT_COUNT) == 1)
// node is "flat" - only one height value
height[cell_x + node_x][cell_z + node_z] = *heights;
else
height[cell_x + node_x][cell_z + node_z] = *heights++;
if (aw_int (AW_TERRAIN_NODE_TEXTURE_COUNT) == 1)
// only one texture value for entire node
texture[cell_x + node_x][cell_z + node_z] = *textures;
else
texture[cell_x + node_x][cell_z + node_z] = *textures++;
}
}
}
static void handle_terrain_end (void)
{
// Note, store the sequence, and provide the cached sequence with subsequent queries.
sequence = aw_int (AW_TERRAIN_SEQUENCE);
if (aw_bool (AW_TERRAIN_COMPLETE))
up_to_date = 1;
query_in_progress = 0;
}
void download_page (int page_x, int page_z)
{
int rc;
aw_event_set (AW_EVENT_TERRAIN_DATA, handle_terrain_data);
aw_event_set (AW_EVENT_TERRAIN_END, handle_terrain_end);
memset (&height, 0, sizeof (height));
memset (&texture, 0, sizeof (texture));
up_to_date = 0;
query_in_progress = 0;
// Note, store the sequence and provide the cached sequence with subsequent queries.
// this examples assumes your local cache is empty.
sequence = 0;
while (!up_to_date)
{
if (!query_in_progress)
{
// start a new query
rc = aw_terrain_query (page_x, page_z, sequence);
if (rc != RC_SUCCESS)
{
printf ("Unable to query terrain (reason %d)", rc);
return;
}
query_in_progress = 1;
}
// wait for query to complete
aw_wait (60);
}
}