Main Page | Modules | Namespace List | Class Hierarchy | Class List | Directories | Namespace Members | Class Members | Related Pages
XEngine::Core::RenderContext

RenderContext Class Reference
[XEngineCore Library]

List of all members.

Detailed Description

RenderContext is the main interface class to the underlying rendering API, such as OpenGL or DirectX. It offers routines to create render targets, to set render states, to draw primitives using buffers, to create various render resources, and to begin and end a scene.

A render context is created by calling Renderer::CreateRenderContext, which returns a shared pointer to the newly created render context. Only the thread that created the render context may use it subsequently. When a render context is created, a primary render window is automatically created with it and set as active render target. The primary render window can be any RenderWindow-derived class. Therefore the render target format object passed to Renderer::CreateRenderContext must be an instance of the RenderWindow::Format class or a class derived from it.

In order to render objects with a render context, you must first create various resources to describe those objects. These resources include objects of the classes VertexBuffer and IndexBuffer that store basic geometry information. You can create texture resources to give your objects a realistic appearance. All texture classes, such as Texture2D or CubeTexture, are derived from the TextureBase base class.

After you have created your objects using the RenderResource-derived classes, you can start setting various render states by calling RenderContext::SetState. Of course, you might also want to set various texture coordinate stage states and set a texture for the texture sampler stages. To do that, call RenderContext::GetTextureSamplerStage or RenderContext::GetTextureCoordStage to get a pointer to the desired stage and then call TextureSamplerStage::SetState or TextureCoordStage::SetState to set a state or TextureSamplerStage::SetTexture to set the texture for that stage.

Once everything is ready to be rendered, call RenderContext::SetRenderTarget to set an appropriate render target. Render targets are all instances of RenderTarget-derived classes. Initially, the primary render window is set as render target. Call RenderContext::Clear to clear the render target, if necessary. Then call RenderContext::BeginScene to tell XEngine that you intend to render a scene, and use one of the RenderContext::Draw methods to draw your geometry. After you're done call RenderContext::EndScene to end the scene. If you're rendering to a window, you'll have to call RenderContext::Swap to swap the back with the front buffer.

A render context is destroyed when the last shared pointer instance referencing it is destroyed. It is important that, before destroying a render context, all render resources and render targets created by that render context are destroyed. Thus, the client must reset or destroy all shared pointers to render resources and render targets that it holds. All shared pointers that the render context holds internally to resources and targets are taken care of by the destructor of the render context, so the client will not have to worry about these and need not e.g. call TextureSamplerStage::SetTexture with an empty pointer before destroying a render context. The debug version of the library will assert if not all references to render resources and render targets held by the client have been released.


Public Types

enum  PrimitiveType {
  PointList, LineList, LineStrip, TriangleList,
  TriangleStrip, TriangleFan
}
 This enum specifies the available primitive types. More...

Public Member Functions

void SetDefaultState ()
 Sets the default state of the complete set of states of this render context.
void SetDefaultRenderState ()
 Sets the default render state for all render states.
const boost::shared_ptr< Renderer > & GetRenderer () const
 Returns the renderer object that created this render context.
unsigned int GetAdapter () const
 Returns the adapter that is used by this context.
unsigned int GetDevice () const
 Returns the device/driver that is used by this context.
const AdapterInfo & GetAdapterInfo () const
 Returns the adapter info object of the adapter used by this context.
const DeviceInfo & GetDeviceInfo () const
 Returns the device info object of the device used by this context.
const RenderContextCaps & GetCaps () const
 Returns the capabilities object for this render context; does not contain display mode information!
boost::shared_ptr< const StateSet > GetStateSet () const
 Returns a pointer to the state set of this render context.
const boost::shared_ptr< TextureSamplerStage > & GetTextureSamplerStage (size_t stage) const
 Returns a pointer to a texture sampler stage.
const boost::shared_ptr< TextureCoordStage > & GetTextureCoordStage (size_t stage) const
 Returns a pointer to a texture coordinate stage.
boost::shared_ptr< RenderTarget > CreateRenderTarget (const RenderTarget::Format &format)
 Creates a new render target of the given type.
void SetRenderTarget (const boost::shared_ptr< RenderTarget > &pTarget)
 Sets the active render target. All subsequent Draw calls will render to this target.
const boost::shared_ptr< RenderTarget > & GetRenderTarget () const
 Returns the active render target.
const boost::shared_ptr< RenderWindow > & GetPrimaryRenderWindow () const
 Returns the primary render window of this render context.
size_t GetRenderTargetCount (RenderTarget::Type renderTargetType) const
 Returns the number of render targets of the given type created so far.
size_t GetRenderWindowCount () const
 Returns the number of all render windows (all RenderWindow-derived classes) created so far.
template<typename OutputIteratorT>
void GetRenderTargets (OutputIteratorT it) const
 Returns all render targets currently managed by this render context via the given boost::shared_ptr<RenderTarget> output iterator.
void Clear (wxUint32 clearFlags)
 Clears the specified buffers of the currently active render target.
void Swap ()
 Swaps front with back buffers of the currently active render target, if it supports swapping.
