Xors3d Engine
Surfaces

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, bool vertices=true, bool 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 void BBCALL xSurfaceAlpha (Surface *surface, float alpha)
 Sets the alpha level of a surface.
BBDECL void BBCALL xSurfaceAlphaFunc (Surface *surface, int alphaFunc)
 Sets the alpha test function of a surface.
BBDECL void BBCALL xSurfaceAlphaRef (Surface *surface, int alphaRef)
 Sets the reference alpha value of a surface.
BBDECL void BBCALL xSurfaceBlend (Surface *surface, int blendMode)
 Sets the blending mode of a surface.
BBDECL void BBCALL xSurfaceColor (Surface *surface, int red, int green, int blue)
 Sets the diffuse color of a surface.
BBDECL void BBCALL xSurfaceFX (Surface *surface, int fxFlags)
 Sets miscellaneous effects for a surface.
BBDECL void BBCALL xSurfacePrimitiveType (Surface *surface, int ptype)
 Sets the type of primitive to render.
BBDECL void BBCALL xSurfaceShininess (Surface *surface, float shininess)
 Sets the specular shininess of a surface.
BBDECL void BBCALL xSurfaceTexture (Surface *surface, Texture *texture, int frame, int index)
 Applies a texture to a surface.
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 (useful 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,
bool  vertices = true,
bool  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
BBDECL void BBCALL xSurfacePrimitiveType ( Surface *  surface,
int  ptype 
)

Sets the type of primitive to render.

Parameters:
surfaceSurface handle.
ptypeType of primitive, see 'The types of primitive for rendering of meshes and surfaces' for more information.
BBDECL void BBCALL xSurfaceTexture ( Surface *  surface,
Texture *  texture,
int  frame,
int  index 
)

Applies a texture to a surface.

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:
surfaceSurface handle
textureTexture handle
frameFrame of texture
indexIndex number of texture. Should be in the range [0; 7].
BBDECL void BBCALL xSurfaceColor ( Surface *  surface,
int  red,
int  green,
int  blue 
)

Sets the diffuse color of a surface.

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

Parameters:
surfaceSurface handle
redRed value of surface color
greenGreen value of surface color
blueBlue value of surface color
BBDECL void BBCALL xSurfaceAlpha ( Surface *  surface,
float  alpha 
)

Sets the alpha level of a surface.

The 'alpha' value should be in a floating point value in the range [0.0; 1.0]. The default surface alpha setting is 1.0. The alpha level is how transparent a surface is. A value of 1.0 will mean the surface is opaque. A value of 0.0 will mean the surface 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:
surfaceSurface handle
alphaAlpha level of entity
BBDECL void BBCALL xSurfaceShininess ( Surface *  surface,
float  shininess 
)

Sets the specular shininess of a surface.

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:
surfaceSurface handle
shininessShininess of entity
BBDECL void BBCALL xSurfaceBlend ( Surface *  surface,
int  blendMode 
)

Sets the blending mode of a surface.

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 surfaces/brushes (where applicable) alpha value and its color compentent multiplied by the surfaces/brushes colour. This is the RGBA which will then be blended into the background pixel, and how this is done depends on the xSurfaceBlend() value.

Parameters:
surfaceSurface handle
blendModeBlend mode. See 'Blending modes' for more information
BBDECL void BBCALL xSurfaceFX ( Surface *  surface,
int  fxFlags 
)

Sets miscellaneous effects for a surface.

Flags can be added to combine two or more effects.

Parameters:
surfaceSurface handle
fxFlagsEffects flags. See 'FX flags' for more information
BBDECL void BBCALL xSurfaceAlphaRef ( Surface *  surface,
int  alphaRef 
)

Sets the reference alpha value of a surface.

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 xSurfaceAlphaFunc()). This is useful for varying smoothness of edges of surfaces with masked textures (e.g. grass, leaves, clouds).

Parameters:
surfaceSurface handle
alphaRefReference alpha value
BBDECL void BBCALL xSurfaceAlphaFunc ( Surface *  surface,
int  alphaFunc 
)

Sets the alpha test function of a surface.

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:
surfaceSurface handle
alphaFuncAlpha test function. See 'Compare functions' for more infomation.