Xors3d Engine
Cameras

Functions

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

Function Documentation

BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL 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.
BBDECL void BBCALL xCameraProjMode ( Camera *  camera,
int  mode 
)

Sets the camera projection mode.

Parameters:
cameraCamera handle
modeProjection mode. See 'Camera projection types' for more information
BBDECL void BBCALL 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
BBDECL int BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL Camera* BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL float BBCALL xProjectedX ( )

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

BBDECL float BBCALL xProjectedY ( )

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

BBDECL float BBCALL xProjectedZ ( )

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

BBDECL D3DXMATRIX* BBCALL xGetViewMatrix ( Camera *  camera)

Returns a pointer to camera's view matrix.

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

Returns a pointer to camera's projection matrix.

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

Sets zoom factor for a camera.

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

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

Parameters:
cameraCamera handle
BBDECL int BBCALL 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
BBDECL Entity* BBCALL 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
BBDECL float BBCALL xPickedNX ( )

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

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

BBDECL float BBCALL xPickedNY ( )

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

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

BBDECL float BBCALL xPickedNZ ( )

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

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

BBDECL float BBCALL 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

BBDECL float BBCALL 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

BBDECL float BBCALL 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

BBDECL Entity* BBCALL xPickedEntity ( )

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

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

BBDECL Surface* BBCALL 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().

BBDECL int BBCALL 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().

BBDECL int BBCALL xPickedTime ( )

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

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

BBDECL void BBCALL 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