![]() |
Xors3d Engine
|
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. |
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
parent | Parent 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.
path | Name of the file containing the model to load |
parent | Parent entity handle |
BBDECL Entity* BBCALL xLoadMeshWithChild | ( | const char * | path, |
Entity * | parent = NULL |
||
) |
Loads a static mesh with saving hierarchy.
path | String containing filename of mesh file |
parent | Parent 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.
path | Name of the file containing the model to load |
parent | Parent 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.
parent | Parent 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.
segments | Sphere detail |
parent | Parent 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.
segments | Cylinder detail |
solid | True for a cone with a base, false for a cone without a base |
parent | Parent 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.
segments | Torus detail |
R | The distance from the center of the tube to the center of the torus |
r_tube | The radius of the tube |
parent | Parent 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.
segments | Cone detail |
solid | True for a cone with a base, false for a cone without a base |
parent | Parent 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.
entity | Entity handle |
parent | Parent 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.
source | Source mesh |
destination | Destination 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.
entity | Entity 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.
entity | Entity handle |
brush | Brush 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.
entity | Mesh handle |
x | x position of mesh |
y | y position of mesh |
z | z position of mesh |
width | Width of mesh |
height | Height of mesh |
depth | Depth of mesh |
uniform | If 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.
entity | Entity handle |
recursive | If 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.
entity | Entity handle |
recursive | If 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.
entity | Entity handle |
recursive | If 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.
entity | Entity handle |
x | x scale of mesh |
y | y scale of mesh |
z | z 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
entity | Entity handle |
x | Pitch of mesh |
y | Yaw of mesh |
z | Roll 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.
entity | Entity handle |
x | x position of mesh |
y | y position of mesh |
z | z 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.
entity | Entity 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.
entity | Entity 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.
entity | Entity handle |
BBDECL int BBCALL xMeshesBBIntersect | ( | Entity * | entity1, |
Entity * | entity2 | ||
) |
Returns true if the specified meshes bounding boxes are currently intersecting.
entity1 | First entity handle |
entity2 | Second entity handle |
BBDECL int BBCALL xMeshesIntersect | ( | Entity * | entity1, |
Entity * | entity2 | ||
) |
Returns true if the specified meshes are currently intersecting.
entity1 | First entity handle |
entity2 | Second 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()
entity | Entity 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()
entity | Entity handle |
BBDECL int BBCALL xGetMeshVBSize | ( | Entity * | entity | ) |
Returns a size of mesh vertices buffer.
entity | Entity handle |
BBDECL int BBCALL xGetMeshIBSize | ( | Entity * | entity | ) |
Returns a size of mesh indeices buffer.
entity | Entity handle |
BBDECL void BBCALL xDeleteMeshVB | ( | Entity * | entity | ) |
Deletes an allocated array for mesh verticies.
entity | Entity handle |
BBDECL void BBCALL xDeleteMeshIB | ( | Entity * | entity | ) |
Deletes an allocated array for mesh indecies.
entity | Entity 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
entity | Entity 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.
entity | entity handle |
index | Index 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.
parent | Parent 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.
entity | Entity handle |
brush | Brush handle |
BBDECL Node* BBCALL xCreatePoly | ( | int | sides, |
Entity * | parent = NULL |
||
) |
Creates a polygon.
sides | If true two-sided polygon will be created |
parent | Parent 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.
entity | Entity handle (should be a mesh). |
BBDECL int BBCALL xSaveMesh | ( | Entity * | entity, |
const char * | path | ||
) |
Saves mesh hierarhy into the .FBX file.
entity | Entity handle |
path | File 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.
entity | Entity handle |
red | Red light value |
green | Green light value |
blue | Blue light value |
range | Light range |
lightX | x-coordinate of light |
lightY | y-coordinate of light |
lightZ | z-coordinate of light |
BBDECL void BBCALL xMeshPrimitiveType | ( | Entity * | entity, |
int | ptype | ||
) |
Sets the type of primitive to render.
entity | Entity handle. |
ptype | Type of primitive, see 'The types of primitive for rendering of meshes and surfaces' for more information. |