Aw data
| Minimum requirements | ||
|---|---|---|
| Added in version 3.3 | ||
| SDK | build 24 | |
char* aw_data (AW_ATTRIBUTE a, unsigned int *length)
Description
Returns a data attribute.
Callback
None (returns immediately)
Notes
Important: The returned pointer is only valid immediately after the call to this method and may be invalidated by subsequent calls into the SDK. Therefore an application must copy a data attribute to its own local buffer if it wishes to keep the data for an extended period of time.
A few of the data attributes have a maximum length defined by AW_MAX_ATTRIBUTE_LENGTH in Aw.h. This limit is currently 255 bytes. Most attributes can be longer than this (e.g. AW_OBJECT_DATA). Their maximum lengths can vary up to 4094 bytes depending on the attribute (e.g. AW_OBJECT_DATA has a maximum length of 4094 bytes).
Data buffers are used when dealing with property, and contain additional information for cameras, zones, particles, or movers. All of these object types will have data associated with them, to control their behavior. If you are performing a property query and want to be able to rebuild or alter one of these object types later, then you must store the contents of the data buffer.
Another use of aw_data is terrain data, heights and textures for terrain pages.
See SDK Attributes for more information.
Arguments
- a
- Attribute (defined in Aw.h).
- length
- Returns the length of the data. Only when a data pointer is returned (not NULL). This must be a valid pointer.
Argument attributes
None
Return values
- NULL
- The attribute is not a data buffer, is outside the range of defined attributes (i.e. 0 to AW_MAX_ATTRIBUTE - 1), or there is no current instance (i.e. aw_instance () returns NULL).
- Pointer to data
- Attribute has been set.
Returned attributes
None
Usage
void process_object_data (void)
{
unsigned int length = 0;
char* data;
char* buffer;
struct aw_object_data_mover* mover = NULL;
struct aw_object_data_particles* particles = NULL;
struct aw_object_data_camera* camera = NULL;
struct aw_object_data_zone* zone = NULL;
data = aw_data (AW_OBJECT_DATA, &length);
if (length == 0)
return;
buffer = malloc (length);
if (!buffer)
return;
/* save the contents of the data for later */
memcpy (buffer, data, sizeof(buffer));
switch (aw_int (AW_OBJECT_TYPE))
{
case AW_OBJECT_TYPE_ZONE:
zone = (aw_object_data_zone*)buffer;
break;
case AW_OBJECT_TYPE_MOVER:
mover = (aw_object_data_mover*)buffer;
break;
case AW_OBJECT_TYPE_PARTICLES:
particles = (aw_object_data_particles*)buffer;
break;
case AW_OBJECT_TYPE_CAMERA:
camera = (aw_object_data_camera*)buffer;
break;
default:
break;
}
/* ... */
}