boost::shared_ptr< StateSet > CreateStateSet ()
 Creates a new state set.
boost::shared_ptr< IndexBuffer > CreateIndexBuffer (RenderBuffer::BufferType bufferType, RenderBuffer::UsageFlags usage, size_t count, IndexBuffer::Type type)
 Creates a new index buffer.
boost::shared_ptr< VertexBuffer > CreateVertexBuffer (RenderBuffer::BufferType bufferType, RenderBuffer::UsageFlags usage, size_t count, const VertexFormat &format)
 Creates a new vertex buffer.
boost::shared_ptr< Texture1D > CreateTexture1D (unsigned int width, const PixelFormat &format, size_t levelCount=0, bool generateMipmaps=true)
 Creates a new 1-dimensional texture.
boost::shared_ptr< Texture2D > CreateTexture2D (unsigned int width, unsigned int height, const PixelFormat &format, size_t levelCount=0, bool generateMipmaps=true)
 Creates a new 2-dimensional texture.
boost::shared_ptr< Texture3D > CreateTexture3D (unsigned int width, unsigned int height, unsigned int depth, const PixelFormat &format, size_t levelCount=0, bool generateMipmaps=true)
 Creates a new 3-dimensional volume texture.
boost::shared_ptr< CubeTexture > CreateCubeTexture (unsigned int edgeLength, const PixelFormat &format, size_t levelCount=0, bool generateMipmaps=true)
 Creates a new cube texture.
boost::shared_ptr< Texture1D > CreateTexture1D (const wxImage &image, size_t levelCount=0, bool generateMipmaps=true)
 Creates a new 1-dimensional texture from a wxImage.
boost::shared_ptr< Texture2D > CreateTexture2D (const wxImage &image, size_t levelCount=0, bool generateMipmaps=true)
 Creates a new 2-dimensional texture from a wxImage.
boost::shared_ptr< CubeTexture > CreateCubeTexture (const wxImage &positiveX, const wxImage &negativeX, const wxImage &positiveY, const wxImage &negativeY, const wxImage &positiveZ, const wxImage &negativeZ, size_t levelCount=0, bool generateMipmaps=true)
 Creates a new cube texture from 6 wxImage objects.
boost::shared_ptr< Texture1D > CreateTexture1D (wxInputStream &inputStream, size_t levelCount=0, bool generateMipmaps=true)
 Creates a new 1-dimensional texture from a wxInputStream.
boost::shared_ptr< Texture2D > CreateTexture2D (wxInputStream &inputStream, size_t levelCount=0, bool generateMipmaps=true)
 Creates a new 2-dimensional texture from a wxInputStream.
boost::shared_ptr< CubeTexture > CreateCubeTexture (wxInputStream &positiveX, wxInputStream &negativeX, wxInputStream &positiveY, wxInputStream &negativeY, wxInputStream &positiveZ, wxInputStream &negativeZ, size_t levelCount=0, bool generateMipmaps=true)
 Creates a new cube texture from 6 wxInputStream objects.
boost::shared_ptr< Texture1D > CreateTexture1D (const wxFileName &fileName, size_t levelCount=0, bool generateMipmaps=true)
 Creates a new 1-dimensional texture from the given file.
boost::shared_ptr< Texture2D > CreateTexture2D (const wxFileName &fileName, size_t levelCount=0, bool generateMipmaps=true)
 Creates a new 2-dimensional texture from the given file.
boost::shared_ptr< CubeTexture > CreateCubeTexture (const wxFileName &positiveX, const wxFileName &negativeX, const wxFileName &positiveY, const wxFileName &negativeY, const wxFileName &positiveZ, const wxFileName &negativeZ, size_t levelCount=0, bool generateMipmaps=true)
 Creates a new cube texture from 6 files.
boost::shared_ptr< ShaderProgram > CreateShaderProgram ()
 Creates a new empty shader program.
boost::shared_ptr< ShaderProgram > CreateShaderProgram (const VertexAttribBinding &binding)
 Creates a new shader program with the given vertex attribute binding.
boost::shared_ptr< Shader > CreateShader (Shader::ShaderType shaderType, ShadingLanguage language)
 Creates a new shader of the specified type.
void SetShaderProgram (const boost::shared_ptr< ShaderProgram > &pShaderProgram, bool force=false)
 Sets the active shader program.
const boost::shared_ptr< ShaderProgram > & GetShaderProgram () const
 Returns the active shader program.
size_t GetRenderResourceCount () const
 Returns the number of render resources that are currently managed by this render context.
template<typename OutputIteratorT>
void GetRenderResources (OutputIteratorT it) const
 Returns shared pointers to all the render resources currently managed by this render context.
virtual void SetWorldMatrix (const Matrix4x4 &m)
 Sets the world matrix to the given matrix.
virtual void SetViewMatrix (const Matrix4x4 &m)
 Sets the view matrix to the given matrix.
virtual void SetProjectionMatrix (const Matrix4x4 &m)
 Sets the projection matrix to the given matrix.
const Matrix4x4 & GetWorldMatrix () const
 Returns the currently set world matrix.
const Matrix4x4 & GetViewMatrix () const
 Returns the currently set view matrix.
