CrystalSpace

Public API Reference

iGraphics3D Struct Reference

This is the standard 3D graphics interface. More...

#include <ivideo/graph3d.h>

Inheritance diagram for iGraphics3D:

List of all members.

Public Member Functions

virtual bool ActivateBuffers (csVertexAttrib *attribs, iRenderBuffer **buffers, unsigned int count)=0
 Activate all given buffers.
virtual bool ActivateBuffers (csRenderBufferHolder *holder, csRenderBufferName mapping[CS_VATTRIB_SPECIFIC_LAST+1])=0
 Activate the buffers in the default buffer holder.
virtual bool BeginDraw (int DrawFlags)=0
 Start a new frame (see CSDRAW_XXX bit flags).
virtual bool CanSetRenderTarget (const char *format, csRenderTargetAttachment attachment=rtaColor0)=0
 Check if a texture with the given format can be set as a render target for the given attachment.
virtual void Close ()=0
 Close the 3D graphics display.
virtual void ClosePortal ()=0
 Close a portal previously opened with OpenPortal().
virtual void CopyFromRenderTargets (size_t num, csRenderTargetAttachment *attachments, iTextureHandle **textures, int *subtextures=0)=0
 Copy the contents of the given render target attachments to the specified textures.
virtual iHaloCreateHalo (float iR, float iG, float iB, unsigned char *iAlpha, int iWidth, int iHeight)=0
 Create a halo of the specified color and return a handle.
virtual void DeactivateBuffers (csVertexAttrib *attribs, unsigned int count)=0
 Deactivate all given buffers.
virtual void DisableZOffset ()=0
virtual void DrawLine (const csVector3 &v1, const csVector3 &v2, float fov, int color)=0
 Draw a line in camera space.
virtual void DrawMesh (const CS::Graphics::CoreRenderMesh *mymesh, const CS::Graphics::RenderMeshModes &modes, const csShaderVariableStack &stack)=0
 Drawroutine. Only way to draw stuff.
virtual void DrawPixmap (iTextureHandle *hTex, int sx, int sy, int sw, int sh, int tx, int ty, int tw, int th, uint8 Alpha=0)=0
 Draw a pixmap using a rectangle from given texture.
virtual void DrawSimpleMesh (const csSimpleRenderMesh &mesh, uint flags=0)=0
 Draw a csSimpleRenderMesh on the screen.
virtual void DrawSimpleMeshes (const csSimpleRenderMesh *meshes, size_t numMeshes, uint flags=0)=0
 Draw multiple csSimpleRenderMeshes.
virtual void EnableZOffset ()=0
virtual void FinishDraw ()=0
 End the frame and do a page swap.
virtual const csGraphics3DCapsGetCaps () const =0
 Get the current driver's capabilities.
virtual iClipper2DGetClipper ()=0
 Get clipper that was used.
virtual int GetClipType () const =0
 Return type of clipper.
virtual int GetCurrentDrawFlags () const =0
 Get the current drawflags.
virtual iGraphics2DGetDriver2D ()=0
 Retrieve the associated canvas.
virtual bool GetEdgeDrawing ()=0
 Get state of edge drawing.
virtual int GetHeight () const =0
 Get drawing buffer height.
virtual const csPlane3GetNearPlane () const =0
 Get near clip plane.
virtual float GetPerspectiveAspect () const =0
 Get aspect ratio.
virtual void GetPerspectiveCenter (int &x, int &y) const =0
 Get perspective center.
virtual long GetRenderState (G3D_RENDERSTATEOPTION op) const =0
 Get a renderstate value.
virtual iTextureHandleGetRenderTarget (csRenderTargetAttachment attachment=rtaColor0, int *subtexture=0) const =0
 Get the current render target (0 for screen).
virtual iTextureManagerGetTextureManager ()=0
 Retrieve the texture manager.
virtual int GetWidth () const =0
 Get drawing buffer width.
virtual const
csReversibleTransform
GetWorldToCamera ()=0
 Get the current world to camera transform.
