Functions

Surfaces
[Command reference]

Functions

BBDECL int BBCALL xAddTriangle (Surface *surface, int v0, int v1, int v2)
 Adds a triangle to a surface and returns the triangle's index number, starting from 0.
BBDECL int BBCALL xAddVertex (Surface *surface, float x, float y, float z, float u=0.0f, float v=0.0f, float w=0.0f)
 Adds a vertex to the specified surface and returns the vertices index number, starting from 0.
BBDECL void BBCALL xClearSurface (Surface *surface, int vertices=true, int triangles=true)
 Removes all vertices and/or triangles from a surface.
BBDECL int BBCALL xCountTriangles (Surface *surface)
 Returns the number of triangles in a surface.
BBDECL int BBCALL xCountVertices (Surface *surface)
 Returns the number of vertices in a surface.
BBDECL Surface *BBCALL xCreateSurface (Entity *entity, Brush *brush=NULL, bool dynamic=false)
 Creates a surface attached to a mesh and returns the surface's handle.
BBDECL void BBCALL xFreeSurface (Surface *surface)
 Frees up a surface.
BBDECL Brush *BBCALL xGetSurfaceBrush (Surface *surface)
 Returns a brush with the same properties as is applied to the specified mesh surface.
BBDECL Texture *BBCALL xGetSurfaceTexture (Surface *surface, int index=0)
 Return surface texture from specified index.
BBDECL void BBCALL xPaintSurface (Surface *surface, Brush *brush)
 Paints a surface with a brush.
BBDECL int BBCALL xTriangleVertex (Surface *surface, int triangle, int corner)
 Returns the vertex of a triangle corner.
BBDECL float BBCALL xVertexAlpha (Surface *surface, int vertex)
 Returns the alpha component of a vertices color, set using xVertexColor()
BBDECL void BBCALL xVertexBinormal (Surface *surface, int vertex, float x, float y, float z)
 Sets the binormal of an existing vertex.
BBDECL float BBCALL xVertexBlue (Surface *surface, int vertex)
 Returns the blue component of a vertices color.
BBDECL float BBCALL xVertexBX (Surface *surface, int vertex)
 Returns the x component of a vertex binormal.
BBDECL float BBCALL xVertexBY (Surface *surface, int vertex)
 Returns the y component of a vertex binormal.
BBDECL float BBCALL xVertexBZ (Surface *surface, int vertex)
 Returns the z component of a vertex binormal.
BBDECL void BBCALL xVertexColor (Surface *surface, int vertex, int red, int green, int blue, float alpha=1.0f)
 Sets the color of an existing vertex.
BBDECL void BBCALL xVertexCoords (Surface *surface, int vertex, float x, float y, float z)
 Sets the geometric coordinates of an existing vertex.
BBDECL float BBCALL xVertexGreen (Surface *surface, int vertex)
 Returns the green component of a vertices color.
BBDECL void BBCALL xVertexNormal (Surface *surface, int vertex, float x, float y, float z)
 Sets the normal of an existing vertex.
BBDECL float BBCALL xVertexNX (Surface *surface, int vertex)
 Returns the x component of a vertex normal.
BBDECL float BBCALL xVertexNY (Surface *surface, int vertex)
 Returns the y component of a vertex normal.
BBDECL float BBCALL xVertexNZ (Surface *surface, int vertex)
 Returns the z component of a vertex normal.
BBDECL float BBCALL xVertexRed (Surface *surface, int vertex)
 Returns the red component of a vertices color.
BBDECL void BBCALL xVertexTangent (Surface *surface, int vertex, float x, float y, float z)
 Sets the tangent of an existing vertex.
BBDECL void BBCALL xVertexTexCoords (Surface *surface, int vertex, float u, float v, float w=1.0f, int textureSet=0)
 Sets the texture coordinates of an existing vertex.
BBDECL float BBCALL xVertexTX (Surface *surface, int vertex)
 Returns the x component of a vertex tangent.