const Matrix4x4 & GetProjectionMatrix () const
 Returns the currently set projection matrix.
void BeginScene ()
 Begins a new scene.
void EndScene ()
 Ends a scene.
bool IsRendering () const
 Returns true if a scene is currently being rendered.
void Draw (PrimitiveType type, const VertexBufferStreamMapping &vertexBufferStreams, size_t startVertex, size_t primitiveCount)
 Renders the given vertex buffers to the active render target.
void Draw (PrimitiveType type, const boost::shared_ptr< const IndexBuffer > &pIndices, const VertexBufferStreamMapping &vertexBufferStreams, size_t startIndex, size_t primitiveCount, size_t minVertexIndex=0, size_t maxVertexIndex=0)
 Renders the given vertex buffers using the given index buffer to the active render target.
void SetState (const RenderState &state, bool force=false)
 Sets a render state.
template<typename RenderStateT>
const RenderStateT & GetState () const
 Returns a constant reference to a currently set render state.

Member Enumeration Documentation

enum PrimitiveType
 

This enum type lists all available primitive types in the engine.

Enumeration values:
PointList  List of points.
LineList  List of lines.
LineStrip  Line strip.
TriangleList  List of triangles.
TriangleStrip  Triangle strip.
TriangleFan  Triangle fan.

Member Function Documentation

void BeginScene (   ) 
 

Begins a new scene. This method must be called before any calls to any of the Draw methods have been made. After scene rendering is complete the scene must be ended by calling EndScene.

Exceptions:
BeginSceneException This exception is thrown whenever something goes wrong when beginning a new scene. If this exception is thrown EndScene must not be called.
Warning:
There must be an active render target when you call this method.

void Clear (  wxUint32  clearFlags  ) 
 

Clears the specified buffers of the active render target with the currently set clear values.

boost::shared_ptr< CubeTexture > CreateCubeTexture (  const wxFileName &  positiveX,
const wxFileName &  negativeX,
const wxFileName &  positiveY,
const wxFileName &  negativeY,
const wxFileName &  positiveZ,
const wxFileName &  negativeZ,
size_t  levelCount = 0,
bool  generateMipmaps = true
) 
 

Creates a new cube map texture from 6 files specified by the given file names. This method just creates wxFileInputStreams using the file names and then uses the corresponding other CreateCubeTexture method to load the texture. Please see there for more detailed documentation.

The 6 file names correspond to the 6 faces of the cube map texture in the following order:

  • positive x face
  • negative x face
  • positive y face
  • negative y face
  • positive z face
  • negative y face

See also:
RenderContext::CreateCubeTexture(const boost::array<wxFileName, 6>& fileNames, size_t levelCount, bool generateMipmaps)

boost::shared_ptr< CubeTexture > CreateCubeTexture (  wxInputStream &  positiveX,
wxInputStream &  negativeX,
wxInputStream &  positiveY,
wxInputStream &  negativeY,
wxInputStream &  positiveZ,
wxInputStream &  negativeZ,
size_t  levelCount = 0,
bool  generateMipmaps = true
) 
 

Creates a new cube map texture from 6 wxInputStreams. All 6 images should have the same dimensions. If they don't the first image's dimensions will be used as reference and all other images will be resized to its size. Furthermore, the width and height should be equal for all images for cube map textures. If width and height of the first image are not equal the larger of the two will be used as edge length and the image resized appropriately. Also note that when the images have different pixel formats, the first image determines the pixel format of the cube texture. All other images will be converted to that pixel format.

This method first tries to use the DevIL library to load images from the input streams. If DevIL for some reason cannot handle the given file format or XEngine has been built without DevIL, the wxImage loaders of wxWindows will try to load the files.

When DevIL is used to load an image from the input stream, the texture format is determined by the corresponding format returned by DevIL. If the wxImage loaders are used the texture format will be RGB8 since wxImage only supports that format. However, even when using DevIL, only the following formats will be used:

Note that paletted images are currently unsupported by XEngine and will be converted to one of the types listed above.

If the width or height of the loaded images is not a power of 2 the images will be resized using iluScale or wxImage::Scale, so that the width and height of the image is a power of 2.

Parameters:
positiveX The input stream for the positive x face of the cube map.
negativeX The input stream for the negative x face of the cube map.
positiveY The input stream for the positive y face of the cube map.
negativeY The input stream for the negative y face of the cube map.
positiveZ The input stream for the positive z face of the cube map.
negativeZ The input stream for the negative z face of the cube map.
levelCount The number of mipmap levels to be created. If the number of mipmap levels is 0, a full chain of mipmap levels down to a dimension of 1x1 will be automatically created and once the level 0 texture image is set the mimmap images will be created automatically as well.
generateMipmaps If this parameter is set to true, once a mipmap level data is set, the mipmap data of all subsequent mipmap levels will be automatically generated. This elevates the client application of manually specifying mipmap data.

boost::shared_ptr< CubeTexture > CreateCubeTexture (  const wxImage &  positiveX,
const wxImage &  negativeX,
const wxImage &  positiveY,
const wxImage &  negativeY,
const wxImage &  positiveZ,
const wxImage &  negativeZ,
size_t  levelCount = 0,
bool  generateMipmaps = true
) 
 

