Xors3d Engine
Cameras

Functions

void xCameraClipPlane (Camera *camera, int index, bool enabled, float a, float b, float c, float d)
 Sets camera clip plane.
void xCameraClsColor (Camera *camera, int red, int green, int blue, int alpha=255)
 Sets camera background color (RGBA-format). Defaults to (0, 0, 0, 255).
void xCameraClsMode (Camera *camera, int clearColor, int clearZBuffer)
 Sets camera clear mode.
void xCameraCropViewport (Camera *camera, int x, int y, int width, int height)
 Sets the camera viewport crop rectangle.
void xCameraFogColor (Camera *camera, int red, int green, int blue)
 Sets camera fog color. Defaults to 0, 0, 0.
void xCameraFogMode (Camera *camera, int mode)
 Sets the camera fog mode.
void xCameraFogRange (Camera *camera, float nearRange, float farRange)
 Sets camera fog range.
Entity * xCameraPick (Camera *camera, int x, int y)
 Picks the entity positioned at the specified viewport coordinates.
void xCameraProject (Camera *camera, float x, float y, float z)
 Projects the world coordinates on to the 2D screen.
void xCameraProject2D (Camera *camera, int x, int y, float zDistance)
 Projects the 2D screen coordinates on to the world coordinates.
void xCameraProjMode (Camera *camera, int mode)
 Sets the camera projection mode.
void xCameraRange (Camera *camera, float nearRange, float farRange)
 Sets camera range.
void xCameraViewport (Camera *camera, int x, int y, int width, int height)
 Sets the camera viewport position and size.
void xCameraZoom (Camera *camera, float zoom)
 Sets zoom factor for a camera.
Camera * xCreateCamera (Entity *parent=NULL)
 Creates a camera entity and returns its handle.
int xEntityInView (Entity *entity, Camera *camera)
 Returns true if the specified entity is visible to the specified camera.
D3DXMATRIX * xGetProjectionMatrix (Camera *camera)
 Returns a pointer to camera's projection matrix.
D3DXMATRIX * xGetViewMatrix (Camera *camera)
 Returns a pointer to camera's view matrix.
D3DXMATRIX * xGetViewProjMatrix (Camera *camera)
 Returns a pointer to camera's view-projection matrix.
Entity * xPickedEntity ()
 Returns the entity 'picked' by the most recently executed pick command.
float xPickedNX ()
 Returns the x component of the normal of the most recently executed pick command.
float xPickedNY ()
 Returns the y component of the normal of the most recently executed pick command.
float xPickedNZ ()
 Returns the z component of the normal of the most recently executed pick command.
Surface * xPickedSurface ()
 Returns the handle of the surface that was 'picked' by the most recently executed pick command.
int xPickedTime ()
 Returns the time taken to calculate the most recently executed pick command.
int xPickedTriangle ()
 Returns the index number of the triangle that was 'picked' by the most recently executed pick command.
float xPickedX ()
 Returns the world x coordinate of the most recently executed pick command.
float xPickedY ()
 Returns the world ycoordinate of the most recently executed pick command.
float xPickedZ ()
 Returns the world z coordinate of the most recently executed pick command.
float xProjectedX ()
 Returns the viewport x coordinate of the most recently executed xCameraProject()
float xProjectedY ()
 Returns the viewport y coordinate of the most recently executed xCameraProject()
float xProjectedZ ()
 Returns the viewport z coordinate of the most recently executed xCameraProject()
void xSetSurfaceFrustumSphere (Surface *surface, float x, float y, float z, float radii)
 Sets surface's bounding sphere for frustum culling.
int xSphereInFrustum (Camera *camera, float x, float y, float z, float radii)
 Returns true if sphere passed frustum culling check.

Function Documentation

void xCameraFogMode ( Camera *  camera,
int  mode 
)

Sets the camera fog mode.

This will enable/disable fogging, a technique used to gradually fade out graphics the further they are away from the camera. This can be used to avoid 'pop-up', the moment at which 3D objects suddenly appear on the horizon. The default fog colour is black and the default fog range is 1-1000, although these can be changed by using xCameraFogColor() and xCameraFogRange() respectively. Each camera can have its own fog mode, for multiple on-screen fog effects.

