Xors3d Engine
Meshes

Functions

BBDECL void BBCALL xAddMesh (Entity *source, Entity *destination)
 Adds the source mesh to the destination mesh.
BBDECL Entity *BBCALL xCopyMesh (Entity *entity, Entity *parent=NULL)
 Creates a copy of a mesh and returns the newly-created mesh's handle.
BBDECL int BBCALL xCountSurfaces (Entity *entity)
 Returns the number of surfaces in a mesh.
BBDECL Node *BBCALL xCreateCone (int segments=16, bool solid=true, Entity *parent=NULL)
 Creates a cone mesh/entity and returns its handle.
BBDECL Node *BBCALL xCreateCube (Entity *parent=NULL)
 Creates a cube mesh/entity and returns its handle.
BBDECL Node *BBCALL xCreateCylinder (int segments=16, bool solid=true, Entity *parent=NULL)
 Creates a cylinder mesh/entity and returns its handle.
BBDECL Entity *BBCALL xCreateMesh (Entity *parent=NULL)
 Creates a 'blank' mesh entity and returns its handle.
BBDECL Entity *BBCALL xCreatePivot (Entity *parent=NULL)
 Creates a pivot entity.
BBDECL Node *BBCALL xCreatePoly (int sides, Entity *parent=NULL)
 Creates a polygon.
BBDECL Node *BBCALL xCreateSphere (int segments=16, Entity *parent=NULL)
 Creates a sphere mesh/entity and returns its handle.
BBDECL Node *BBCALL xCreateTorus (int segments=16, float R=1.0f, float r_tube=0.025f, Entity *parent=NULL)
 Creates a torus mesh/entity and returns its handle.
BBDECL void BBCALL xDeleteMeshIB (Entity *entity)
 Deletes an allocated array for mesh indecies.
BBDECL void BBCALL xDeleteMeshVB (Entity *entity)
 Deletes an allocated array for mesh verticies.
BBDECL Surface *BBCALL xFindSurface (Node *entity, Brush *brush)
 Attempts to find a surface attached to the specified mesh and created with the specified brush.
BBDECL void BBCALL xFitMesh (Entity *entity, float x, float y, float z, float width, float height, float depth, bool uniform=false)
 Scales and translates all vertices of a mesh so that the mesh occupies the specified box.
BBDECL void BBCALL xFlipMesh (Entity *entity)
 Flips all the triangles in a mesh.
BBDECL int *BBCALL xGetMeshIB (Entity *entity)
 Returns a pointer to mesh indeices.
BBDECL int BBCALL xGetMeshIBSize (Entity *entity)
 Returns a size of mesh indeices buffer.
BBDECL float *BBCALL xGetMeshVB (Entity *entity)
 Returns pointer to mesh vertices.
BBDECL int BBCALL xGetMeshVBSize (Entity *entity)
 Returns a size of mesh vertices buffer.
BBDECL Surface *BBCALL xGetSurface (Entity *entity, int index)
 Returns the handle of the surface attached to the specified mesh and with the specified index number.
BBDECL void BBCALL xLightMesh (Entity *entity, int red, int green, int blue, float range=0.0f, float lightX=0.0f, float lightY=0.0f, float lightZ=0.0f)
 Performs a 'fake' lighting operation on a mesh.
BBDECL Entity *BBCALL xLoadAnimMesh (const char *path, Entity *parent=NULL)
 Similar to xLoadMesh(), loads a mesh from the file (B3D is fully supported; X, OBJ, FBX, 3DS, MS3D are partially supported) and returns a mesh handle.
BBDECL Entity *BBCALL xLoadMesh (const char *path, Entity *parent=NULL)
 Loads a mesh from a file (B3D is fully supported; X, OBJ, FBX, 3DS, MS3D are partially supported) and returns the mesh handle.
BBDECL Entity *BBCALL xLoadMeshWithChild (const char *path, Entity *parent=NULL)
 Loads a static mesh with saving hierarchy.