Creates a new cube texture from 6 wxImage objects. All 6 images should have the same dimensions. If they don't the first image's dimensions will be used as reference and all other images will be resized to its size. Furthermore, the width and height should be equal for all images for cube map textures. If width and height of the first image are not equal the larger of the two will be used as edge length and the image resized appropriately.

The 6 images correspond to the 6 faces of the cube map texture in the following order:

  • positive x face
  • negative x face
  • positive y face
  • negative y face
  • positive z face
  • negative y face

Note that since the wxImage class always stores pictures in RGB8 format, that's what will be used for the internal texture format.

If the dimensions of the given wxImage objects are not a power of 2 the images will be resized using wxImage::Scale, so that both the width and height of the images are a power of 2.

Parameters:
positiveX,negativeX,positiveY,negativeY,positiveZ,negativeZ The wxImage objects that are used to create level 0 of the cube texture.
levelCount The number of mipmap levels to be created. If the number of mipmap levels is 0, a full chain of mipmap levels down to a dimension of 1x1 will be automatically created and once the level 0 texture image is set the mimmap images will be created automatically as well.
generateMipmaps If this parameter is set to true, once a mipmap level data is set, the mipmap data of all subsequent mipmap levels will be automatically generated. This elevates the client application of manually specifying mipmap data.

boost::shared_ptr< CubeTexture > CreateCubeTexture (  unsigned int  edgeLength,
const PixelFormat &  format,
size_t  levelCount = 0,
bool  generateMipmaps = true
) 
 

Creates a new cube texture resource with the specified dimensions, texture format and number of mipmap levels.

Parameters:
edgeLength The edge length of level 0 of the texture.
format The texture format. Note that this format must not necessarily be the format in which the data is stored internally.
levelCount The number of mipmap levels to be created. If the number of mipmap levels is 0, a full chain of mipmap levels down to a dimension of 1x1 will be automatically created.
generateMipmaps If this parameter is set to true, once a mipmap level data is set, the mipmap data of all subsequent mipmap levels will be automatically generated. This elevates the client application of manually specifying mipmap data.

boost::shared_ptr< IndexBuffer > CreateIndexBuffer (  RenderBuffer::BufferType  bufferType,
RenderBuffer::UsageFlags  usage,
size_t  count,
IndexBuffer::Type  type
) 
 

Creates a new index buffer with the specified maximum number of indices that can be stored in the buffer. The usage flag should be set as restrictive as possible, as this might drastically improve performance.

Parameters:
bufferType The buffer type (static, stream, or dynamic).
usage Usage flag that indicates which application access the buffer allows.
count The number of indices the buffer is supposed to hold
type The type of the indices (16 bits or 32 bits). Smaller indices will give better performance on most systems.

boost::shared_ptr< RenderTarget > CreateRenderTarget (  const RenderTarget::Format &  format  ) 
 

Creates a new render target according to the given type and format. Note that some render contexts do not support the creation of multiple instances of a certain render target type. For example, it might not be possible to have more than one full screen render window.

boost::shared_ptr< Shader > CreateShader (  Shader::ShaderType  shaderType,
ShadingLanguage  language
) 
 

Creates a new shader of the specified type and language. Note that only the shading languages advertised in the render context capabilities can be used, anything else will result in an exception.

boost::shared_ptr< ShaderProgram > CreateShaderProgram (  const VertexAttribBinding &  binding  ) 
 

Creates a new shader program with the given vertex attribute binding.

boost::shared_ptr< ShaderProgram > CreateShaderProgram (   ) 
 

Creates a new empty shader program. Before the shader program can be linked a vertex attribute binding must be set for the shader program via ShaderProgram::SetVertexAttribBinding.

boost::shared_ptr< StateSet > CreateStateSet (   ) 
 

Creates a new state set and returns a shared pointer to it.

Just like instances of RenderResource-derived classes, state sets are always passed around as shared pointers. When the client deletes the render context that created a state set, all outstanding references (i.e. all shared pointer objects pointing to the state set) must have already been released beforehand.

boost::shared_ptr< Texture1D > CreateTexture1D (  const wxFileName &  fileName,
size_t  levelCount = 0,
bool  generateMipmaps = true
) 
 

Creates a new 1-dimensional texture from a file specified by the given file name. This method just creates a wxFileInputStream using the file name and then uses the corresponding other CreateTexture1D method to load the texture. Please see there for more detailed documentation.

See also:
RenderContext::CreateTexture1D(wxInputStream& inputStream, size_t levelCount, bool generateMipmaps)

boost::shared_ptr< Texture1D > CreateTexture1D (  wxInputStream &  inputStream,
size_t  levelCount = 0,
bool  generateMipmaps = true
) 
 

Creates a new 1-dimensional texture from a wxInputStream. This method first tries to use the DevIL library to load an image from the input stream. If DevIL for some reason cannot handle the given file format or XEngine has been built without DevIL, the wxImage loaders of wxWindows will try to load the file.