BBDECL float BBCALL xVertexTY (Surface *surface, int vertex)
 Returns the y component of a vertex tangent.
BBDECL float BBCALL xVertexTZ (Surface *surface, int vertex)
 Returns the z component of a vertex tangent.
BBDECL float BBCALL xVertexU (Surface *surface, int vertex, int textureSet=0)
 Returns the texture u coordinate of a vertex.
BBDECL float BBCALL xVertexV (Surface *surface, int vertex, int textureSet=0)
 Returns the texture v coordinate of a vertex.
BBDECL float BBCALL xVertexW (Surface *surface, int vertex, int textureSet=0)
 Returns the texture w coordinate of a vertex.
BBDECL float BBCALL xVertexX (Surface *surface, int vertex)
 Returns the x coordinate of a vertex.
BBDECL float BBCALL xVertexY (Surface *surface, int vertex)
 Returns the y coordinate of a vertex.
BBDECL float BBCALL xVertexZ (Surface *surface, int vertex)
 Returns the z coordinate of a vertex.

Function Documentation

BBDECL Surface* BBCALL xCreateSurface ( Entity *  entity,
Brush *  brush = NULL,
bool  dynamic = false 
)

Creates a surface attached to a mesh and returns the surface's handle.

Surfaces are sections of mesh which are then used to attach triangles to. You must have at least one surface per mesh in order to create a visible mesh, however you can use as many as you like. Splitting a mesh up into lots of sections allows you to affect those sections individually, which can be a lot more useful than if all the surfaces are combined into just one.

Parameters:
entityEntity handle
brushBrush handle
dynamicIf true - dynamic surface will be created. It is faster for editing, but slower for rendering (usefull for particle systems and others dynamic meshes).
BBDECL Brush* BBCALL xGetSurfaceBrush ( Surface *  surface )

Returns a brush with the same properties as is applied to the specified mesh surface.

If this command does not appear to be returning a valid brush, try using xGetEntityBrush() instead. Remember, xGetSurfaceBrush() actually creates a new brush so don't forget to free it afterwards using xFreeBrush() to prevent memory leaks. Once you have got the brush handle from a surface, you can use xGetBrushTexture() and xTextureName() to get the details of what texture(s) are applied to the brush.

Parameters:
surfaceSurface handle
BBDECL int BBCALL xAddVertex ( Surface *  surface,
float  x,
float  y,
float  z,
float  u = 0.0f,
float  v = 0.0f,
float  w = 0.0f 
)

Adds a vertex to the specified surface and returns the vertices index number, starting from 0.

'x', 'y', 'z' are the geometric coordinates of the vertex, and 'u', 'v', 'w' are texture mapping coordinates. A vertex is a point in 3D space which is used to connect edges of a triangle together. Without any vertices, you can't have any triangles. At least three vertices are needed to create one triangle; one for each corner. The optional 'u', 'v' and 'w' parameters allow you to specify texture coordinates for a vertex, which will determine how any triangle created using those vertices will be texture mapped. The 'u', 'v' and 'w' parameters specified will take effect on both texture coordinate sets (0 and 1). This works on the following basis:

The top left of an image has the uv coordinates 0.0, 0.0.

The top right has coordinates 1.0, 0.0

The bottom right is 1.0, 1.0

The bottom left 0.0, 1.0

Thus, uv coordinates for a vertex correspond to a point in the image. For example, coordinates 0.9, 0.1 would be near the upper right corner of the image. So now imagine you have a normal equilateral triangle. By assigning the bottom left vertex a uv coordinate of 0.0, 0.0, the bottom right a coordinate of 1.0, 0.0 and the top centre 0.5, 1.0, this will texture map the triangle with an image that fits it. When adding a vertex its default color is 255, 255, 255, 255.

Parameters:
surfaceSurface handle
xx coordinate of vertex
yy coordinate of vertex
zz coordinate of vertex
uu texture coordinate of vertex
vv texture coordinate of vertex
ww texture coordinate of vertex - not used, included for future expansion
BBDECL int BBCALL xAddTriangle ( Surface *  surface,
int  v0,
int  v1,
int  v2 
)