BBDECL float BBCALL xMeshDepth (Entity *entity, bool recursive=false)
 Returns the depth of a mesh.
BBDECL int BBCALL xMeshesBBIntersect (Entity *entity1, Entity *entity2)
 Returns true if the specified meshes bounding boxes are currently intersecting.
BBDECL int BBCALL xMeshesIntersect (Entity *entity1, Entity *entity2)
 Returns true if the specified meshes are currently intersecting.
BBDECL float BBCALL xMeshHeight (Entity *entity, bool recursive=false)
 Returns the height of a mesh.
BBDECL void BBCALL xMeshPrimitiveType (Entity *entity, int ptype)
 Sets the type of primitive to render.
BBDECL void BBCALL xMeshSingleSurface (Node *entity)
 Converts an entity with several surfaces into an entity with a single surface. All textures of this entity become ignorable.
BBDECL float BBCALL xMeshWidth (Entity *entity, bool recursive=false)
 Returns the width of a mesh.
BBDECL void BBCALL xPaintMesh (Entity *entity, Brush *brush)
 Paints a mesh with a brush.
BBDECL void BBCALL xPositionMesh (Entity *entity, float x, float y, float z)
 Moves all vertices of a mesh.
BBDECL void BBCALL xRotateMesh (Entity *entity, float x, float y, float z)
 Rotates all vertices of a mesh by the specified rotation.
BBDECL int BBCALL xSaveMesh (Entity *entity, const char *path)
 Saves mesh hierarhy into the .FBX file.
BBDECL void BBCALL xScaleMesh (Entity *entity, float x, float y, float z)
 Scales all vertices of a mesh by the specified scaling factors.
BBDECL void BBCALL xUpdateN (Entity *entity)
 Recalculates all normals in a mesh.
BBDECL void BBCALL xUpdateNormals (Entity *entity)
 Recalculates all normals, tangents and binormals in a mesh.
BBDECL void BBCALL xUpdateTB (Entity *entity)
 Recalculates all tangents and binormals in a mesh.

Function Documentation

BBDECL Entity* BBCALL xCreateMesh ( Entity *  parent = NULL)

Creates a 'blank' mesh entity and returns its handle.

When a mesh is first created it has no surfaces, vertices or triangles associated with it

Parameters:
parentParent entity handle
BBDECL Entity* BBCALL xLoadMesh ( const char *  path,
Entity *  parent = NULL 
)

Loads a mesh from a file (B3D is fully supported; X, OBJ, FBX, 3DS, MS3D are partially supported) and returns the mesh handle.

Any hierarchy and animation information in the file will be ignored. Use xLoadAnimMesh() to maintain hierarchy and animation information. The parent parameter allows you to specify a parent entity for the mesh so that when the parent is moved the child mesh will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent. Specifying a parent entity will still result in the mesh being created at position 0, 0, 0 rather than at the parent entity's position.

Parameters:
pathName of the file containing the model to load
parentParent entity handle
BBDECL Entity* BBCALL xLoadMeshWithChild ( const char *  path,
Entity *  parent = NULL 
)

Loads a static mesh with saving hierarchy.

Parameters:
pathString containing filename of mesh file
parentParent entity handle
BBDECL Entity* BBCALL xLoadAnimMesh ( const char *  path,
Entity *  parent = NULL 
)

Similar to xLoadMesh(), loads a mesh from the file (B3D is fully supported; X, OBJ, FBX, 3DS, MS3D are partially supported) and returns a mesh handle.

The difference between xLoadMesh() and xLoadAnimMesh() is that any hierarchy and animation information present in the file is retained. You can then either activate the animation by using the xAnimate() command or find child entities within the hierarchy by using the xFindChild(), xGetChild() functions. The parent parameter allows you to specify a parent entity for the mesh so that when the parent is moved the child mesh will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent. Specifying a parent entity will still result in the mesh being created at position 0, 0, 0 rather than at the parent entity's position.