When DevIL is used to load an image from the input stream, the texture format is determined by the corresponding format returned by DevIL. If the wxImage loaders are used the texture format will be RGB8 since wxImage only supports that format. However, even when using DevIL, only the following formats will be used:

Note that paletted images are currently unsupported by XEngine and will be converted to one of the types listed above.

If the width of the loaded image is not a power of 2 the image will be resized using iluScale or wxImage::Scale, so that the width of the image is a power of 2. If the height of the image is not 1 only the first row of the image will be used for the texture.

Parameters:
inputStream The input stream that is used to load level 0 of the texture.
levelCount The number of mipmap levels to be created. If the number of mipmap levels is 0, a full chain of mipmap levels down to a dimension of 1x1 will be automatically created and once the level 0 texture image is set the mimmap images will be created automatically as well.
generateMipmaps If this parameter is set to true, once a mipmap level data is set, the mipmap data of all subsequent mipmap levels will be automatically generated. This elevates the client application of manually specifying mipmap data.

boost::shared_ptr< Texture1D > CreateTexture1D (  const wxImage &  image,
size_t  levelCount = 0,
bool  generateMipmaps = true
) 
 

Creates a new 1-dimensional texture resource from the given RGB wxImage and the specified number of mipmap levels. Note that since the wxImage class always stores pictures in RGB8 format, that's what will be used for the internal texture format.

If the width of the given wxImage object is not a power of 2 the image will be resized using wxImage::Scale, so that the width of the image is a power of 2. If the height of the image is not 1 only the first row of the image will be used for the texture.

Parameters:
image The wxImage object that is used to create level 0 of the texture.
levelCount The number of mipmap levels to be created. If the number of mipmap levels is 0, a full chain of mipmap levels down to a dimension of 1x1 will be automatically created and once the level 0 texture image is set the mimmap images will be created automatically as well.
generateMipmaps If this parameter is set to true, once a mipmap level data is set, the mipmap data of all subsequent mipmap levels will be automatically generated. This elevates the client application of manually specifying mipmap data.

boost::shared_ptr< Texture1D > CreateTexture1D (  unsigned int  width,
const PixelFormat &  format,
size_t  levelCount = 0,
bool  generateMipmaps = true
) 
 

Creates a new 1-dimensional texture resource with the specified dimensions, texture format and number of mipmap levels.

Parameters:
width The width of level 0 of the texture.
format The texture format. Note that this format must not necessarily be the format in which the data is stored internally.
levelCount The number of mipmap levels to be created. If the number of mipmap levels is 0, a full chain of mipmap levels down to a dimension of 1x1 will be automatically created.
generateMipmaps If this parameter is set to true, once a mipmap level data is set, the mipmap data of all subsequent mipmap levels will be automatically generated. This elevates the client application of manually specifying mipmap data.

boost::shared_ptr< Texture2D > CreateTexture2D (  const wxFileName &  fileName,
size_t  levelCount = 0,
bool  generateMipmaps = true
) 
 

Creates a new 2-dimensional texture from a file specified by the given file name. This method just creates a wxFileInputStream using the file name and then uses the corresponding other CreateTexture2D method to load the texture. Please see there for more detailed documentation.

See also:
RenderContext::CreateTexture2D(wxInputStream& inputStream, size_t levelCount, bool generateMipmaps)

boost::shared_ptr< Texture2D > CreateTexture2D (  wxInputStream &  inputStream,
size_t  levelCount = 0,
bool  generateMipmaps = true
) 
 

Creates a new 2-dimensional texture from a wxInputStream. This method first tries to use the DevIL library to load an image from the input stream. If DevIL for some reason cannot handle the given file format or XEngine has been built without DevIL, the wxImage loaders of wxWindows will try to load the file.

When DevIL is used to load an image from the input stream, the texture format is determined by the corresponding format returned by DevIL. If the wxImage loaders are used the texture format will be RGB8 since wxImage only supports that format. However, even when using DevIL, only the following formats will be used:

Note that paletted images are currently unsupported by XEngine and will be converted to one of the types listed above.

If the width or height of the loaded image is not a power of 2 the image will be resized using iluScale or wxImage::Scale, so that the width and height of the image is a power of 2.

Parameters:
inputStream The input stream that is used to load level 0 of the texture.
levelCount The number of mipmap levels to be created. If the number of mipmap levels is 0, a full chain of mipmap levels down to a dimension of 1x1 will be automatically created and once the level 0 texture image is set the mimmap images will be created automatically as well.
generateMipmaps If this parameter is set to true, once a mipmap level data is set, the mipmap data of all subsequent mipmap levels will be automatically generated. This elevates the client application of manually specifying mipmap data.

boost::shared_ptr< Texture2D > CreateTexture2D (  const wxImage &  image,
size_t  levelCount = 0,
bool  generateMipmaps = true
) 
 

Creates a new 2-dimensional texture resource from the given RGB wxImage and the specified number of mipmap levels. Note that since the wxImage class always stores pictures in RGB8 format, that's what will be used for the internal texture format.

If the dimensions of the given wxImage object are not a power of 2 the image will be resized using wxImage::Scale, so that both the width and height of the image are a power of 2.