virtual void GetWriteMask (bool &red, bool &green, bool &blue, bool &alpha) const =0
 Get the masking of color and/or alpha values to framebuffer.
virtual float GetZBuffValue (int x, int y)=0
 Get Z-buffer value at given X,Y position.
virtual csZBufMode GetZMode ()=0
 Get the z buffer write/test mode.
virtual bool HasNearPlane () const =0
 Return true if we have a near plane.
virtual bool Open ()=0
 Open the 3D graphics display.
virtual void OpenPortal (size_t numVertices, const csVector2 *vertices, const csPlane3 &normal, csFlags flags)=0
 Enter a new portal.
virtual bool PerformExtension (char const *command,...)=0
 Perform a system specific exension.
virtual bool PerformExtensionV (char const *command, va_list)=0
 Perform a system specific exension.
virtual void Print (csRect const *area)=0
 Print the image in backbuffer.
virtual void ResetNearPlane ()=0
 Reset near clip plane (i.e.
virtual void SetClipper (iClipper2D *clipper, int cliptype)=0
 Set optional clipper to use.
virtual void SetDimensions (int width, int height)=0
 Change the dimensions of the display.
virtual void SetEdgeDrawing (bool flag)=0
 Enable/disable edge drawing (for debugging purposes).
virtual void SetNearPlane (const csPlane3 &pl)=0
 Set near clip plane.
virtual bool SetOption (const char *, const char *)=0
 Set a renderer specific option.
virtual void SetPerspectiveAspect (float aspect)=0
 Set aspect ratio for perspective projection.
virtual void SetPerspectiveCenter (int x, int y)=0
 Set center of projection for perspective projection.
virtual void SetProjectionMatrix (const CS::Math::Matrix4 &m)=0
 Set the projection matrix to use.
virtual bool SetRenderState (G3D_RENDERSTATEOPTION op, long val)=0
 Set a renderstate value.
virtual bool SetRenderTarget (iTextureHandle *handle, bool persistent=false, int subtexture=0, csRenderTargetAttachment attachment=rtaColor0)=0
 Set the target of rendering for a certain rasterization result.
virtual void SetShadowState (int state)=0
 Controls shadow drawing.
virtual void SetTextureComparisonModes (int *units, CS::Graphics::TextureComparisonMode *texCompare, int count)=0
 Set the texture comparison modes for the given texture units.
virtual void SetTextureState (int *units, iTextureHandle **textures, int count)=0
 Activate or deactivate all given textures depending on the value of the entry of textures for that unit (i.e.
virtual void SetWorldToCamera (const csReversibleTransform &w2c)=0
 Set the world to camera transform.
virtual void SetWriteMask (bool red, bool green, bool blue, bool alpha)=0
 Set the masking of color and/or alpha values to framebuffer.
virtual void SetZMode (csZBufMode mode)=0
 Set the z buffer write/test mode.
virtual void UnsetRenderTargets ()=0
 Clear render targets for all rasterization result attachments.
virtual bool ValidateRenderTargets ()=0
 Check if the current set of render targets is valid.
Occlusion queries



virtual void OQBeginQuery (unsigned int occlusion_query)=0
 Start counting unoccluded fragments for a given query.
virtual void OQDelQueries (unsigned int *queries, int num_queries)=0
 Delete a set of occlusion queries.
virtual void OQEndQuery ()=0
 End counting unoccluded fragments for current query.
virtual void OQInitQueries (unsigned int *queries, int num_queries)=0
 Initialise a set of occlusion queries.
virtual bool OQIsVisible (unsigned int occlusion_query, unsigned int sampleLimit=0)=0
 Check via occlusion query whether a mesh is visible.
virtual bool OQueryFinished (unsigned int occlusion_query)=0
 Returns whether an occlusion query has finished.

Detailed Description

This is the standard 3D graphics interface.

All 3D renderers for Crystal Space implement this interface.

Main creators of instances implementing this interface:

Main ways to get pointers to this interface:

Definition at line 809 of file graph3d.h.


Member Function Documentation

virtual bool iGraphics3D::ActivateBuffers ( csVertexAttrib attribs,
iRenderBuffer **  buffers,
unsigned int  count 
) [pure virtual]

Activate all given buffers.

virtual bool iGraphics3D::ActivateBuffers ( csRenderBufferHolder holder,
csRenderBufferName  mapping[CS_VATTRIB_SPECIFIC_LAST+1] 
) [pure virtual]

Activate the buffers in the default buffer holder.

virtual bool iGraphics3D::BeginDraw ( int  DrawFlags  )  [pure virtual]

Start a new frame (see CSDRAW_XXX bit flags).

virtual bool iGraphics3D::CanSetRenderTarget ( const char *  format,
csRenderTargetAttachment  attachment = rtaColor0 
) [pure virtual]

Check if a texture with the given format can be set as a render target for the given attachment.

Remarks:
Texture formats may be reported as supported even though textures with that format can't be created.
virtual void iGraphics3D::Close (  )  [pure virtual]

Close the 3D graphics display.

virtual void iGraphics3D::ClosePortal (  )  [pure virtual]

Close a portal previously opened with OpenPortal().

If 'zfill_portal' then the portal area will be zfilled.

virtual void iGraphics3D::CopyFromRenderTargets ( size_t  num,
csRenderTargetAttachment attachments,
iTextureHandle **  textures,
int *  subtextures = 0 
) [pure virtual]

Copy the contents of the given render target attachments to the specified textures.

Parameters:
num Number of attachment/texture pairs.
attachments Array of attachments from which to copy.
textures Array of texture to copy to.
subtextures Optional array of subtextures (cube map faces/volume slices) to copy to. If none is given a subtexture 0 is assumed for all targets.
virtual iHalo* iGraphics3D::CreateHalo ( float  iR,
float  iG,
float  iB,
unsigned char *  iAlpha,
int  iWidth,
int  iHeight 
) [pure virtual]

Create a halo of the specified color and return a handle.

virtual void iGraphics3D::DeactivateBuffers ( csVertexAttrib attribs,
unsigned int  count 
) [pure virtual]

Deactivate all given buffers.

If attribs is 0, all buffers are deactivated;

virtual void iGraphics3D::DisableZOffset (  )  [pure virtual]
Deprecated:
Deprecated in 1.3. Use RenderMeshModes::zoffset instead.
virtual void iGraphics3D::DrawLine ( const csVector3 v1,
const csVector3 v2,
float  fov,
int  color 
) [pure virtual]

Draw a line in camera space.

Warning! This is a 2D operation and must be called while in BeginDraw(CSDRAW_2DGRAPHICS)!

Deprecated:
Deprecated in 2.0. Use iGraphics2D::DrawLineProjected() instead
virtual void iGraphics3D::DrawMesh ( const CS::Graphics::CoreRenderMesh mymesh,
const CS::Graphics::RenderMeshModes modes,
const csShaderVariableStack stack 
) [pure virtual]

Drawroutine. Only way to draw stuff.

virtual void iGraphics3D::DrawPixmap ( iTextureHandle hTex,
int  sx,
int  sy,
int  sw,
int  sh,
int  tx,
int  ty,
int  tw,
int  th,
uint8  Alpha = 0 
) [pure virtual]

Draw a pixmap using a rectangle from given texture.

The sx,sy(sw,sh) rectangle defines the screen rectangle within which the drawing is performed (clipping rectangle is also taken into account). The tx,ty(tw,th) rectangle defines a subrectangle from texture which should be painted. If the subrectangle exceeds the actual texture size, texture coordinates are wrapped around (e.g. the texture is tiled). The Alpha parameter defines the transparency of the drawing operation, 0 means opaque, 255 means fully transparent.

WARNING: Tiling works only with textures that have power-of-two sizes! That is, both width and height should be a power-of-two, although not neccessarily equal.

virtual void iGraphics3D::DrawSimpleMesh ( const csSimpleRenderMesh mesh,
uint  flags = 0 
) [pure virtual]

Draw a csSimpleRenderMesh on the screen.

Simple render meshes are intended for cases where setting up a render mesh and juggling with render buffers would be too much effort - e.g. when you want to draw a single polygon on the screen.

DrawSimpleMesh () hides the complexity of csRenderMesh, it cares about setting up render buffers, activating the texture etc. Note that you can still provide shaders and shader variables, but those are optional.

Parameters:
mesh The mesh to draw.
flags Drawing flags, a combination of csSimpleMeshFlags values.
Remarks:
This operation can also be called from 2D mode. In this case, the csSimpleMeshScreenspace flag should be specified. If this is not the case, you are responsible for the mess that is likely created.
virtual void iGraphics3D::DrawSimpleMeshes ( const csSimpleRenderMesh meshes,
size_t  numMeshes,
uint  flags = 0 
) [pure virtual]

Draw multiple csSimpleRenderMeshes.

See also:
DrawSimpleMesh
virtual void iGraphics3D::EnableZOffset (  )  [pure virtual]
Deprecated:
Deprecated in 1.3. Use RenderMeshModes::zoffset instead.
virtual void iGraphics3D::FinishDraw (  )  [pure virtual]

End the frame and do a page swap.

virtual const csGraphics3DCaps* iGraphics3D::GetCaps (  )  const [pure virtual]

Get the current driver's capabilities.

Each driver implements their own function.

virtual iClipper2D* iGraphics3D::GetClipper (  )  [pure virtual]

Get clipper that was used.

virtual int iGraphics3D::GetClipType (  )  const [pure virtual]

Return type of clipper.

virtual int iGraphics3D::GetCurrentDrawFlags (  )  const [pure virtual]

Get the current drawflags.

virtual iGraphics2D* iGraphics3D::GetDriver2D (  )  [pure virtual]

Retrieve the associated canvas.

Remarks:
This will return a valid canvas only after csInitializer::OpenApplication() has been invoked (and if the canvas plugin loaded and initialized successfully); otherwise it will return null.
virtual bool iGraphics3D::GetEdgeDrawing (  )  [pure virtual]

Get state of edge drawing.

virtual int iGraphics3D::GetHeight (  )  const [pure virtual]

Get drawing buffer height.

virtual const csPlane3& iGraphics3D::GetNearPlane (  )  const [pure virtual]

Get near clip plane.

virtual float iGraphics3D::GetPerspectiveAspect (  )  const [pure virtual]

Get aspect ratio.

Deprecated:
Deprecated in 2.0. Use explicit camera's projection matrix instead
virtual void iGraphics3D::GetPerspectiveCenter ( int &  x,
int &  y 
) const [pure virtual]

Get perspective center.

Remarks:
The coordinates are vertically mirrored in comparison to screen space, i.e. y=0 is at the bottom of the viewport, y=GetHeight() at the top.
Deprecated:
Deprecated in 2.0. Use explicit camera's projection matrix instead
virtual long iGraphics3D::GetRenderState ( G3D_RENDERSTATEOPTION  op  )  const [pure virtual]

Get a renderstate value.

Deprecated:
Deprecated in 2.0. Use SetEdgeDrawing() for sole supported render state.
virtual iTextureHandle* iGraphics3D::GetRenderTarget ( csRenderTargetAttachment  attachment = rtaColor0,
int *  subtexture = 0 
) const [pure virtual]

Get the current render target (0 for screen).

Parameters:
attachment The attachment for which to return the render target.
subtexture Optionally returns the subtexture index.
virtual iTextureManager* iGraphics3D::GetTextureManager (  )  [pure virtual]

Retrieve the texture manager.

Remarks:
This will return a valid texture manager only after csInitializer::OpenApplication() has been invoked; otherwise it will return null.
virtual int iGraphics3D::GetWidth (  )  const [pure virtual]

Get drawing buffer width.

virtual const csReversibleTransform& iGraphics3D::GetWorldToCamera (  )  [pure virtual]

Get the current world to camera transform.

Remarks:
'this' space is world space, 'other' space is camera space
virtual void iGraphics3D::GetWriteMask ( bool &  red,
bool &  green,
bool &  blue,
bool &  alpha 
) const [pure virtual]

Get the masking of color and/or alpha values to framebuffer.

virtual float iGraphics3D::GetZBuffValue ( int  x,
int  y 
) [pure virtual]

Get Z-buffer value at given X,Y position.

virtual csZBufMode iGraphics3D::GetZMode (  )  [pure virtual]

Get the z buffer write/test mode.

virtual bool iGraphics3D::HasNearPlane (  )  const [pure virtual]

Return true if we have a near plane.

virtual bool iGraphics3D::Open (  )  [pure virtual]

Open the 3D graphics display.

virtual void iGraphics3D::OpenPortal ( size_t  numVertices,
const csVector2 vertices,
const csPlane3 normal,
csFlags  flags 
) [pure virtual]

Enter a new portal.

If 'flags' contains CS_PORTAL_FLOAT then this routine will restrict all further drawing to the given 2D area and it will also respect the current contents of the Z-buffer so that geometry will only render where the Z-buffer allows it (even if zfill or znone is used). Remember to close a portal later using ClosePortal(). Basically this represents a stacked layer of portals. Each subsequent portal must be fully contained in the previous ones.

virtual void iGraphics3D::OQBeginQuery ( unsigned int  occlusion_query  )  [pure virtual]

Start counting unoccluded fragments for a given query.

virtual void iGraphics3D::OQDelQueries ( unsigned int *  queries,
int  num_queries 
) [pure virtual]

Delete a set of occlusion queries.

virtual void iGraphics3D::OQEndQuery (  )  [pure virtual]

End counting unoccluded fragments for current query.

virtual void iGraphics3D::OQInitQueries ( unsigned int *  queries,
int  num_queries 
) [pure virtual]

Initialise a set of occlusion queries.

virtual bool iGraphics3D::OQIsVisible ( unsigned int  occlusion_query,
unsigned int  sampleLimit = 0 
) [pure virtual]

Check via occlusion query whether a mesh is visible.

virtual bool iGraphics3D::OQueryFinished ( unsigned int  occlusion_query  )  [pure virtual]

Returns whether an occlusion query has finished.

virtual bool iGraphics3D::PerformExtension ( char const *  command,
  ... 
) [pure virtual]

Perform a system specific exension.

The command is a string; any arguments may follow. There is no way to guarantee the uniquiness of commands, so please try to use descriptive command names rather than "a", "b" and so on...

virtual bool iGraphics3D::PerformExtensionV ( char const *  command,
va_list   
) [pure virtual]

Perform a system specific exension.

Just like PerformExtension() except that the command arguments are passed as a `va_list'.

virtual void iGraphics3D::Print ( csRect const *  area  )  [pure virtual]

Print the image in backbuffer.

The area parameter is only a hint to the renderer. Changes outside the rectangle may or may not be printed as well.

virtual void iGraphics3D::ResetNearPlane (  )  [pure virtual]

Reset near clip plane (i.e.

disable it).

virtual void iGraphics3D::SetClipper ( iClipper2D clipper,
int  cliptype 
) [pure virtual]

Set optional clipper to use.

If clipper == null then there is no clipper. Currently only used by DrawTriangleMesh.

virtual void iGraphics3D::SetDimensions ( int  width,
int  height 
) [pure virtual]

Change the dimensions of the display.

Deprecated:
Deprecated in 1.3.
virtual void iGraphics3D::SetEdgeDrawing ( bool  flag  )  [pure virtual]

Enable/disable edge drawing (for debugging purposes).

virtual void iGraphics3D::SetNearPlane ( const csPlane3 pl  )  [pure virtual]

Set near clip plane.

The plane is in camera space.

virtual bool iGraphics3D::SetOption ( const char *  ,
const char *   
) [pure virtual]

Set a renderer specific option.

Returns false if renderer doesn't support that option.

virtual void iGraphics3D::SetPerspectiveAspect ( float  aspect  )  [pure virtual]

Set aspect ratio for perspective projection.

Deprecated:
Deprecated in 2.0. Use explicit camera's projection matrix instead
virtual void iGraphics3D::SetPerspectiveCenter ( int  x,
int  y 
) [pure virtual]

Set center of projection for perspective projection.

Remarks:
The coordinates are vertically mirrored in comparison to screen space, i.e. y=0 is at the bottom of the viewport, y=GetHeight() at the top.
Deprecated:
Deprecated in 2.0. Use explicit camera's projection matrix instead
virtual void iGraphics3D::SetProjectionMatrix ( const CS::Math::Matrix4 m  )  [pure virtual]

Set the projection matrix to use.

virtual bool iGraphics3D::SetRenderState ( G3D_RENDERSTATEOPTION  op,
long  val 
) [pure virtual]

Set a renderstate value.

Deprecated:
Deprecated in 2.0. Use SetEdgeDrawing() for sole supported render state.
virtual bool iGraphics3D::SetRenderTarget ( iTextureHandle handle,
bool  persistent = false,
int  subtexture = 0,
csRenderTargetAttachment  attachment = rtaColor0 
) [pure virtual]

Set the target of rendering for a certain rasterization result.

If all result attachments have a 0 target rendering is performed to the framebuffer (ie main screen). If at least one texture is attached rendering is performed off-screen to the given texture(s). After calling FinishDraw() the targets will automatically be unset. Note that on some implementions rendering on a texture will overwrite the framebuffer contents. So you should only do this BEFORE you start rendering your frame.

Parameters:
persistent If this is true then the current contents of the texture will be preserved when drawing occurs (in the first call to BeginDraw). Otherwise it is assumed that you fully render the texture - untouched parts may be undefined. Using persistence may incur a performance penalty so it's recommended to avoid this flag.
subtexture this specifies the subtexture index if the texture is a cubemap or volume texture. It is in the range 0 to 5 for cubemaps (iTextureHandle::CS_TEXTURE_CUBE_POS_X et al) or the depth index for volume textures.
attachment Specifies to what result of the rasterization the texture should be attached to.
Returns:
Whether setting the render target was successful. However, even if 'true' is returned, it may be possible that rendering to the eventual set of render targets is not possible. Only if ValidateRenderTargets returns 'true' the set of targets can really be used as a render target.
See also:
UnsetRenderTargets
virtual void iGraphics3D::SetShadowState ( int  state  )  [pure virtual]

Controls shadow drawing.

virtual void iGraphics3D::SetTextureComparisonModes ( int *  units,
CS::Graphics::TextureComparisonMode *  texCompare,
int  count 
) [pure virtual]

Set the texture comparison modes for the given texture units.

virtual void iGraphics3D::SetTextureState ( int *  units,
iTextureHandle **  textures,
int  count 
) [pure virtual]

Activate or deactivate all given textures depending on the value of the entry of textures for that unit (i.e.

deactivate if 0). If textures itself is 0 all specified units are deactivated.

virtual void iGraphics3D::SetWorldToCamera ( const csReversibleTransform w2c  )  [pure virtual]

Set the world to camera transform.

This affects rendering in DrawMesh and DrawSimpleMesh.

Remarks:
'this' space is world space, 'other' space is camera space
virtual void iGraphics3D::SetWriteMask ( bool  red,
bool  green,
bool  blue,
bool  alpha 
) [pure virtual]

Set the masking of color and/or alpha values to framebuffer.

virtual void iGraphics3D::SetZMode ( csZBufMode  mode  )  [pure virtual]

Set the z buffer write/test mode.

virtual void iGraphics3D::UnsetRenderTargets (  )  [pure virtual]

Clear render targets for all rasterization result attachments.

virtual bool iGraphics3D::ValidateRenderTargets (  )  [pure virtual]

Check if the current set of render targets is valid.

Returns:
Whether the current set of render targets is valid and useable. Reasons for invalidity/unusability can include:
  • The hardware or driver does not support the given attachment with the given texture or not at all.
  • The dimensions of the various attachments don't match.

The documentation for this struct was generated from the following file:

Generated for Crystal Space 2.0 by doxygen 1.6.1