Parameters:
pathName of the file containing the model to load
parentParent entity handle
BBDECL Node* BBCALL xCreateCube ( Entity *  parent = NULL)

Creates a cube mesh/entity and returns its handle.

The cube will extend from -1, -1, -1 to +1, +1, +1. The optional parent parameter allows you to specify a parent entity for the cube so that when the parent is moved the child cube will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent. Specifying a parent entity will still result in the cube being created at position 0, 0, 0 rather than at the parent entity's position. Creation of cubes, cylinders and cones are a great way of getting scenes set up quickly, as they can act as placeholders for more complex pre-modeled meshes later on in program development.

Parameters:
parentParent entity handle
BBDECL Node* BBCALL xCreateSphere ( int  segments = 16,
Entity *  parent = NULL 
)

Creates a sphere mesh/entity and returns its handle.

The sphere will be centred at 0, 0, 0 and will have a radius of 1. The segments value must be in the range 2-100 inclusive

Example segments values:

8: 224 polygons - bare minimum amount of polygons for a sphere

16: 960 polygons - smooth looking sphere at medium-high distances

32: 3968 polygons - smooth sphere at close distances

The parent parameter allows you to specify a parent entity for the sphere so that when the parent is moved the child sphere will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent. Specifying a parent entity will still result in the sphere being created at position 0, 0, 0 rather than at the parent entity's position.

Parameters:
segmentsSphere detail
parentParent entity handle
BBDECL Node* BBCALL xCreateCylinder ( int  segments = 16,
bool  solid = true,
Entity *  parent = NULL 
)

Creates a cylinder mesh/entity and returns its handle.

The cylinder will be centred at 0, 0, 0 and will have a radius of 1. The segments value must be in the range 3-100 inclusive. Example segments values (solid mesh):

3: 8 polygons - a prism

8: 28 polygons - bare minimum amount of polygons for a cylinder

16: 60 polygons - smooth cylinder at medium-high distances

32: 124 polygons - smooth cylinder at close distances

The optional parent parameter allows you to specify a parent entity for the cylinder so that when the parent is moved the child cylinder will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent. Specifying a parent entity will still result in the cylinder being created at position 0, 0, 0 rather than at the parent entity's position.

Parameters:
segmentsCylinder detail
solidTrue for a cone with a base, false for a cone without a base
parentParent entity handle
BBDECL Node* BBCALL xCreateTorus ( int  segments = 16,
float  R = 1.0f,
float  r_tube = 0.025f,
Entity *  parent = NULL 
)

Creates a torus mesh/entity and returns its handle.

The torus will be centred at 0, 0, 0 and will have a radius of 1. The segments value must be in the range 3-100 inclusive. The optional parent parameter allows you to specify a parent entity for the cylinder so that when the parent is moved the child cylinder will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent. Specifying a parent entity will still result in the torus being created at position 0, 0, 0 rather than at the parent entity's position.

Parameters:
segmentsTorus detail
RThe distance from the center of the tube to the center of the torus
r_tubeThe radius of the tube
parentParent entity handle
BBDECL Node* BBCALL xCreateCone ( int  segments = 16,
bool  solid = true,
Entity *  parent = NULL 
)

Creates a cone mesh/entity and returns its handle.

The cone will be centred at 0, 0, 0 and the base of the cone will have a radius of 1. The segments value must be in the range 3-100 inclusive. Example segments values (solid mesh):

4: 6 polygons - a pyramid

8: 14 polygons - bare minimum amount of polygons for a cone

16: 30 polygons - smooth cone at medium-high distances

32: 62 polygons - smooth cone at close distances

The optional parent parameter allows you to specify a parent entity for the cone so that when the parent is moved the child cone will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent. Specifying a parent entity will still result in the cone being created at position 0, 0, 0 rather than at the parent entity's position.

Parameters:
segmentsCone detail
solidTrue for a cone with a base, false for a cone without a base
parentParent entity handle
BBDECL Entity* BBCALL xCopyMesh ( Entity *  entity,
Entity *  parent = NULL 
)

