Revision #5 by Dr. Squailboont, 30-NOV-2006
NOTE: This article currently only applies to C/C++ programmers. Information for Visual Basic and Delphi (Pascal) may soon be provided.
The SDK structures provided for the new 4.1 objects (Particle Emitters, Movers, Zones, and Cameras) are utilized in a way that, due to a lack of adequate documentation, is unwieldy to most programmers. The purpose of this article is to demonstrate the proper method of creating particle emitters via the SDK.
As indicated in the declaration of aw_object_data_particles, the str_data field contains a reference to the first byte of the necessary strings for the asset list and tag name.
To properly allocate and initialize the aw_object_data_particles structure, the following code should be used:
| 1 | size_t slen = 0, psiz = 0; |
| 2 | aw_object_data_particles* pe = NULL; |
| 3 | |
| 4 | /* Determine length of user string */ |
| 5 | slen = strlen(asset_list); |
| 6 | |
| 7 | /* Now determine how much memory to allocate for the PE */ |
| 8 | psiz = slen + sizeof(aw_object_data_particles); |
| 9 | |
| 10 | /* Allocate and initialize PE */ |
| 11 | pe = (aw_object_data_particles*)malloc(psiz); |
| 12 | memset(pe, 0, psiz); |
| 13 | |
| 14 | /* TODO: Fill in PE as desired */ |
| 15 | |
| 16 | /* Copy asset list to the end of the structure */ |
| 17 | |
| 18 | pe->asset_list_len = (unsigned short)slen; |
| 19 | memcpy(pe->str_data, asset_list, slen); |
(Note that this code sample assumes only an asset list is provided, and the PE is not given a tag name.)
In line #11, malloc is used to allocate memory. psiz represents the length of the string and the size of the aw_object_data_particles structure, which is passed to malloc.
Line #12 calls memset to initialize the newly allocated memory with the value 0.
Line #18 assigns the size of the user string to the asset_list_len field, and then in line #19 the asset_list string is copied to the end of the PE structure with str_data[0] containing a reference to the first byte. (Note that we do not need to copy the terminating NUL byte.)
Here is a graphical representation of the structure, with both an asset list and a tag name.
The base structure size is the size of the PE when no asset list or tag name is specified; as of build 63, this is 203 bytes (sizeof(aw_object_data_particles)). In the example above, the asset list is 15 bytes and the tag name is 5 bytes (remember these strings are not NUL-terminated). Adding the lengths of these strings together (20 bytes) to the base structure size produces 223 bytes; this is the number of bytes to allocate via malloc. The string data will appear at the end as displayed. To read the tag name, go 15 bytes over (the length of the asset list) and begin copying 5 bytes until you reach the end of the structure (bytes 218 to 223).
Two general-purpose C functions are available here to assist in initializing and preparing to build particle emitters. Additional functions for movers (including waypoints), cameras, and zones are also available.