Xors3d Engine
Surfaces

Functions

int 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.
int 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.
void xClearSurface (Surface *surface, bool vertices=true, bool triangles=true)
 Removes all vertices and/or triangles from a surface.
int xCountTriangles (Surface *surface)
 Returns the number of triangles in a surface.
int xCountVertices (Surface *surface)
 Returns the number of vertices in a surface.
Surface * xCreateSurface (Entity *entity, Brush *brush=NULL, bool dynamic=false)
 Creates a surface attached to a mesh and returns the surface's handle.
void xFreeSurface (Surface *surface)
 Frees up a surface.
Brush * xGetSurfaceBrush (Surface *surface)
 Returns a brush with the same properties as is applied to the specified mesh surface.
Texture * xGetSurfaceTexture (Surface *surface, int index=0)
 Return surface texture from specified index.
void xPaintSurface (Surface *surface, Brush *brush)
 Paints a surface with a brush.
void xSurfaceAlpha (Surface *surface, float alpha)
 Sets the alpha level of a surface.
void xSurfaceAlphaFunc (Surface *surface, int alphaFunc)
 Sets the alpha test function of a surface.
void xSurfaceAlphaRef (Surface *surface, int alphaRef)
 Sets the reference alpha value of a surface.
void xSurfaceBlend (Surface *surface, int blendMode)
 Sets the blending mode of a surface.
void xSurfaceColor (Surface *surface, int red, int green, int blue)
 Sets the diffuse color of a surface.
void xSurfaceFX (Surface *surface, int fxFlags)
 Sets miscellaneous effects for a surface.
void xSurfacePrimitiveType (Surface *surface, int ptype)
 Sets the type of primitive to render.
void xSurfaceShininess (Surface *surface, float shininess)
 Sets the specular shininess of a surface.
void xSurfaceTexture (Surface *surface, Texture *texture, int frame, int index)
 Applies a texture to a surface.
int xTriangleVertex (Surface *surface, int triangle, int corner)
 Returns the vertex of a triangle corner.
float xVertexAlpha (Surface *surface, int vertex)
 Returns the alpha component of a vertices color, set using xVertexColor()
void xVertexBinormal (Surface *surface, int vertex, float x, float y, float z)
 Sets the binormal of an existing vertex.
float xVertexBlue (Surface *surface, int vertex)
 Returns the blue component of a vertices color.
float xVertexBX (Surface *surface, int vertex)
 Returns the x component of a vertex binormal.
float xVertexBY (Surface *surface, int vertex)
 Returns the y component of a vertex binormal.
float xVertexBZ (Surface *surface, int vertex)
 Returns the z component of a vertex binormal.
void xVertexColor (Surface *surface, int vertex, int red, int green, int blue, float alpha=1.0f)
 Sets the color of an existing vertex.
void xVertexCoords (Surface *surface, int vertex, float x, float y, float z)
 Sets the geometric coordinates of an existing vertex.
float xVertexGreen (Surface *surface, int vertex)
 Returns the green component of a vertices color.
void xVertexNormal (Surface *surface, int vertex, float x, float y, float z)
 Sets the normal of an existing vertex.
float xVertexNX (Surface *surface, int vertex)
 Returns the x component of a vertex normal.
float xVertexNY (Surface *surface, int vertex)
 Returns the y component of a vertex normal.
float xVertexNZ (Surface *surface, int vertex)
 Returns the z component of a vertex normal.
float xVertexRed (Surface *surface, int vertex)
 Returns the red component of a vertices color.
void xVertexTangent (Surface *surface, int vertex, float x, float y, float z)
 Sets the tangent of an existing vertex.
void xVertexTexCoords (Surface *surface, int vertex, float u, float v, float w=1.0f, int textureSet=0)
 Sets the texture coordinates of an existing vertex.
float xVertexTX (Surface *surface, int vertex)
 Returns the x component of a vertex tangent.
float xVertexTY (Surface *surface, int vertex)
 Returns the y component of a vertex tangent.
float xVertexTZ (Surface *surface, int vertex)
 Returns the z component of a vertex tangent.
float xVertexU (Surface *surface, int vertex, int textureSet=0)
 Returns the texture u coordinate of a vertex.
float xVertexV (Surface *surface, int vertex, int textureSet=0)
 Returns the texture v coordinate of a vertex.
float xVertexW (Surface *surface, int vertex, int textureSet=0)
 Returns the texture w coordinate of a vertex.
float xVertexX (Surface *surface, int vertex)
 Returns the x coordinate of a vertex.
float xVertexY (Surface *surface, int vertex)
 Returns the y coordinate of a vertex.
float xVertexZ (Surface *surface, int vertex)
 Returns the z coordinate of a vertex.

Function Documentation

Surface* 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).
Brush* 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
int 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
int 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()
void 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
void 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
void 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
void 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
void 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
void 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.
int xCountVertices ( Surface *  surface)

Returns the number of vertices in a surface.

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

Returns the x coordinate of a vertex.

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

Returns the y coordinate of a vertex.

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

Returns the z coordinate of a vertex.

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

Returns the x component of a vertex normal.

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

Returns the y component of a vertex normal.

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

Returns the z component of a vertex normal.

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

Returns the x component of a vertex tangent.

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

Returns the y component of a vertex tangent.

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

Returns the z component of a vertex tangent.

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

Returns the x component of a vertex binormal.

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

Returns the y component of a vertex binormal.

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

Returns the z component of a vertex binormal.

Parameters:
surfaceSurface handle
vertexVertex index
float 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.
float 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.
float 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.
float xVertexRed ( Surface *  surface,
int  vertex 
)

Returns the red component of a vertices color.

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

Returns the green component of a vertices color.

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

Returns the blue component of a vertices color.

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

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

Parameters:
surfaceSurface handle
vertexVertex index
int 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.
int xCountTriangles ( Surface *  surface)

Returns the number of triangles in a surface.

Parameters:
surfaceSurface handle
void 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
void 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
Texture* xGetSurfaceTexture ( Surface *  surface,
int  index = 0 
)

Return surface texture from specified index.

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

Frees up a surface.

Parameters:
surfaceSurface handle
void 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.
void 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].
void 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
void 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
void 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
void 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
void 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
void 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
void 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.