Creates a copy of a mesh and returns the newly-created mesh's handle.

The difference between xCopyMesh() and xCopyEntity() is that xCopyMesh() performs a 'deep' copy of a mesh.

Parameters:
entityEntity handle
parentParent entity handle
BBDECL void BBCALL xAddMesh ( Entity *  source,
Entity *  destination 
)

Adds the source mesh to the destination mesh.

xAddMesh() works best with meshes that have previously only had mesh commands used with them. So if you want to manipulate a mesh before adding it to another mesh, make sure you use xScaleMesh(), xPositionMesh(), xPaintMesh() etc rather than xScaleEntity(), xPositionEntity(), xEntityTexture() etc before using xAddMesh(). However, something to be aware of when using commands such as xRotateMesh is that all mesh commands work from a global origin of (0, 0, 0). Therefore it is generally a good idea to scale and rotate a mesh before positioning it, otherwise your mesh could end up in unexpected positions. Also, when using xAddMesh(), the origin of the new all-in-one mesh will be set at (0, 0, 0). After using xAddMesh(), the original 'src' mesh will still exist, therefore use xFreeEntity() to delete it if you wish to do so.

Parameters:
sourceSource mesh
destinationDestination mesh
BBDECL void BBCALL xFlipMesh ( Entity *  entity)

Flips all the triangles in a mesh.

This is useful for a couple of reasons. Firstly though, it is important to understand a little bit of the theory behind 3D graphics. A 3D triangle is represented by three points; only when these points are presented to the viewer in a clockwise-fashion is the triangle visible. So really, triangles only have one side. Normally, for example in the case of a sphere, a model's triangles face the inside of the model, so it doesn't matter that you can't see them. However, what about if you wanted to use the sphere as a huge sky for your world, i.e. so you only needed to see the inside? In this case you would just use xFlipMesh(). Another use for xFlipMesh() is to make objects two-sided, so you can see them from the inside and outside if you can't already. In this case, you can copy the original mesh using xCopyEntity(), specifying the original mesh as the parent, and flip it using xFlipMesh(). You will now have two meshes occupying the same space - this will make it double-sided, but beware, it will also double the polygon count. The above technique is worth trying when an external modelling program has exported a model in such a way that some of the triangles appear to be missing.

Parameters:
entityEntity handle
BBDECL void BBCALL xPaintMesh ( Entity *  entity,
Brush *  brush 
)

Paints a mesh with a brush.

This has the effect of instantly altering the visible appearance of the mesh, assuming the brush's properties are different to what was was applied to the surface before. The reason for using xPaintMesh() to apply specific properties to a mesh using a brush rather than just using xEntityTexture(), xEntityColor(), xEntityShininess() etc, is that you can pre-define one brush, and then paint meshes over and over again using just the one command rather than lots of separate ones.

Parameters:
entityEntity handle
brushBrush handle
BBDECL void BBCALL xFitMesh ( Entity *  entity,
float  x,
float  y,
float  z,
float  width,
float  height,
float  depth,
bool  uniform = false 
)

Scales and translates all vertices of a mesh so that the mesh occupies the specified box.

Do not use a width, height or depth value of 0.0, otherwise all mesh data will be destroyed and your mesh will not be displayed. Use a value of 0.001 instead for a flat mesh along one axis.

Parameters:
entityMesh handle
xx position of mesh
yy position of mesh
zz position of mesh
widthWidth of mesh
heightHeight of mesh
depthDepth of mesh
uniformIf true, the mesh will be scaled by the same amounts in x, y and z, so will not be distorted
BBDECL float BBCALL xMeshWidth ( Entity *  entity,
bool  recursive = false 
)

Returns the width of a mesh.

This is calculated by the actual vertex positions and so the scale of the entity (set by xScaleEntity()) will not have an effect on the resultant width. Mesh operations, on the other hand, will effect the result.

