aw_terrain_query queries a terrain page for changes

Callback

None (returns immediately)

Notes

This method is new in SDK build 24 and requires a version 3.3 or later world server.

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 aw_terrain_query, 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 aw_terrain_query until AW_TERRAIN_COMPLETE is 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.

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

Example

/* download all terrain data for a given page */

#define PAGE_SIZE 128
#define TEXTURE   0

short height[PAGE_SIZE][PAGE_SIZE];
char  texture[PAGE_SIZE][PAGE_SIZE];
int   sequence;
int   up_to_date;
int   query_in_progress;

static void handle_terrain_data (void)
{

  unsigned char   len;
  int             x;
  int             z;
  int             node_x;
  int             node_z;
  int             node_size;
  short*          heights;
  unsigned char*  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 = aw_data (AW_TERRAIN_NODE_TEXTURES, &len);
  heights = (short *)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 nod */
        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 = TRUE;
  query_in_progress = FALSE;

}

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);
  up_to_date = FALSE;
  query_in_progress = FALSE;
  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) {
        printf ("Unable to query terrain (reason %d)", rc);
        return;
      }
      query_in_progress = TRUE;
    }
    /* wait for query to complete */
    aw_wait (10);
  }

}

SEE ALSO

aw_terrain_query
aw_terrain_next
aw_terrain_delete_all
aw_terrain_load_node
AW_EVENT_TERRAIN_CHANGED