Xors3d Engine
Entity control

Functions

BBDECL void BBCALL xCalculateFrustumVolume (Entity *entity)
 Calculates a volume used for frustum culling.
BBDECL Entity *BBCALL xCopyEntity (Entity *entity, Entity *parent=NULL, int cloneBuffers=0)
 Creates a copy of an entity and returns the handle of the newly created copy. This is a new entity instance of an existing entity's mesh. Anything you do to the original mesh (such as xRotateMesh()) will effect all the copies. Other properties (such as xEntityColor(), xPositionEntity(), etc.) since they are 'Entity' properties, will be individual to the copy. If a parent entity is specified, the copied entity will be created at the parent entity's position. Otherwise, it will be created at 0, 0, 0.
BBDECL Entity *BBCALL xCreateInstance (Entity *entity, Entity *parent=NULL)
 Creates entity instancee and returns its handle.
BBDECL void BBCALL xEntityAlpha (Entity *entity, float alpha)
 Sets the alpha level of an entity.
BBDECL void BBCALL xEntityAlphaFunc (Entity *entity, int value)
 Sets the alpha test function of an entity.
BBDECL void BBCALL xEntityAlphaRef (Entity *entity, int value)
 Sets the reference alpha value of an entity.
BBDECL void BBCALL xEntityAmbientColor (Entity *entity, int red, int green, int blue)
 Sets the ambient color of an entity.
BBDECL void BBCALL xEntityAutoFade (Entity *entity, float nearRange, float farRange)
 Enables auto fading for an entity.
BBDECL void BBCALL xEntityBlend (Entity *entity, int mode)
 Sets the blending mode of an entity.
BBDECL void BBCALL xEntityColor (Entity *entity, int red, int green, int blue)
 Sets the diffuse color of an entity.
BBDECL void BBCALL xEntityEmissiveColor (Entity *entity, int red, int green, int blue)
 Sets the emissive color of an entity.
BBDECL void BBCALL xEntityFX (Entity *entity, int fx)
 Sets miscellaneous effects for an entity.
BBDECL void BBCALL xEntityOrder (Entity *entity, int order)
 Sets the drawing order for an entity.
BBDECL void BBCALL xEntityParent (Entity *entity, Entity *parent=NULL, bool isGlobal=true)
 Attaches an entity to a parent.
BBDECL void BBCALL xEntityShininess (Entity *entity, float shininess)
 Sets the specular shininess of an entity.
BBDECL void BBCALL xEntitySpecularColor (Entity *entity, int red, int green, int blue)
 Sets the specular color of an entity.
BBDECL void BBCALL xEntityTexture (Entity *entity, Texture *texture, int frame=0, int index=0, int isRecursive=1)
 Applies a texture to an entity.
BBDECL void BBCALL xFreeEntity (Entity *entity)
 Frees up an entity.
BBDECL void BBCALL xHideEntity (Entity *entity)
 Hides an entity, so that it is no longer visible, and is no longer involved in collisions.
BBDECL void BBCALL xNameEntity (Entity *entity, const char *name)
 Sets an entity's name.
BBDECL void BBCALL xPaintEntity (Entity *entity, Brush *brush)
 Paints a entity with a brush.
BBDECL void BBCALL xSetEntityMatrix (Entity *entity, D3DXMATRIX *matrix)
 Sets entity world matrix.
BBDECL void BBCALL xSetEntityQuaternion (Entity *entity, Quaternion *quaternion)
 Sets entity rotation quaternion.
BBDECL void BBCALL xSetFrustumSphere (Entity *entity, float x, float y, float z, float radii)
 Sets entity's bounding sphere for frustum culling.
BBDECL void BBCALL xShowEntity (Entity *entity)
 Shows an entity.

Function Documentation

BBDECL void BBCALL xEntityAutoFade ( Entity *  entity,
float  nearRange,
float  farRange 
)

Enables auto fading for an entity.

This will cause an entity's alpha level to be adjusted at distances between near and far to create a 'fade-in' effect.

Parameters:
entityEntity handle
nearRangeDistance in front of the camera at which entity's will start being faded
farRangeDistance in front of the camera at which entity's will stop being faded (and will be invisible).
BBDECL void BBCALL xEntityOrder ( Entity *  entity,
int  order 
)

Sets the drawing order for an entity.

An order value of 0 will mean the entity is drawn normally. A value greater than 0 will mean that entity is drawn first, behind everything else. A value less than 0 will mean the entity is drawn last, in front of everything else. Setting an entity's order to non-0 also disables z-buffering for the entity, so should be only used for simple, convex entities like skyboxes, sprites etc. xEntityOrder() affects the specified entity but none of its child entities, if any exist.

Parameters:
entityEntity handle
orderOrder that entity will be drawn in
BBDECL void BBCALL xFreeEntity ( Entity *  entity)