Parameters:
entityEntity handle
recursiveIf true - will compute bounding box width for all heirarhy
BBDECL float BBCALL xMeshHeight ( Entity *  entity,
bool  recursive = false 
)

Returns the height of a mesh.

This is calculated by the actual vertex positions and so the scale of the entity (set by xScaleEntity()) will not have an effect on the resultant height. Mesh operations, on the other hand, will effect the result.

Parameters:
entityEntity handle
recursiveIf true - will compute bounding box height for all heirarhy
BBDECL float BBCALL xMeshDepth ( Entity *  entity,
bool  recursive = false 
)

Returns the depth of a mesh.

This is calculated by the actual vertex positions and so the scale of the entity (set by xScaleEntity()) will not have an effect on the resultant depth. Mesh operations, on the other hand, will effect the result.

Parameters:
entityEntity handle
recursiveIf true - will compute bounding box depth for all heirarhy
BBDECL void BBCALL xScaleMesh ( Entity *  entity,
float  x,
float  y,
float  z 
)

Scales all vertices of a mesh by the specified scaling factors.

Unlike xScaleEntity(), xScaleMesh() actually modifies the actual mesh structure. So whereas using xScaleEntity(2, 2, 2) would only double the size of an entity the first time it was used, xScaleMesh(2, 2, 2) will double the size of the mesh every time it is used. This is because xScaleEntity() scales an entity based on a fixed mesh structure, whereas xScaleMesh() actually modifies the mesh structure itself.

Parameters:
entityEntity handle
xx scale of mesh
yy scale of mesh
zz scale of mesh
BBDECL void BBCALL xRotateMesh ( Entity *  entity,
float  x,
float  y,
float  z 
)

Rotates all vertices of a mesh by the specified rotation.

Unlike xRotateEntity(), xRotateMesh() actually modifies the actual mesh structure. So whereas using xRotateEntity(0, 45, 0) would only rotate an entity by 45 degrees the first time it was used, xRotateMesh(0, 45, 0) will rotate the mesh every time it is used. This is because xRotateEntity() rotates an entity based on a fixed mesh structure, whereas xRotateMesh() actually modifies the mesh structure itself

Parameters:
entityEntity handle
xPitch of mesh
yYaw of mesh
zRoll of mesh
BBDECL void BBCALL xPositionMesh ( Entity *  entity,
float  x,
float  y,
float  z 
)

Moves all vertices of a mesh.

Unlike xPositionEntity(), xPositionMesh() modifies the actual mesh structure. So whereas using xPositionEntity(0, 0, 1) would only move an entity by one unit the first time it was used, xPositionMesh(0, 0, 1) will move the mesh by one unit every time it is used. This is because xPositionEntity() positions an entity based on a fixed mesh structure, whereas xPositionMesh() actually modifies the mesh structure itself.

Parameters:
entityEntity handle
xx position of mesh
yy position of mesh
zz position of mesh
BBDECL void BBCALL xUpdateNormals ( Entity *  entity)

Recalculates all normals, tangents and binormals in a mesh.

This is necessary for correct lighting if you have not set surface normals using xVertexNormal() commands.

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

Recalculates all normals in a mesh.

This is necessary for correct lighting if you have not set surface normals using xVertexNormal() commands.

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

Recalculates all tangents and binormals in a mesh.

This is necessary for correct lighting if you have not set surface normals using xVertexBinormal() and xVertexTangent()commands.

Parameters:
entityEntity handle
BBDECL int BBCALL xMeshesBBIntersect ( Entity *  entity1,
Entity *  entity2 
)

Returns true if the specified meshes bounding boxes are currently intersecting.

Deprecated:
Use xEntitiesBBIntersect() instead.
Parameters:
entity1First entity handle
entity2Second entity handle
BBDECL int BBCALL xMeshesIntersect ( Entity *  entity1,
Entity *  entity2 
)

Returns true if the specified meshes are currently intersecting.