Parameters:
image The wxImage object that is used to create level 0 of the texture.
levelCount The number of mipmap levels to be created. If the number of mipmap levels is 0, a full chain of mipmap levels down to a dimension of 1x1 will be automatically created and once the level 0 texture image is set the mimmap images will be created automatically as well.
generateMipmaps If this parameter is set to true, once a mipmap level data is set, the mipmap data of all subsequent mipmap levels will be automatically generated. This elevates the client application of manually specifying mipmap data.

boost::shared_ptr< Texture2D > CreateTexture2D (  unsigned int  width,
unsigned int  height,
const PixelFormat &  format,
size_t  levelCount = 0,
bool  generateMipmaps = true
) 
 

Creates a new 2-dimensional texture resource with the specified dimensions, texture format and number of mipmap levels.

Parameters:
width The width of level 0 of the texture.
height The height of level 0 of the texture.
format The texture format. Note that this format must not necessarily be the format in which the data is stored internally.
levelCount The number of mipmap levels to be created. If the number of mipmap levels is 0, a full chain of mipmap levels down to a dimension of 1x1 will be automatically created.
generateMipmaps If this parameter is set to true, once a mipmap level data is set, the mipmap data of all subsequent mipmap levels will be automatically generated. This elevates the client application of manually specifying mipmap data.

boost::shared_ptr< Texture3D > CreateTexture3D (  unsigned int  width,
unsigned int  height,
unsigned int  depth,
const PixelFormat &  format,
size_t  levelCount = 0,
bool  generateMipmaps = true
) 
 

Creates a new 3-dimensional texture resource with the specified dimensions, texture format and number of mipmap levels.

Parameters:
width The width of level 0 of the texture.
height The height of level 0 of the texture.
depth The depth of level 0 of the texture.
format The texture format. Note that this format must not necessarily be the format in which the data is stored internally.
levelCount The number of mipmap levels to be created. If the number of mipmap levels is 0, a full chain of mipmap levels down to a dimension of 1x1 will be automatically created.
generateMipmaps If this parameter is set to true, once a mipmap level data is set, the mipmap data of all subsequent mipmap levels will be automatically generated. This elevates the client application of manually specifying mipmap data.

boost::shared_ptr< VertexBuffer > CreateVertexBuffer (  RenderBuffer::BufferType  bufferType,
RenderBuffer::UsageFlags  usage,
size_t  count,
const VertexFormat &  format
) 
 

Creates a new vertex buffer with the specified number of vertices that can be stored in the buffer. The usage flag should be set as restrictive as possible, as this might drastically improve performance.

Parameters:
bufferType The buffer type (static, stream, or dynamic).
usage Usage flag that indicates which application access the buffer allows.
count The number of vertices the buffer is supposed to hold
format The format specification of the vertex type structure.

void Draw (  PrimitiveType  type,
const boost::shared_ptr< const IndexBuffer > &  pIndices,
const VertexBufferStreamMapping &  vertexBufferStreams,
size_t  startIndex,
size_t  primitiveCount,
size_t  minVertexIndex = 0,
size_t  maxVertexIndex = 0
) 
 

Renders the given vertex buffer using the given index buffer to the active render target. Passing in a locked vertex buffer or index buffer will result in undefined behavior. The debug build of the library asserts in this case.

Parameters:
type The primitive type (points, lines or triangles).
pIndices The indices into the vertex buffer that describe the primitives.
vertexBufferStreams The vertex data that gets indexed by the indices stored in one or more vertex buffer streams.
startIndex The start offset into the index buffer where rendering is supposed to begin.
primitiveCount The number of primitives to render.
minVertexIndex The minimum vertex index occuring in the index buffer. If you specify this, be sure that it really is the minimum vertex index used. If specified, optimizes performance because the vertex buffer will only have to be accessed starting with the vertex indexed by minVertexIndex.
maxVertexIndex The maximum vertex index occuring in the in index buffer If this value is 0, then the maximum possible vertex index (which corresponds to the size of the vertex buffer - 1) will be used.
Warning:
The primitive type PointList is not allowed when calling this method.

There must be an active render target when you call this method.

void Draw (  PrimitiveType  type,
const VertexBufferStreamMapping &  vertexBufferStreams,
size_t  startVertex,
size_t  primitiveCount
) 
 

Renders the given vertex buffer to the active render target. Passing in a locked vertex buffer will result in undefined behavior. The debug build of the library asserts in this case.

Parameters:
type The primitive type (points, lines or triangles).
vertexBufferStreams The vertices to render stored in one or multiple vertex buffer streams.
startVertex The start vertex offset into the vertex buffer where rendering is supposed to begin. All vertices before the specified start offset are ignored.
primitiveCount The number of primitives to render.
Warning:
There must be an active render target when you call this method.

void EndScene (   ) 
 

Ends a scene. This method must only be called after a successful call to BeginScene.

Warning:
There must be an active render target when you call this method.

unsigned int GetAdapter (   )  const
 

Returns the adapter that is used by this context.

const AdapterInfo & GetAdapterInfo (   )  const
 

Returns the adapter info object of the adapter used by this context.

const RenderContextCaps & GetCaps (   )  const
 