Parameters:
cameraCamera handle
modeFor mode. See 'Fog types' for more information
void xCameraFogColor ( Camera *  camera,
int  red,
int  green,
int  blue 
)

Sets camera fog color. Defaults to 0, 0, 0.

Parameters:
cameraCamera handle
redRed value of camera fog color
greenGreen value of camera fog color
blueBlue value of camera fog color
void xCameraFogRange ( Camera *  camera,
float  nearRange,
float  farRange 
)

Sets camera fog range.

The 'nearRange' parameter specifies at what distance in front of the camera that the fogging effect will start; all 3D object before this point will not be faded. The 'farRange' parameter specifies at what distance in front of the camera that the fogging effect will end; all 3D objects beyond this point will be completely faded out.

Parameters:
cameraCamera handle
nearRangeDistance in front of camera that fog starts
farRangeDistance in front of camera that fog ends
void xCameraClsColor ( Camera *  camera,
int  red,
int  green,
int  blue,
int  alpha = 255 
)

Sets camera background color (RGBA-format). Defaults to (0, 0, 0, 255).

Parameters:
cameraCamera handle
redRed value of camera background color
greenGreen value of camera background color
blueBlue value of camera background color
alphaAlpha value of camera background color.
void xCameraProjMode ( Camera *  camera,
int  mode 
)

Sets the camera projection mode.

Parameters:
cameraCamera handle
modeProjection mode. See 'Camera projection types' for more information
void xCameraClsMode ( Camera *  camera,
int  clearColor,
int  clearZBuffer 
)

Sets camera clear mode.

Parameters:
cameraCamera handle
clearColorTrue to clear the color buffer, false not to
clearZBufferTrue to clear the color z-buffer, false not to
int xSphereInFrustum ( Camera *  camera,
float  x,
float  y,
float  z,
float  radii 
)

Returns true if sphere passed frustum culling check.

Parameters:
cameraCamera handle
xx coordinate of sphere center
yy coordinate of sphere center
zz coordinate of sphere center
radiiRadius of sphere
void xCameraClipPlane ( Camera *  camera,
int  index,
bool  enabled,
float  a,
float  b,
float  c,
float  d 
)

Sets camera clip plane.

(A, B, C, D) coefficients take the form of the general plane equation.

Parameters:
cameraCamera handle
indexClip plane index
enabledTrue to enable clipping plane
aa component of clipping plane
bb component of clipping plane
cc component of clipping plane
dd component of clipping plane
void xCameraRange ( Camera *  camera,
float  nearRange,
float  farRange 
)

Sets camera range.

Try and keep the ratio of far/near as small as possible for optimal z-buffer performance. Defaults to 1, 1000

Parameters:
cameraCamera handle
nearRangeDistance in front of camera that 3D objects start being drawn
farRangeDistance in front of camera that 3D object stop being drawn
void xCameraViewport ( Camera *  camera,
int  x,
int  y,
int  width,
int  height 
)

Sets the camera viewport position and size.

The camera viewport is the area of the 2D screen that the 3D graphics as viewed by the camera are displayed in. Setting the camera viewport allows you to achieve spilt-screen and rear-view mirror effects

Parameters:
cameraCamera handle
xx-coordinate of top left hand corner of viewport
yy-coordinate of top left hand corner of viewport
widthWidth of viewport
heightHeight of viewport
void xCameraCropViewport ( Camera *  camera,
int  x,
int  y,
int  width,
int  height 
)

Sets the camera viewport crop rectangle.

Parameters:
cameraCamera handle
xx-coordinate of top left hand corner of viewport
yy-coordinate of top left hand corner of viewport
widthWidth of viewport
heightHeight of viewport
Camera* xCreateCamera ( Entity *  parent = NULL)

Creates a camera entity and returns its handle.

Without at least one camera, you won't be able to see anything in your 3D world. With more than one camera, you will be to achieve effect such as split-screen modes and rear-view mirrors. In Xors3D camera can render in any rendering buffer (xBackBuffer(), xImageBuffer(), xTextureBuffer()). The optional parent parameter allow you to specify a parent entity for the camera so that when the parent is moved the child camera 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 camera being created at position 0, 0, 0 rather than at the parent entity's position.

Parameters:
parentParent entity handle
void xCameraProject ( Camera *  camera,
float  x,
float  y,
float  z 
)