Parameters:
entity1First entity handle
entity2Second entity handle
BBDECL float* BBCALL xGetMeshVB ( Entity *  entity)

Returns pointer to mesh vertices.

Actually it's a only copy of original vertex buffer, you can use it for phisics engines, such as PhysX for making trimesh and so one. You must delete created buffers when it's no more needed by xDeteleMeshVB()

Parameters:
entityEntity handle
BBDECL int* BBCALL xGetMeshIB ( Entity *  entity)

Returns a pointer to mesh indeices.

Actually it's only a copy of original index buffer, you can use it for phisics engines, such as PhysX for making trimesh and so one. You must delete created buffers when it's no more needed by xDeteleMeshIB()

Parameters:
entityEntity handle
BBDECL int BBCALL xGetMeshVBSize ( Entity *  entity)

Returns a size of mesh vertices buffer.

Parameters:
entityEntity handle
BBDECL int BBCALL xGetMeshIBSize ( Entity *  entity)

Returns a size of mesh indeices buffer.

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

Deletes an allocated array for mesh verticies.

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

Deletes an allocated array for mesh indecies.

Parameters:
entityEntity handle
BBDECL int BBCALL xCountSurfaces ( Entity *  entity)

Returns the number of surfaces in a mesh.

Surfaces are sections of mesh. A mesh may contain only one section, or very many

Parameters:
entityEntity handle
BBDECL Surface* BBCALL xGetSurface ( Entity *  entity,
int  index 
)

Returns the handle of the surface attached to the specified mesh and with the specified index number.

Index should be in the range [0; xCountSurfaces() - 1] You need to 'get a surface', i.e. get its handle, in order to be able to then use that particular surface with other commands.

Parameters:
entityentity handle
indexIndex of surface
BBDECL Entity* BBCALL xCreatePivot ( Entity *  parent = NULL)

Creates a pivot entity.

A pivot entity is an invisible point in 3D space that's main use is to act as a parent entity to other entities. The pivot can then be used to control lots of entities at once, or act as new centre of rotation for other entities. To enforce this relationship; use xEntityParent() or make use of the optional parent entity parameter available with all entity load/creation commands. Indeed, this parameter is also available with the xCreatePivot() command if you wish for the pivot to have a parent entity itself.

Parameters:
parentParent entity handle
BBDECL Surface* BBCALL xFindSurface ( Node *  entity,
Brush *  brush 
)

Attempts to find a surface attached to the specified mesh and created with the specified brush.

Returns the surface handle if found or 0 if not.

Parameters:
entityEntity handle
brushBrush handle
BBDECL Node* BBCALL xCreatePoly ( int  sides,
Entity *  parent = NULL 
)

Creates a polygon.

Parameters:
sidesIf true two-sided polygon will be created
parentParent entity handle
BBDECL void BBCALL xMeshSingleSurface ( Node *  entity)

Converts an entity with several surfaces into an entity with a single surface. All textures of this entity become ignorable.

Parameters:
entityEntity handle (should be a mesh).
BBDECL int BBCALL xSaveMesh ( Entity *  entity,
const char *  path 
)

Saves mesh hierarhy into the .FBX file.

Parameters:
entityEntity handle
pathFile path to save
BBDECL void BBCALL xLightMesh ( Entity *  entity,
int  red,
int  green,
int  blue,
float  range = 0.0f,
float  lightX = 0.0f,
float  lightY = 0.0f,
float  lightZ = 0.0f 
)

Performs a 'fake' lighting operation on a mesh.

Parameters:
entityEntity handle
redRed light value
greenGreen light value
blueBlue light value
rangeLight range
lightXx-coordinate of light
lightYy-coordinate of light
lightZz-coordinate of light
BBDECL void BBCALL xMeshPrimitiveType ( Entity *  entity,
int  ptype 
)

Sets the type of primitive to render.

Parameters:
entityEntity handle.
ptypeType of primitive, see 'The types of primitive for rendering of meshes and surfaces' for more information.