Adds a triangle to a surface and returns the triangle's index number, starting from 0.

The v0, v1 and v2 parameters are the index numbers of the vertices created using xAddVertex(). Depending on how the vertices are arranged, then the triangle will only be visible from a certain side. Imagine that a triangle's vertex points are like dot-to-dot pattern, each numbered v0, v1, v2. If these dots, starting from v0, through to V2, form a clockwise pattern relative to the viewer, then the triangle will be visible. If these dots form an anti-clockwise pattern relative to the viewer, then the triangle will not be visible. The reason for having one-sided triangles is that it reduces the amount of triangles that need to be rendered when one side faces the side of an object which won't be seen (such as the inside of a snooker ball). However, if you wish for a triangle to be two-sided, then you can either create two triangles, using the same set of vertex numbers for both but assigning them in opposite orders, or you can use xCopyEntity() and xFlipMesh() together.

Parameters:
surfaceSurface handle
v0Index number of first vertex of triangle
v1Index number of second vertex of triangle
v2Index number of third vertex of triangle
See also:
xAddVertex()
BBDECL void BBCALL xVertexCoords ( Surface *  surface,
int  vertex,
float  x,
float  y,
float  z 
)

Sets the geometric coordinates of an existing vertex.

This is the command used to perform what is commonly referred to as 'dynamic mesh deformation'. It will reposition a vertex so that all the triangle edges connected to it, will move also. This will give the effect of parts of the mesh suddenly deforming.

Parameters:
surfaceSurface handle
vertexVertex index
xx position of vertex
yy position of vertex
zz position of vertex
BBDECL void BBCALL xVertexNormal ( Surface *  surface,
int  vertex,
float  x,
float  y,
float  z 
)

Sets the normal of an existing vertex.

Parameters:
surfaceSurface handle
vertexVertex index
xNormal x of vertex
yNormal y of vertex
zNormal z of vertex
BBDECL void BBCALL xVertexTangent ( Surface *  surface,
int  vertex,
float  x,
float  y,
float  z 
)

Sets the tangent of an existing vertex.

Parameters:
surfaceSurface handle
vertexVertex index
xTangent x of vertex
yTangent y of vertex
zTangent z of vertex
BBDECL void BBCALL xVertexBinormal ( Surface *  surface,
int  vertex,
float  x,
float  y,
float  z 
)

Sets the binormal of an existing vertex.

Parameters:
surfaceSurface handle
vertexVertex index
xBinormal x of vertex
yBinormal y of vertex
zBinormal z of vertex
BBDECL void BBCALL xVertexColor ( Surface *  surface,
int  vertex,
int  red,
int  green,
int  blue,
float  alpha = 1.0f 
)

Sets the color of an existing vertex.

Parameters:
surfaceSurface handle
vertexVertex index
redRed value of vertex color
greenGreen value of vertex color
blueBlue value of vertex color
alphaAlpha value of vertex color
BBDECL void BBCALL xVertexTexCoords ( Surface *  surface,
int  vertex,
float  u,
float  v,
float  w = 1.0f,
int  textureSet = 0 
)

Sets the texture coordinates of an existing vertex.

Parameters:
surfaceSurface handle
vertexVertex index
uu coordinate of vertex
vv coordinate of vertex
ww coordinate of vertex
textureSetTexture coodrinates set. Should be set to 0 or 1.
BBDECL int BBCALL xCountVertices ( Surface *  surface )

Returns the number of vertices in a surface.

Parameters:
surfaceSurface handle
BBDECL float BBCALL xVertexX ( Surface *  surface,
int  vertex 
)

Returns the x coordinate of a vertex.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexY ( Surface *  surface,
int  vertex 
)

Returns the y coordinate of a vertex.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexZ ( Surface *  surface,
int  vertex 
)

Returns the z coordinate of a vertex.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexNX ( Surface *  surface,
int  vertex 
)