Frees up an entity.

Parameters:
entityEntity handle
BBDECL Entity* BBCALL xCopyEntity ( Entity *  entity,
Entity *  parent = NULL,
int  cloneBuffers = 0 
)

Creates a copy of an entity and returns the handle of the newly created copy. This is a new entity instance of an existing entity's mesh. Anything you do to the original mesh (such as xRotateMesh()) will effect all the copies. Other properties (such as xEntityColor(), xPositionEntity(), etc.) since they are 'Entity' properties, will be individual to the copy. If a parent entity is specified, the copied entity will be created at the parent entity's position. Otherwise, it will be created at 0, 0, 0.

Parameters:
entityEntity handle
parentParent entity handle
cloneBuffersIf true vertex and indices buffers will be cloned
BBDECL void BBCALL xPaintEntity ( Entity *  entity,
Brush *  brush 
)

Paints a entity with a brush.

The reason for using xPaintEntity() to apply specific properties to a entity using a brush rather than just using xEntityTexture(), xEntityColor(), xEntityShininess() etc, is that you can pre-define one brush, and then paint entities over and over again using just the one command rather than lots of separate ones.

Parameters:
entityEntity handle
brushBrush handle
BBDECL void BBCALL xEntityShininess ( Entity *  entity,
float  shininess 
)

Sets the specular shininess of an entity.

The shininess value should be a floting point number in the range [0.0; 1.0]. The default shininess setting is 0.0 Shininess is how much brighter certain areas of an object will appear to be when a light is shone directly at them. Setting a shininess value of 1.0 for a medium to high poly sphere, combined with the creation of a light shining in the direction of it, will give it the appearance of a shiny snooker ball.

Parameters:
entityEntity handle
shininessShininess of entity
BBDECL void BBCALL xEntityTexture ( Entity *  entity,
Texture *  texture,
int  frame = 0,
int  index = 0,
int  isRecursive = 1 
)

Applies a texture to an entity.

The optional frame parameter specifies which texture animation frame should be used as the texture. The optional index parameter specifies which index number should be assigned to the texture. Index numbers are used for the purpose of multitexturing. See xTextureBlend().

Parameters:
entityEntity handle
textureTexture handle
frameFrame of texture
indexIndex number of texture. Should be in the range [0; 7].
isRecursiveIf 1 (true) then entity's children will receive the texture too.
BBDECL void BBCALL xEntityFX ( Entity *  entity,
int  fx 
)

Sets miscellaneous effects for an entity.

Flags can be added to combine two or more effects.

Parameters:
entityEntity handle
fxEffects flags. See 'FX flags' for more information
BBDECL void BBCALL xSetFrustumSphere ( Entity *  entity,
float  x,
float  y,
float  z,
float  radii 
)

Sets entity's bounding sphere for frustum culling.

Parameters:
entityEntity handle
xx coordinate of bounding sphere center
yy coordinate of bounding sphere center
zz coordinate of bounding sphere center
radiiRadius of bounding sphere
BBDECL void BBCALL xCalculateFrustumVolume ( Entity *  entity)

Calculates a volume used for frustum culling.

Both frustum box and frustum sphere are calculated. This function is useful if have modified position of the vertices manually.

Parameters:
entityEntity handle
BBDECL void BBCALL xEntityParent ( Entity *  entity,
Entity *  parent = NULL,
bool  isGlobal = true 
)

Attaches an entity to a parent.

Parent may be 0, in which case the entity will have no parent

Parameters:
entityEntity handle
parentParent entity handle
isGlobalTrue for the child entity to retain its global position and orientation
BBDECL void BBCALL xShowEntity ( Entity *  entity)

Shows an entity.

Once an entity has been hidden using xHideEntity(), use show entity to make it visible and involved in collisions again. Entities are shown by default after creating/loading them, so you should only need to use xShowEntity() after using xHideEntity().

Parameters:
entityEntity handle
BBDECL void BBCALL xHideEntity ( Entity *  entity)

Hides an entity, so that it is no longer visible, and is no longer involved in collisions.

The main purpose of hide entity is to allow you to create entities at the beginning of a program, hide them, then copy them and show as necessary in the main game. This is more efficient than creating entities mid-game. If you wish to hide an entity so that it is no longer visible but still involved in collisions, then use EntityAlpha 0 instead. This will make an entity completely transparent. xHideEntity() affects the specified entity and all of its child entities, if any exist.

Parameters:
entityEntity handle
BBDECL void BBCALL xNameEntity ( Entity *  entity,
const char *  name 
)

Sets an entity's name.

Parameters:
entityEntity handle
nameName of entity
BBDECL void BBCALL xSetEntityQuaternion ( Entity *  entity,
Quaternion *  quaternion 
)

