Aw terrain query

From ActiveWiki
Jump to: navigation, search


Minimum requirements
Added in version 3.3
SDKbuild 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

AW_TERRAIN_VERSION_NEEDED

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);
  }
}

See also