Returns the capabilities object for this render context.

unsigned int GetDevice (   )  const
 

Returns the device/driver that is used by this context.

const DeviceInfo & GetDeviceInfo (   )  const
 

Returns the device info object of the device used by this context.

const boost::shared_ptr< RenderWindow > & GetPrimaryRenderWindow (   )  const
 

Returns the primary render window of this render context.

const Matrix4x4 & GetProjectionMatrix (   )  const
 

Returns the currently set projection matrix.

const boost::shared_ptr< Renderer > & GetRenderer (   )  const
 

Returns the renderer object that created this render context.

size_t GetRenderResourceCount (   )  const
 

Returns the number of render resources that are currently managed by this render context.

void GetRenderResources (  OutputIteratorT  it  )  const
 

Returns shared pointers to all the render resources currently managed by this render context. The given output iterator must accept objects of type boost::shared_ptr<RenderResource>.

const boost::shared_ptr< RenderTarget > & GetRenderTarget (   )  const
 

Returns the currently active render target of this renderer.

size_t GetRenderTargetCount (  RenderTarget::Type  renderTargetType  )  const
 

Returns the number of render targets of the given type created so far.

void GetRenderTargets (  OutputIteratorT  it  )  const
 

Returns all render targets currently managed by this render context via the given output iterator, which must accept objects of type boost::shared_ptr<RenderTarget>.

size_t GetRenderWindowCount (   )  const
 

Returns the number of all render windows (all RenderWindow-derived classes) created so far.

const boost::shared_ptr< ShaderProgram > & GetShaderProgram (   )  const
 

Returns the active shader program.

const RenderStateT & GetState (   )  const
 

Returns a reference to a currently set render state.

boost::shared_ptr< const StateSet > GetStateSet (   )  const
 

Returns a pointer to the state set of this render context. The returned state set contains the current state of the render context. Therefore the state set has all available states set. Note that the returned pointer is const and therefore the state set cannot be modified. Use the SetState member functions, e.g. of RenderContext, to change states.

const boost::shared_ptr< TextureCoordStage > & GetTextureCoordStage (  size_t  stage  )  const
 

Returns a pointer to a texture coordinate stage.

Warning:
Do not try to access a not available texture coordinate stage. The number of available texture coordinate stages depends on the graphics hardware. The engine guarantees that at least one texture coordinate stage is present in the system. Any additional stages are implementation-dependent. If you try to access a non-existing texture coordinate stage, a NotAvailableException exception gets thrown.

const boost::shared_ptr< TextureSamplerStage > & GetTextureSamplerStage (  size_t  stage  )  const
 

Returns a pointer to a texture sampler stage.

Warning:
Do not try to access a not available texture sampler stage. The number of available texture sampler stages depends on the graphics hardware. The engine guarantees that at least one texture sampler stage is present in the system. Any additional stages are implementation-dependent. If you try to access a non-existing texture sampler stage, a NotAvailableException exception gets thrown.

const Matrix4x4 & GetViewMatrix (   )  const
 

Returns the currently set view matrix.

const Matrix4x4 & GetWorldMatrix (   )  const
 

Returns the currently set world matrix.

bool IsRendering (   )  const
 

Returns true if a scene is currently being rendered, that is BeginScene has been called, but EndScene has not yet been called.

void SetDefaultRenderState (   ) 
 

Sets the default render state for all render states. Usually, this method shouldn't be called by a user application. But it can be used to kind of reset the render context.