Sets entity rotation quaternion.

Parameters:
entityEntity handle
quaternionPointer to quaternion (in 'xyzw' form)
BBDECL void BBCALL xSetEntityMatrix ( Entity *  entity,
D3DXMATRIX *  matrix 
)

Sets entity world matrix.

Parameters:
entityEntity handle
matrixPointer to matrix
BBDECL void BBCALL xEntityAlpha ( Entity *  entity,
float  alpha 
)

Sets the alpha level of an entity.

The 'alpha' value should be in a floating point value in the range [0.0; 1.0]. The default entity alpha setting is 1.0. The alpha level is how transparent an entity is. A value of 1.0 will mean the entity is opaque. A value of 0.0 will mean the entity is completely transparent, i.e. invisible. Values between 0.0 and 1.0 will cause varying amount of transparency. This is useful for imitating the look of objects such as glass and other translucent materials.

Parameters:
entityEntity handle
alphaAlpha level of entity
BBDECL void BBCALL xEntityColor ( Entity *  entity,
int  red,
int  green,
int  blue 
)

Sets the diffuse color of an entity.

The red, green and blue values should be in the range [0; 255] with 0 being darkest and 255 brightest. The default entity color is 255, 255, 255 (white).

Parameters:
entityEntity handle
redRed value of entity color
greenGreen value of entity color
blueBlue value of entity color
BBDECL void BBCALL xEntitySpecularColor ( Entity *  entity,
int  red,
int  green,
int  blue 
)

Sets the specular color of an entity.

The red, green and blue values should be in the range [0; 255] with 0 being darkest and 255 brightest. The default specular entity color is 0, 0, 0 (black). xEntityShininess() also change specular color.

Parameters:
entityEntity handle
redRed value of entity specular color
greenGreen value of entity specular color
blueBlue value of entity specular color
BBDECL void BBCALL xEntityAmbientColor ( Entity *  entity,
int  red,
int  green,
int  blue 
)

Sets the ambient color of an entity.

The red, green and blue values should be in the range [0; 255] with 0 being darkest and 255 brightest. The default entity ambient color is 255, 255, 255 (white). xEntityColor() also change ambient color

Parameters:
entityEntity handle
redRed value of entity ambient color
greenGreen value of entity ambient color
blueBlue value of entity ambient color
BBDECL void BBCALL xEntityEmissiveColor ( Entity *  entity,
int  red,
int  green,
int  blue 
)

Sets the emissive color of an entity.

The red, green and blue values should be in the range [0; 255] with 0 being darkest and 255 brightest. The default emissive entity color is 0, 0, 0 (black).

Parameters:
entityEntity handle
redRed value of entity emissive color
greenGreen value of entity emissive color
blueBlue value of entity emissive color
BBDECL void BBCALL xEntityBlend ( Entity *  entity,
int  mode 
)

Sets the blending mode of an entity.

This blending mode determines the way in which the new RGBA of the pixel being rendered is combined with the RGB of the background. To calculate the new RGBA of the pixel being rendered, the texture RGBA for the pixel is taken, its alpha component multiplied by the entities/brushes (where applicable) alpha value and its color compentent multiplied by the entities/brushes colour. This is the RGBA which will then be blended into the background pixel, and how this is done depends on the xEntityBlend() value.

Parameters:
entityEntity handle
modeBlend mode. See 'Blending modes' for more information
BBDECL void BBCALL xEntityAlphaRef ( Entity *  entity,
int  value 
)

Sets the reference alpha value of an entity.

The 'value' value should be an integer in the range [0; 255]. The default value is 0. It specifies a reference alpha value against which pixels are tested when alpha testing is enabled (See xEntityAlphaFunc()). This is useful for varying smoothness of edges of entities with masked textures (e.g. grass, leaves, clouds).

Parameters:
entityEntity handle
valueReference alpha value
BBDECL void BBCALL xEntityAlphaFunc ( Entity *  entity,
int  value 
)

Sets the alpha test function of an entity.

The 'value' value should be an integer in the range [1; 8]. The default value is 5 (CMP_GREATER). Alpha test enables an application to accept or reject a pixel, based on its alpha value.

Parameters:
entityEntity handle
valueAlpha test function. See 'Compare functions' for more infomation.
BBDECL Entity* BBCALL xCreateInstance ( Entity *  entity,
Entity *  parent = NULL 
)

Creates entity instancee and returns its handle.

Instncing allows rendering multiple copies of the same mesh in a scene at once. This technique is primarily used for objects such as trees, grass, or buildings which can be represented as repeated geometry without appearing unduly repetitive, but may also be used for characters.

You may rotate, move and scale instance or change its color and alpha value.

Parameters:
entityOriginal entity handle
parentParent entity handle