Returns the x component of a vertex normal.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexNY ( Surface *  surface,
int  vertex 
)

Returns the y component of a vertex normal.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexNZ ( Surface *  surface,
int  vertex 
)

Returns the z component of a vertex normal.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexTX ( Surface *  surface,
int  vertex 
)

Returns the x component of a vertex tangent.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexTY ( Surface *  surface,
int  vertex 
)

Returns the y component of a vertex tangent.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexTZ ( Surface *  surface,
int  vertex 
)

Returns the z component of a vertex tangent.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexBX ( Surface *  surface,
int  vertex 
)

Returns the x component of a vertex binormal.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexBY ( Surface *  surface,
int  vertex 
)

Returns the y component of a vertex binormal.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexBZ ( Surface *  surface,
int  vertex 
)

Returns the z component of a vertex binormal.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexU ( Surface *  surface,
int  vertex,
int  textureSet = 0 
)

Returns the texture u coordinate of a vertex.

Parameters:
surfaceSurface handle
vertexVertex index
textureSetTexture coodrinates set. Should be set to 0 or 1.
BBDECL float BBCALL xVertexV ( Surface *  surface,
int  vertex,
int  textureSet = 0 
)

Returns the texture v coordinate of a vertex.

Parameters:
surfaceSurface handle
vertexVertex index
textureSetTexture coodrinates set. Should be set to 0 or 1.
BBDECL float BBCALL xVertexW ( Surface *  surface,
int  vertex,
int  textureSet = 0 
)

Returns the texture w coordinate of a vertex.

Parameters:
surfaceSurface handle
vertexVertex index
textureSetTexture coodrinates set. Should be set to 0 or 1.
BBDECL float BBCALL xVertexRed ( Surface *  surface,
int  vertex 
)

Returns the red component of a vertices color.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexGreen ( Surface *  surface,
int  vertex 
)

Returns the green component of a vertices color.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexBlue ( Surface *  surface,
int  vertex 
)

Returns the blue component of a vertices color.

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL float BBCALL xVertexAlpha ( Surface *  surface,
int  vertex 
)

Returns the alpha component of a vertices color, set using xVertexColor()

Parameters:
surfaceSurface handle
vertexVertex index
BBDECL int BBCALL xTriangleVertex ( Surface *  surface,
int  triangle,
int  corner 
)

Returns the vertex of a triangle corner.

Parameters:
surfaceSurface handle
triangleTriangle index
cornerCorner of triangle. Should be 0, 1 or 2.
BBDECL int BBCALL xCountTriangles ( Surface *  surface )

Returns the number of triangles in a surface.

Parameters:
surfaceSurface handle
BBDECL void BBCALL xPaintSurface ( Surface *  surface,
Brush *  brush 
)

Paints a surface with a brush.

This has the effect of instantly altering the visible appearance of that particular surface, i.e. section of mesh, assuming the brush's properties are different to what was applied to the surface before.

Parameters:
surfaceSurface handle
brushBrush handle
BBDECL void BBCALL xClearSurface ( Surface *  surface,
int  vertices = true,
int  triangles = true 
)

Removes all vertices and/or triangles from a surface.

This is useful for clearing sections of mesh. The results will be instantly visible. After clearing a surface, you may wish to add vertices and triangles to it again but with a slightly different polygon count for dynamic level of detail (LOD).

Parameters:
surfaceSurface handle
verticesTrue to remove all vertices from the specified surface, false not to
trianglesTrue to remove all triangles from the specified surface, false not to
BBDECL Texture* BBCALL xGetSurfaceTexture ( Surface *  surface,
int  index = 0 
)

Return surface texture from specified index.

Parameters:
surfaceSurface handle
indexTexture layer index in range [0; 7]
BBDECL void BBCALL xFreeSurface ( Surface *  surface )

Frees up a surface.

Parameters:
surfaceSurface handle

Xors3d Engine, Copyright © 2009-2011, www.xors3d.com Generated by Doxygen