The default state looks like this:

  • A fixed-function pipeline shader program is set active for the VertexTypePrimColor vertex type and its corresponding vertex attribute binding.

  • The world matrix is set to the identity.
  • The view matrix is set to the identity.
  • The projection matrix is set to a perspective projection matrix with a vertical field-of-view of 60 degrees, an aspect ratio of 4/3, a z-near plane of 1.0 and a z-far plane of 1000.0.

  • The color buffer clear value is the RGB color (0, 0, 0).
  • The depth buffer clear value is set to 1 (farthes distance to the viewer).
  • The stencil buffer clear value is set to 0.

  • Depth testing is enabled.
  • Depth buffer writes are enabled.
  • The depth buffer comparison function is set to RSDepthBuffer::Less.
  • The depth range is set to range from 0 to 1.

  • Stencil buffering is disabled.
  • The stencil buffer comparison function is set to RSStencilBuffer::Always.
  • The stencil reference value is 0.
  • The stencil mask used with the reference value and buffer entries is set to 0xffffffff.
  • The stencil write mask is set to 0xffffffff.
  • The stencil buffer fail operation, z-fail operation and pass operation are all set to RSStencilBuffer::Keep.

  • The cull mode is set to cull clockwise-oriented faces.
  • The fill mode is set to solid.
  • The shade mode is set to Gouraud shading.

  • The default material is set to the following:
    • Diffuse color = (0.8, 0.8, 0.8, 1.0)
    • Specular color = (0.0, 0.0, 0.0, 1.0)
    • Ambient color = (0.2, 0.2, 0.2, 1.0)
    • Emissive color = (0.0, 0.0, 0.0, 1.0)
    • Shininess = 0.0

  • Automatic normalization of normals is deactivated.
  • Dithering is disabled.

  • Alpha testing is disabled.
  • The alpha test reference value is set to 0.
  • The alpha test compare function is set to RSAlphaTest::Greater.

  • Frame buffer blending is disabled.
  • Separate color and alpha blending is disabled.
  • The color and alpha blending function is set to RSBlendMode::Add.
  • The source argument is set to RSBlendMode::One.
  • The destination argument is set to RSBlendMode::Zero.

  • Lighting is disabled.
  • Light 0 is set to a directional light with the following values:
    • The direction is set to (0, 0, -1), so in parallel to and in direction of the negative z-axis.
    • The diffuse color is set to (1, 1, 1, 1) for light 0 and to (0, 0, 0, 1) for all other lights.
    • The specular color is set to (0, 0, 0, 1).
    • The ambient color is set to (0, 0, 0, 1).
  • All other lights are set to an undefined state!
  • All lights are disabled, except for light 0 which is enabled.
  • The global ambient color is set to (0.2, 0.2, 0.2, 1.0).
  • The local viewer flag is set to true.

  • Color material is disabled.
  • The material parameter to be tracked by the primary color is set to RSColorMaterial::Diffuse.

  • All user-defined clipping planes are disabled.
  • The first user-defined clipping plane is set to (A, B, C, D) = (0, 1, 0, 0).
  • All other user-defined clipping planes are in an undefined state!

  • Fog is disabled.
  • The fog formula is set to RSFog::Exp.
  • The fog color is set to (0, 0, 0, 0).
  • The fog density is set to 1.0.
  • The fog start value is set to 0.0.
  • The fog end value is set to 1.0.

  • The scissor test is disabled.
  • The scissor rectangle is set to cover the entire render target. If no render target is currently set the scissor rectangle is set to (0, 0, 0, 0).

  • The default point size is set to 1.
  • The point size range is set to [1, 1].
  • The distance attenuation values are set to A = 1, B = 0, and C = 0.
  • Point sprite rendering is disabled.

See also:
RenderContext::SetDefaultState

TextureSamplerStage::SetDefaultState

TextureCoordStage::SetDefaultState

void SetDefaultState (   ) 
 

Sets the default state of the complete set of states of this render context. This includes all render states, texture sampler states, texture coordinate states, the shader program and all textures.

See also:
RenderContext::SetDefaultRenderState

TextureSamplerStage::SetDefaultState

TextureCoordStage::SetDefaultState

void SetProjectionMatrix (  const Matrix4x4 &  m  )  [virtual]
 

Sets the projection matrix to the given matrix.

void SetRenderTarget (  const boost::shared_ptr< RenderTarget > &  pTarget  ) 
 

Sets the active render target to the given render target. All subsequent Draw calls will render to this target. Passing in an empty poniter as active render target is allowed, but you must not call RenderContext::BeginScene, RenderContext::EndScene or any RenderContext::Draw calls, if there is no active render target.

The scissor rectangle is reset to the size of the entire render target when a new render target is set. See the RSScissor render state.

Warning:
Do not call this method in between RenderContext::BeginScene and RenderContext::EndScene. Note that only render targets created using this render context can be made active.

If you call SetRenderTarget on a render texture that is set as active texture in any texture sampler stage, then the texture for those stages will be set to NULL.

void SetShaderProgram (  const boost::shared_ptr< ShaderProgram > &  pShaderProgram,
bool  force = false
) 
 

Sets the active shader program. Initially, when a new render context has just been created, a shader program using the fixed-function pipline is set, which uses the vertex attribute binding of the VertexTypePrimColor vertex type.

XEngine internally caches all render states, and therefore also the active shader program. If the shader program that is currently active is the same as the given shader program, this method won't do anything, unless the force parameter is set to true. If the force parameter is true, the shader program will always be set, even if it is the same as the active shader program. This is mostly used internally by XEngine to synchronize with the underlying graphics APIs.

void SetState (  const RenderState &  state,
bool  force = false
) 
 

Sets a render state. Depending on the type of the given render state object the corresponding render state will be set. For example, if the passed in object is a RSDepthBuffer depth buffer render state object then the depth buffer render state is changed according to the information in that render state object. Only active properties of the given render state object will be considered, so this actually behaves like a merge (see StateBase::Merge).

XEngine internally caches all render states. If an attempt is made to set a state that is already set (as indicated by the internal cache), this method doesn't do anything, unless the force parameter is set to true. If the force parameter is true, the state will always be set, even if it is the same as the currently set state. This is mostly used internally by XEngine to synchronize with the underlying graphics APIs.

void SetViewMatrix (  const Matrix4x4 &  m  )  [virtual]
 

Sets the view matrix to the given matrix.

void SetWorldMatrix (  const Matrix4x4 &  m  )  [virtual]
 

Sets the world matrix to the given matrix.

void Swap (   ) 
 

Swaps the front with the back buffer of the active render target, if it supports swapping.

The documentation for this class was generated from the following files:

 

 
Created with doxygen on: Thu Jan 6 14:11:40 2005
Copyright © by Martin Ecker