Projects the world coordinates on to the 2D screen.

If the point (x, y, z) is behind the camera, projected coordinates are (-65535.0, -65535.0, -65535.0).

Parameters:
cameraCamera handle
xWorld coordinate x
yWorld coordinate y
zWorld coordinate z
void xCameraProject2D ( Camera *  camera,
int  x,
int  y,
float  zDistance 
)

Projects the 2D screen coordinates on to the world coordinates.

Parameters:
cameraCamera handle
xScreen coordinate on X axis
yScreen coordinate on Y axis
zDistanceDistance of the projected point from camera near plane
float xProjectedX ( )

Returns the viewport x coordinate of the most recently executed xCameraProject()

float xProjectedY ( )

Returns the viewport y coordinate of the most recently executed xCameraProject()

float xProjectedZ ( )

Returns the viewport z coordinate of the most recently executed xCameraProject()

D3DXMATRIX* xGetViewMatrix ( Camera *  camera)

Returns a pointer to camera's view matrix.

Parameters:
cameraCamera handle
D3DXMATRIX* xGetProjectionMatrix ( Camera *  camera)

Returns a pointer to camera's projection matrix.

Parameters:
cameraCamera handle
void xCameraZoom ( Camera *  camera,
float  zoom 
)

Sets zoom factor for a camera.

Parameters:
cameraCamera handle
zoomZoom factor of camera
D3DXMATRIX* xGetViewProjMatrix ( Camera *  camera)

Returns a pointer to camera's view-projection matrix.

Parameters:
cameraCamera handle
int xEntityInView ( Entity *  entity,
Camera *  camera 
)

Returns true if the specified entity is visible to the specified camera.

If the entity is a mesh, its bounding box will be checked for visibility. For all other types of entities, only their centre position will be checked

Parameters:
entityEntity handle
cameraCamera handle
Entity* xCameraPick ( Camera *  camera,
int  x,
int  y 
)

Picks the entity positioned at the specified viewport coordinates.

Returns the entity picked, or 0 if none there. An entity must have its xEntityPickMode() set to a non-0 value value to be 'pickable'.

Parameters:
cameraCamera handle
x2D viewport x-coordinate
y2D viewport y-coordinate
float xPickedNX ( )

Returns the x component of the normal of the most recently executed pick command.

This might have been xCameraPick(), xEntityPick() or xLinePick().

float xPickedNY ( )

Returns the y component of the normal of the most recently executed pick command.

This might have been xCameraPick(), xEntityPick() or xLinePick().

float xPickedNZ ( )

Returns the z component of the normal of the most recently executed pick command.

This might have been xCameraPick(), xEntityPick() or xLinePick().

float xPickedX ( )

Returns the world x coordinate of the most recently executed pick command.

This might have been xCameraPick(), xEntityPick() or xLinePick(). The coordinate represents the exact point of where something was picked

float xPickedY ( )

Returns the world ycoordinate of the most recently executed pick command.

This might have been xCameraPick(), xEntityPick() or xLinePick(). The coordinate represents the exact point of where something was picked

float xPickedZ ( )

Returns the world z coordinate of the most recently executed pick command.

This might have been xCameraPick(), xEntityPick() or xLinePick(). The coordinate represents the exact point of where something was picked

Entity* xPickedEntity ( )

Returns the entity 'picked' by the most recently executed pick command.

This might have been xCameraPick(), xEntityPick() or xLinePick().

Surface* xPickedSurface ( )

Returns the handle of the surface that was 'picked' by the most recently executed pick command.

This might have been xCameraPick(), xEntityPick() or xLinePick().

int xPickedTriangle ( )

Returns the index number of the triangle that was 'picked' by the most recently executed pick command.

This might have been xCameraPick(), xEntityPick() or xLinePick().

int xPickedTime ( )

Returns the time taken to calculate the most recently executed pick command.

This might have been xCameraPick(), xEntityPick() or xLinePick().

void xSetSurfaceFrustumSphere ( Surface *  surface,
float  x,
float  y,
float  z,
float  radii 
)

Sets surface's bounding sphere for frustum culling.

Parameters:
surfaceSurface handle
xx coordinate of bounding sphere center
yy coordinate of bounding sphere center
zz coordinate of bounding sphere center
radiiRadius of bounding sphere