Structs

A struct is an assembled object that contains variables, pointers, or further structs. There are several predefined struct types for engine objects, like ENTITY, VIEW, PANEL, TEXT, or MATERIAL. They are defined in the file include\atypes.h. Members of a struct are individually accessed using the struct name, followed by a '.' and the member name. Example:

myentity.alpha = 33;
mypanel.red = 255;
mymaterial.emissive_blue = 100;

 LC  In lite-C, you can additionally define individual structs (so the rest of this chapter only applies to lite-C). Example for a user-defined struct:

typedef struct { 
  int x; 
  int y; 
  char name[10];
} SPOT;  // defines a struct type named "SPOT"
...
SPOT myspot; // creates an uninitalized SPOT struct named "myspot"
SPOT* pspot; // creates an uninitalized pointer to a SPOT struct
...
myspot.x = 10;
myspot.name = "test!";

A struct can contain pointers to previously defined structs, and even pointers on itself, but no pointers to later defined structs:

typedef struct SPOT { 
  int x; 
  int y; 
  char name[10];
  struct SPOT* next; // pointer to a SPOT struct
} SPOT;  // defines a struct type named "SPOT"

Unlike variables, structs can not be initialized when they are created. However global struct pointers can (to preserve backwards compatibility with C-Script). Example:

SPOT* myspot = { x = 1; y = 2; name = "my struct"; }  
// creates a new SPOT struct with initial values that is then referenced through the myspot pointer

 !!  Note that this initialization only works for global struct pointers, but not for local struct pointers that are defined within a function, and not for arrays. While you can define struct pointer arrays (like SPOT* pspots[100];), you can not initialize them in the definition. Within the struct initialization, any numbers, variables, character strings, or pointers to other structs can be used, but internal engine variables (such as "camera"), and #defines (such as a previously defined "NUMBER_OF_ARRAY_ELEMENTS") can not be used.

In standard C / C++, members of structs are accessed by a dot '.' and members of struct pointers are accessed by an arrow '->'. In lite-C or C-Script, the dot '.' can normally be used for both because the compiler automatically detects whether a simple object is a pointer or not. You only need to give the '->' in ambiguous cases, for instance when the struct pointer is a member of another struct pointer.

SPOT* myspot = { x = 1; y = 2; name = "my struct"; }
...
myspot->x = 1; // standard C/C++; works also in lite-c
myspot.y = 2;  // C-Script / lite-C 

Vectors

Besides the engine objects, there are also standard structs that can be used as parameter to functions: a VECTOR struct with x, y, z vars, an Euler ANGLE struct with pan, tilt, roll vars (see "coordinates"), and a COLOR struct with blue, green, red vars. They are also defined in include\atypes.h and used in many engine functions.

Structs themselves are not passed as arguments to or returned by functions, but struct pointers are. Lite-C automatically detects whether the argument is a pointer, and converts it to a pointer if not. Example:

function spot_init(SPOT* spot) 
{ 
  if (!spot) return; // prevent crash when an empty pointer is passed
  spot.x = 1; 
  spot.y = 1; 
}
...
SPOT myspot; // creates an uninitalized SPOT struct named "myspot"
...
spot_init(myspot); // passes a pointer to myspot

sizeof(struct)

#define zero(struct) memset((void*)&struct,0,sizeof(struct))
...
VECTOR speed;
zero(speed);	// initializes the VECTOR struct "speed" to zero

See also: