Aw terrain query
From ActiveWiki
| Minimum requirements | ||
|---|---|---|
| Added in version 3.3 | ||
| SDK | build 24 | |
int aw_terrain_query (int page_x, int page_z, unsigned long sequence)
[edit] Description
Queries a terrain page for changes.
[edit] Callback
None (returns immediately)
[edit] 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.
[edit] Arguments
- page_x
- Terrain page X coordinate (East - West).
- page_z
- Terrain page Z coordinate (South - North).
- sequence
- Sequence number.
[edit] Argument attributes
[edit] Return values
- RC_SUCCESS
- RC_NOT_INITIALIZED
- RC_NO_INSTANCE
- RC_NO_CONNECTION
- Network connection to the world is down.
[edit] Returned attributes
None
[edit] Usage
Download all terrain data for a given page.
#define PAGE_SIZE 128
#define TEXTURE 0
int height[PAGE_SIZE][PAGE_SIZE];
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 x;
int 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 (z = 0; z < node_size; z++)
for (x = 0; x < node_size; x++)
{
if (aw_int (AW_TERRAIN_NODE_HEIGHT_COUNT) == 1)
/* node is "flat" - only one height value */
height[x + node_x][z + node_z] = *heights;
else
height[x + node_x][z + node_z] = *heights++;
if (aw_int (AW_TERRAIN_NODE_TEXTURE_COUNT) == 1)
/* only one texture value for entire node */
texture[x + node_x][z + node_z] = *textures;
else
texture[x + node_x][z + node_z] = *textures++;
}
}
static void handle_terrain_end (void)
{
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;
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 (10);
}
}
