Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

Ogre::D3D9RenderSystem Class Reference

Implementation of DirectX9 as a rendering system. More...

#include <OgreD3D9RenderSystem.h>

Inheritance diagram for Ogre::D3D9RenderSystem:

Ogre::RenderSystem List of all members.

Public Methods

virtual ResizeRepositionWindow (HWND wich)
void SetExternalWindowHandle (HWND externalHandle)
void setFullScreenMultiSamplingPasses (DWORD numPasses)
 D3D9RenderSystem (HINSTANCE hInstance)
 ~D3D9RenderSystem ()
const StringgetName (void) const
 Returns the name of the rendering system. More...

ConfigOptionMapgetConfigOptions (void)
 Returns the details of this API's configuration options. More...

void setConfigOption (const String &name, const String &value)
 Sets an option for this API. More...

String validateConfigOptions (void)
 Validates the options set for the rendering system, returning a message if there are problems. More...

RenderWindowinitialise (bool autoCreateWindow)
 Start up the renderer using the settings selected (Or the defaults if none have been selected). More...

void reinitialise ()
 Restart the renderer (normally following a change in settings). More...

void shutdown ()
 Shutdown the renderer and cleanup resources. More...

void startRendering ()
 Starts / restarts the automatic rendering cycle. More...

void setAmbientLight (float r, float g, float b)
 Sets the colour & strength of the ambient (global directionless) light in the world. More...

void setShadingType (ShadeOptions so)
 Sets the type of light shading required (default = Gouraud). More...

void setTextureFiltering (TextureFilterOptions fo)
 Sets the type of texture filtering used when rendering. More...

void setLightingEnabled (bool enabled)
 Sets whether or not dynamic lighting is enabled. More...

RenderWindowcreateRenderWindow (const String &name, int width, int height, int colourDepth, bool fullScreen, int left=0, int top=0, bool depthBuffer=true, RenderWindow *parentWindowHandle=0)
 Creates a new rendering window. More...

RenderTexturecreateRenderTexture (const String &name, int width, int height)
 Creates and registers a render texture object. More...

void destroyRenderWindow (RenderWindow *pWin)
String getErrorDescription (long errorNumber)
 Returns a description of an error code. More...

void convertColourValue (const ColourValue &colour, unsigned long *pDest)
 Generates a packed data version of the passed in ColourValue suitable for use as with this RenderSystem. More...

void _addLight (Light *lt)
 Adds a light to the renderers list of active lights. More...

void _removeLight (Light *lt)
 Removes a light from the renderers list. More...

void _modifyLight (Light *lt)
 Modifies a light in the renderer. More...

void _removeAllLights (void)
 Clears all the lights from the renderer. More...

void _pushRenderState (void)
 Saves the current rendering state. More...

void _popRenderState (void)
 Restores the render state to a previous state. More...

void _setWorldMatrix (const Matrix4 &m)
 Sets the world transform matrix. More...

void _setViewMatrix (const Matrix4 &m)
 Sets the view transform matrix. More...

void _setProjectionMatrix (const Matrix4 &m)
 Sets the projection transform matrix. More...

void _setSurfaceParams (const ColourValue &ambient, const ColourValue &diffuse, const ColourValue &specular, const ColourValue &emissive, Real shininess)
 Sets the surface properties to be used for future rendering. More...

unsigned short _getNumTextureUnits (void)
 Returns the number of texture units the current output hardware supports. More...

void _setTexture (int unit, bool enabled, const String &texname)
 Sets the status of a single texture stage. More...

void _setTextureCoordSet (int stage, int index)
 Sets the texture coordinate set to use for a texture unit. More...

void _setTextureCoordCalculation (int stage, TexCoordCalcMethod m)
 Sets a method for automatically calculating texture coordinates for a stage. More...

void _setTextureBlendMode (int stage, const LayerBlendModeEx &bm)
 Sets the texture blend modes from a TextureLayer record. More...

void _setTextureAddressingMode (int stage, Material::TextureLayer::TextureAddressingMode tam)
 Sets the texture addressing mode for a texture unit. More...

void _setTextureMatrix (int stage, const Matrix4 &xform)
 Sets the texture coordinate transformation matrix for a texture unit. More...

void _setSceneBlending (SceneBlendFactor sourceFactor, SceneBlendFactor destFactor)
 Sets the global blending factors for combining subsequent renders with the existing frame contents. More...

void _setAlphaRejectSettings (CompareFunction func, unsigned char value)
 Sets the global alpha rejection approach for future renders. More...

void _setViewport (Viewport *vp)
 Sets the provided viewport as the active one for future rendering operations. More...

void _beginFrame (void)
 Signifies the beginning of a frame, ie the start of rendering on a single viewport. More...

void _render (RenderOperation &op)
 Render something to the active viewport. More...

void _endFrame (void)
 Ends rendering of a frame to the current viewport. More...

void _setCullingMode (CullingMode mode)
 Sets the culling mode for the render system based on the 'vertex winding'. More...

void _setDepthBufferParams (bool depthTest=true, bool depthWrite=true, CompareFunction depthFunction=CMPF_LESS_EQUAL)
 Sets the mode of operation for depth buffer tests from this point onwards. More...

void _setDepthBufferCheckEnabled (bool enabled=true)
 Sets whether or not the depth buffer check is performed before a pixel write. More...

void _setDepthBufferWriteEnabled (bool enabled=true)
 Sets whether or not the depth buffer is updated after a pixel write. More...

void _setDepthBufferFunction (CompareFunction func=CMPF_LESS_EQUAL)
 Sets the comparison function for the depth buffer check. More...

void _setMultiSampleAntiAlias (BOOL set)
void _setDepthBias (ushort bias)
 See RenderSystem. More...

void _setFog (FogMode mode=FOG_NONE, ColourValue colour=ColourValue::White, Real expDensity=1.0, Real linearStart=0.0, Real linearEnd=1.0)
 Sets the fogging mode for future geometry. More...

void _makeProjectionMatrix (Real fovy, Real aspect, Real nearPlane, Real farPlane, Matrix4 &dest)
 Builds a perspective projection matrix suitable for this render system. More...

void _setRasterisationMode (SceneDetailLevel level)
 Sets how to rasterise triangles, as points, wireframe or solid polys. More...

void setStencilCheckEnabled (bool enabled)
 See RenderSystem. More...

bool hasHardwareStencil (void)
 See RenderSystem. More...

ushort getStencilBufferBitDepth (void)
 See RenderSystem. More...

void setStencilBufferFunction (CompareFunction func)
 See RenderSystem. More...

void setStencilBufferReferenceValue (ulong refValue)
 See RenderSystem. More...

void setStencilBufferMask (ulong mask)
 See RenderSystem. More...

void setStencilBufferFailOperation (StencilOperation op)
 See RenderSystem. More...

void setStencilBufferDepthFailOperation (StencilOperation op)
 See RenderSystem. More...

void setStencilBufferPassOperation (StencilOperation op)
 See RenderSystem. More...

virtual void addFrameListener (FrameListener *newListener)
 Registers a FrameListener which will be called back every frame. More...

virtual void removeFrameListener (FrameListener *oldListener)
 Removes a FrameListener from the list of listening classes. More...

virtual void attachRenderTarget (RenderTarget &target)
 Don't do this anymore, just allow via Root RenderSystem* regPtr = Root::getSingleton().getRenderSystem(); if (!regPtr || regPtr != this) Register self - library user has come to me direct Root::getSingleton().setRenderSystem(this);. More...

virtual RenderTargetgetRenderTarget (const String &name)
 Returns a pointer to the render target with the passed name, or NULL if that render target cannot be found. More...

virtual RenderTargetdetachRenderTarget (const String &name)
 Detaches the render target with the passed name from the render system and returns a pointer to it. More...

void setWaitForVerticalBlank (bool enabled)
 Defines whether or now fullscreen render windows wait for the vertical blank before flipping buffers. More...

bool getWaitForVerticalBlank (void)
 Returns true if the system is synchronising frames with the monitor vertical blank. More...

virtual void _setWorldMatrices (const Matrix4 *m, unsigned short count)
 Sets multiple world matrices (vertex blending). More...

virtual void _setTextureUnitSettings (int texUnit, Material::TextureLayer &tl)
 Utility function for setting all the properties of a texture unit at once. More...

virtual void _disableTextureUnit (int texUnit)
 Turns off a texture unit. More...

virtual Viewport_getViewport (void)
 Get the current active viewport for rendering. More...

virtual CullingMode _getCullingMode (void)
virtual void _beginGeometryCount (void)
 The RenderSystem will keep a count of tris rendered, this resets the count. More...

virtual unsigned int _getFaceCount (void)
 Reports the number of tris rendered since the last _beginGeometryCount call. More...

virtual unsigned int _getVertexCount (void)
 Reports the number of vertices passed to the renderer since the last _beginGeometryCount call. More...

virtual bool _isVertexBlendSupported (void)
 Returns whether or not this RenderSystem supports hardware vertex blending, ie multiple world matrices per vertex with blending weights. More...

virtual unsigned short _getNumVertexBlendMatrices (void)
 Returns the number of matrices available to hardware vertex blending for this rendering system. More...

virtual void setStencilBufferParams (CompareFunction func=CMPF_ALWAYS_PASS, ulong refValue=0, ulong mask=0xFFFFFFFF, StencilOperation stencilFailOp=SOP_KEEP, StencilOperation depthFailOp=SOP_KEEP, StencilOperation passOp=SOP_KEEP)
 This method allows you to set all the stencil buffer parameters in one call. More...

void softwareVertexBlend (RenderOperation &op, Matrix4 *pMatrices)
 Performs a software vertex blend on the passed in operation. More...


Protected Methods

bool fireFrameStarted (FrameEvent &evt)
 Internal method for raising frame started events. More...

bool fireFrameEnded (FrameEvent &evt)
 Internal method for raising frame ended events. More...


Protected Attributes

std::set< FrameListener * > mFrameListeners
 Set of registered frame listeners. More...

ConfigOptionMap mOptions
RenderTargetMap mRenderTargets
 The render targets. More...

RenderTargetPriorityMap mPrioritisedRenderTargets
 The render targets, ordered by priority. More...

RenderTargetmActiveRenderTarget
 The Active render target. More...

TextureManagermTextureManager
ViewportmActiveViewport
CullingMode mCullingMode
bool mVSync
Material::TextureLayer mTextureUnits [OGRE_MAX_TEXTURE_LAYERS]
unsigned int mFaceCount
unsigned int mVertexCount
Matrix4 mWorldMatrices [256]
 Saved set of world matrices. More...

std::vector< RealmTempVertexBlendBuffer
 Temporary buffer for vertex blending in software. More...

std::vector< RealmTempNormalBlendBuffer

Private Methods

D3D9DriverListgetDirect3DDrivers (void)
void refreshD3DSettings (void)
bool compareDecls (D3DVERTEXELEMENT9 *pDecl1, D3DVERTEXELEMENT9 *pDecl2, int size)
D3DXMATRIX makeD3DXMatrix (const Matrix4 &mat)
Matrix4 convertD3DXMatrix (const D3DXMATRIX &mat)
void initConfigOptions (void)
void initInputDevices (void)
void processInputDevices (void)
void setD3D9Light (int index, Light *light)
D3DCMPFUNC convertCompareFunction (CompareFunction func)
D3DSTENCILOP convertStencilOp (StencilOperation op)
HRESULT __SetRenderState (D3DRENDERSTATETYPE state, DWORD value)
HRESULT __SetSamplerState (DWORD sampler, D3DSAMPLERSTATETYPE type, DWORD value)
HRESULT __SetTextureStageState (DWORD stage, D3DTEXTURESTAGESTATETYPE type, DWORD value)

Private Attributes

LPDIRECT3D9 mpD3D
LPDIRECT3DDEVICE9 mpD3DDevice
DWORD mMultiSampleQuality
HWND mExternalHandle
D3D9DriverListmDriverList
D3D9DrivermActiveD3DDriver
D3DCAPS9 mCaps
BYTE * mpRenderBuffer
DWORD mRenderBufferSize
HardwareVertexBuffer mpXYZBuffer
HardwareVertexBuffer mpNormalBuffer
HardwareVertexBuffer mpDiffuseBuffer
HardwareVertexBuffer mpSpecularBuffer
HardwareVertexBuffer mpTextures [OGRE_MAX_TEXTURE_LAYERS][4]
UINT mStreamsInUse
HardwareIndexBuffer mpIndicies
D3DVERTEXELEMENT9 mCurrentDecl [D3D_MAX_DECLSIZE]
LPDIRECT3DVERTEXDECLARATION9 mpCurrentVertexDecl
LightmLights [MAX_LIGHTS]
HINSTANCE mhInstance

Detailed Description

Implementation of DirectX9 as a rendering system.


Constructor & Destructor Documentation

Ogre::D3D9RenderSystem::D3D9RenderSystem HINSTANCE    hInstance
 

Ogre::D3D9RenderSystem::~D3D9RenderSystem  
 


Member Function Documentation

HRESULT Ogre::D3D9RenderSystem::__SetRenderState D3DRENDERSTATETYPE    state,
DWORD    value
[private]
 

HRESULT Ogre::D3D9RenderSystem::__SetSamplerState DWORD    sampler,
D3DSAMPLERSTATETYPE    type,
DWORD    value
[private]
 

HRESULT Ogre::D3D9RenderSystem::__SetTextureStageState DWORD    stage,
D3DTEXTURESTAGESTATETYPE    type,
DWORD    value
[private]
 

void Ogre::D3D9RenderSystem::_addLight Light   lt [virtual]
 

Adds a light to the renderers list of active lights.

This method should not be called directly by user processes - this is adding a light at the rendering level. User processes should add lights using the SceneNode attachLight method

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_beginFrame void    [virtual]
 

Signifies the beginning of a frame, ie the start of rendering on a single viewport.

Will occur several times per complete frame if multiple viewports exist.

Implements Ogre::RenderSystem.

void Ogre::RenderSystem::_beginGeometryCount void    [virtual, inherited]
 

The RenderSystem will keep a count of tris rendered, this resets the count.

void Ogre::RenderSystem::_disableTextureUnit int    texUnit [virtual, inherited]
 

Turns off a texture unit.

void Ogre::D3D9RenderSystem::_endFrame void    [virtual]
 

Ends rendering of a frame to the current viewport.

Implements Ogre::RenderSystem.

CullingMode Ogre::RenderSystem::_getCullingMode void    [virtual, inherited]
 

unsigned int Ogre::RenderSystem::_getFaceCount void    [virtual, inherited]
 

Reports the number of tris rendered since the last _beginGeometryCount call.

unsigned short Ogre::D3D9RenderSystem::_getNumTextureUnits void    [virtual]
 

Returns the number of texture units the current output hardware supports.

For use in rendering, this determines how many texture units the are available for multitexturing (i.e. rendering multiple textures in a single pass). Where a Material has multiple texture layers, it will try to use multitexturing where available, and where it is not available, will perform multipass rendering to achieve the same effect.

Implements Ogre::RenderSystem.

unsigned short Ogre::RenderSystem::_getNumVertexBlendMatrices void    [virtual, inherited]
 

Returns the number of matrices available to hardware vertex blending for this rendering system.

unsigned int Ogre::RenderSystem::_getVertexCount void    [virtual, inherited]
 

Reports the number of vertices passed to the renderer since the last _beginGeometryCount call.

Viewport * Ogre::RenderSystem::_getViewport void    [virtual, inherited]
 

Get the current active viewport for rendering.

bool Ogre::RenderSystem::_isVertexBlendSupported void    [virtual, inherited]
 

Returns whether or not this RenderSystem supports hardware vertex blending, ie multiple world matrices per vertex with blending weights.

void Ogre::D3D9RenderSystem::_makeProjectionMatrix Real    fovy,
Real    aspect,
Real    nearPlane,
Real    farPlane,
Matrix4   dest
[virtual]
 

Builds a perspective projection matrix suitable for this render system.

Remarks:
Because different APIs have different requirements (some incompatible) for the projection matrix, this method allows each to implement their own correctly and pass back a generic OGRE matrix for storage in the engine.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_modifyLight Light   lt [virtual]
 

Modifies a light in the renderer.

Modifies a light which has already been added using _addLight.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_popRenderState void    [virtual]
 

Restores the render state to a previous state.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_pushRenderState void    [virtual]
 

Saves the current rendering state.

Stores the current rendering state on the render state stack. The state may then be altered and restored back to it's previous state using RenderSystem::_popRenderState. Used internally by Ogre to manage changes like model/view matrices, active materials/textures without having to repecify them every time.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_removeAllLights void    [virtual]
 

Clears all the lights from the renderer.

As with RenderSystem::_addLight this method is for use internally, not by user processes. See SceneManager for user-level light maintenance.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_removeLight Light   lt [virtual]
 

Removes a light from the renderers list.

As with RenderSystem::_addLight this method is for use internally, not by user processes. See SceneNode for user-level light maintenance.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_render RenderOperation   op [virtual]
 

Render something to the active viewport.

Low-level rendering interface to perform rendering operations. Unlikely to be used directly by client applications, since the SceneManager and various support classes will be responsible for calling this method. Can only be called between _beginScene and _endScene

Parameters:
op  A rendering operation instance, which contains details of the operation to be performed.

Reimplemented from Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setAlphaRejectSettings CompareFunction    func,
unsigned char    value
[virtual]
 

Sets the global alpha rejection approach for future renders.

By default images are rendered regardless of texture alpha. This method lets you change that.

Parameters:
func  The comparison function which must pass for a pixel to be written.
val  The value to compare each pixels alpha value to (recommended 0 or 128 for compatibility)

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setCullingMode CullingMode    mode [virtual]
 

Sets the culling mode for the render system based on the 'vertex winding'.

A typical way for the rendering engine to cull triangles is based on the 'vertex winding' of triangles. Vertex winding refers to the direction in which the vertices are passed or indexed to in the rendering operation as viewed from the camera, and will wither be clockwise or anticlockwise (that's 'counterclockwise' for you Americans out there ;) The default is CULL_CLOCKWISE i.e. that only triangles whose vertices are passed/indexed in anticlockwise order are rendered - this is a common approach and is used in 3D studio models for example. You can alter this culling mode if you wish but it is not advised unless you know what you are doing. You may wish to use the CULL_NONE option for mesh data that you cull yourself where the vertex winding is uncertain.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setDepthBias ushort    bias [virtual]
 

See RenderSystem.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setDepthBufferCheckEnabled bool    enabled = true [virtual]
 

Sets whether or not the depth buffer check is performed before a pixel write.

Parameters:
enabled  If true, the depth buffer is tested for each pixel and the frame buffer is only updated if the depth function test succeeds. If false, no test is performed and pixels are always written.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setDepthBufferFunction CompareFunction    func = CMPF_LESS_EQUAL [virtual]
 

Sets the comparison function for the depth buffer check.

Advanced use only - allows you to choose the function applied to compare the depth values of new and existing pixels in the depth buffer. Only an issue if the deoth buffer check is enabled (see _setDepthBufferCheckEnabled)

Parameters:
func  The comparison between the new depth and the existing depth which must return true for the new pixel to be written.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setDepthBufferParams bool    depthTest = true,
bool    depthWrite = true,
CompareFunction    depthFunction = CMPF_LESS_EQUAL
[virtual]
 

Sets the mode of operation for depth buffer tests from this point onwards.

Sometimes you may wish to alter the behaviour of the depth buffer to achieve special effects. Because it's unlikely that you'll set these options for an entire frame, but rather use them to tweak settings between rendering objects, this is an internal method (indicated by the '_' prefix) which will be used by a SceneManager implementation rather than directly from the client application. If this method is never called the settings are automatically the same as the default parameters.

Parameters:
depthTest  If true, the depth buffer is tested for each pixel and the frame buffer is only updated if the depth function test succeeds. If false, no test is performed and pixels are always written.
depthWrite  If true, the depth buffer is updated with the depth of the new pixel if the depth test succeeds. If false, the depth buffer is left unchanged even if a new pixel is written.
depthFunction  Sets the function required for the depth test.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setDepthBufferWriteEnabled bool    enabled = true [virtual]
 

Sets whether or not the depth buffer is updated after a pixel write.

Parameters:
enabled  If true, the depth buffer is updated with the depth of the new pixel if the depth test succeeds. If false, the depth buffer is left unchanged even if a new pixel is written.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setFog FogMode    mode = FOG_NONE,
ColourValue    colour = ColourValue::White,
Real    expDensity = 1.0,
Real    linearStart = 0.0,
Real    linearEnd = 1.0
[virtual]
 

Sets the fogging mode for future geometry.

Parameters:
mode  Set up the mode of fog as described in the FogMode enum, or set to FOG_NONE to turn off.
colour  The colour of the fog. Either set this to the same as your viewport background colour, or to blend in with a skydome or skybox.
expDensity  The density of the fog in FOG_EXP or FOG_EXP2 mode, as a value between 0 and 1. The default is 1. i.e. completely opaque, lower values can mean that fog never completely obscures the scene.
linearStart  Distance at which linear fog starts to encroach. The distance must be passed as a parametric value between 0 and 1, with 0 being the near clipping plane, and 1 being the far clipping plane. Only applicable if mode is FOG_LINEAR.
linearEnd  Distance at which linear fog becomes completely opaque.The distance must be passed as a parametric value between 0 and 1, with 0 being the near clipping plane, and 1 being the far clipping plane. Only applicable if mode is FOG_LINEAR.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setMultiSampleAntiAlias BOOL    set
 

void Ogre::D3D9RenderSystem::_setProjectionMatrix const Matrix4   m [virtual]
 

Sets the projection transform matrix.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setRasterisationMode SceneDetailLevel    level [virtual]
 

Sets how to rasterise triangles, as points, wireframe or solid polys.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setSceneBlending SceneBlendFactor    sourceFactor,
SceneBlendFactor    destFactor
[virtual]
 

Sets the global blending factors for combining subsequent renders with the existing frame contents.

The result of the blending operation is:

final = (texture * sourceFactor) + (pixel * destFactor) Each of the factors is specified as one of a number of options, as specified in the SceneBlendFactor enumerated type.

Parameters:
sourceFactor  The source factor in the above calculation, i.e. multiplied by the texture colour components.
destFactor  The destination factor in the above calculation, i.e. multiplied by the pixel colour components.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setSurfaceParams const ColourValue   ambient,
const ColourValue   diffuse,
const ColourValue   specular,
const ColourValue   emissive,
Real    shininess
[virtual]
 

Sets the surface properties to be used for future rendering.

This method sets the the properties of the surfaces of objects to be rendered after it. In this context these surface properties are the amount of each type of light the object reflects (determining it's colour under different types of light), whether it emits light itself, and how shiny it is. Textures are not dealt with here, see the _setTetxure method for details. This method is used by _setMaterial so does not need to be called direct if that method is being used.

Parameters:
ambient  The amount of ambient (sourceless and directionless) light an object reflects. Affected by the colour/amount of ambient light in the scene.
diffuse  The amount of light from directed sources that is reflected (affected by colour/amount of point, directed and spot light sources)
specular  The amount of specular light reflected. This is also affected by directed light sources but represents the colour at the highlights of the object.
emissive  The colour of light emitted from the object. Note that this will make an object seem brighter and not dependent on lights in the scene, but it will not act as a light, so will not illuminate other objects. Use a light attached to the same SceneNode as the object for this purpose.
shininess  A value which only has an effect on specular highlights (so specular must be non-black). The higher this value, the smaller and crisper the specular highlights will be, imitating a more highly polished surface. This value is not constrained to 0.0-1.0, in fact it is likely to be more (10.0 gives a modest sheen to an object).

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setTexture int    unit,
bool    enabled,
const String   texname
[virtual]
 

Sets the status of a single texture stage.

Sets the details of a texture stage, to be used for all primitives rendered afterwards. User processes would not normally call this direct unless rendering primitives themselves - the SubEntity class is designed to manage materials for objects. Note that this method is called by _setMaterial.

Parameters:
unit  The index of the texture unit to modify. Multitexturing hardware can support multiple units (see _getNumTextureUnits)
enabled  Boolean to turn the unit on/off
texname  The name of the texture to use - this should have already been loaded with TextureManager::load.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setTextureAddressingMode int    stage,
Material::TextureLayer::TextureAddressingMode    tam
[virtual]
 

Sets the texture addressing mode for a texture unit.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setTextureBlendMode int    stage,
const LayerBlendModeEx   bm
[virtual]
 

Sets the texture blend modes from a TextureLayer record.

Meant for use internally only - apps should use the Material and TextureLayer classes.

Parameters:
unit  Texture unit as above
bm  Details of the blending mode

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setTextureCoordCalculation int    stage,
TexCoordCalcMethod    m
[virtual]
 

Sets a method for automatically calculating texture coordinates for a stage.

Should not be used by apps - for use by Ogre only.

Parameters:
unit  Texture unit as above
m  Calculation method to use

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setTextureCoordSet int    stage,
int    index
[virtual]
 

Sets the texture coordinate set to use for a texture unit.

Meant for use internally - not generally used directly by apps - the Material and TextureLayer classes let you manage textures far more easily.

Parameters:
unit  Texture unit as above
index  The index of the texture coordinate set to use.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setTextureMatrix int    stage,
const Matrix4   xform
[virtual]
 

Sets the texture coordinate transformation matrix for a texture unit.

Parameters:
unit  Texture unit to affect
xform  The 4x4 matrix

Implements Ogre::RenderSystem.

void Ogre::RenderSystem::_setTextureUnitSettings int    texUnit,
Material::TextureLayer   tl
[virtual, inherited]
 

Utility function for setting all the properties of a texture unit at once.

This method is also worth using over the individual texture unit settings because it only sets those settings which are different from the current settings for this unit, thus minimising render state changes.

void Ogre::D3D9RenderSystem::_setViewMatrix const Matrix4   m [virtual]
 

Sets the view transform matrix.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::_setViewport Viewport   vp [virtual]
 

Sets the provided viewport as the active one for future rendering operations.

This viewport is aware of it's own camera and render target. Must be implemented by subclass.

Parameters:
target  Pointer to the appropriate viewport.

Implements Ogre::RenderSystem.

void Ogre::RenderSystem::_setWorldMatrices const Matrix4   m,
unsigned short    count
[virtual, inherited]
 

Sets multiple world matrices (vertex blending).

void Ogre::D3D9RenderSystem::_setWorldMatrix const Matrix4   m [virtual]
 

Sets the world transform matrix.

Implements Ogre::RenderSystem.

void Ogre::RenderSystem::addFrameListener FrameListener   newListener [virtual, inherited]
 

Registers a FrameListener which will be called back every frame.

Remarks:
A FrameListener is a class which implements methods which will be called during Ogre's automatic rendering loop (started with RenderSystem::startRendering).

See the FrameListener class for more details on the specifics. It is imperitive that the instance passed to this method is not destroyed before iether the rendering loop ends, or the class is removed from the listening list using removeFrameListener.

See also:
FrameListener

void Ogre::RenderSystem::attachRenderTarget RenderTarget   target [virtual, inherited]
 

Don't do this anymore, just allow via Root RenderSystem* regPtr = Root::getSingleton().getRenderSystem(); if (!regPtr || regPtr != this) Register self - library user has come to me direct Root::getSingleton().setRenderSystem(this);.

bool Ogre::D3D9RenderSystem::compareDecls D3DVERTEXELEMENT9 *    pDecl1,
D3DVERTEXELEMENT9 *    pDecl2,
int    size
[inline, private]
 

void Ogre::D3D9RenderSystem::convertColourValue const ColourValue   colour,
unsigned long *    pDest
[virtual]
 

Generates a packed data version of the passed in ColourValue suitable for use as with this RenderSystem.

Remarks:
Since different render systems have different colour data formats (eg RGBA for GL, ARGB for D3D) this method allows you to use 1 method for all.
Parameters:
colour  The colour to convert
pDest  Pointer to location to put the result.

Implements Ogre::RenderSystem.

D3DCMPFUNC Ogre::D3D9RenderSystem::convertCompareFunction CompareFunction    func [private]
 

Matrix4 Ogre::D3D9RenderSystem::convertD3DXMatrix const D3DXMATRIX &    mat [private]
 

D3DSTENCILOP Ogre::D3D9RenderSystem::convertStencilOp StencilOperation    op [private]
 

RenderTexture * Ogre::D3D9RenderSystem::createRenderTexture const String   name,
int    width,
int    height
[virtual]
 

Creates and registers a render texture object.

Parameters:
name  The name for the new render texture. Note that names must be unique.
width  The requested width for the render texture. See Remarks for more info.
height  The requested width for the render texture. See Remarks for more info.
Returns:
On succes, a pointer to a new platform-dependernt, RenderTexture-derived class is returned. On failiure, NULL is returned.
Remarks:
Because a render texture is basically a wrapper around a texture object, the width and height parameters of this method just hint the preferred size for the texture. Depending on the hardware driver or the underlying API, these values might change when the texture is created.

Implements Ogre::RenderSystem.

RenderWindow * Ogre::D3D9RenderSystem::createRenderWindow const String   name,
int    width,
int    height,
int    colourDepth,
bool    fullScreen,
int    left = 0,
int    top = 0,
bool    depthBuffer = true,
RenderWindow   parentWindowHandle = 0
[virtual]
 

Creates a new rendering window.

Remarks:
This method creates a new rendering window as specified by the paramteters. The rendering system could be responible for only a single window (e.g. in the case of a game), or could be in charge of multiple ones (in the case of a level editor). The option to create the window as a child of another is therefore given. This method will create an appropriate subclass of RenderWindow depending on the API and platform implementation.

After creation, this window can be retrieved using getRenderTarget().

Parameters:
name  The name of the window. Used in other methods later like setRenderTarget and getRenderWindow.
width  The width of the new window.
height  The height of the new window.
colourDepth  The colour depth in bits per pixel. Only applicable if fullScreen = true
fullScreen  Specify true to make the window full screen without borders, title bar or menu bar.
left  The x position of the new window. Only applicable if fullScreen is false. Units are relative to the parent window if applicable, otherwise they are in screen coordinates.
top  The y position of the new window.
depthBuffer  If true, a depth buffer will be assigned to this window.
parentWindowHandle  Should be null if this window is to be stand-alone. Otherwise, specify a pointer to a RenderWindow which represents the parent window.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::destroyRenderWindow RenderWindow   pWin
 

RenderTarget * Ogre::RenderSystem::detachRenderTarget const String   name [virtual, inherited]
 

Detaches the render target with the passed name from the render system and returns a pointer to it.

Note:
If the render target cannot be found, NULL is returned.

bool Ogre::RenderSystem::fireFrameEnded FrameEvent   evt [protected, inherited]
 

Internal method for raising frame ended events.

bool Ogre::RenderSystem::fireFrameStarted FrameEvent   evt [protected, inherited]
 

Internal method for raising frame started events.

ConfigOptionMap & Ogre::D3D9RenderSystem::getConfigOptions void    [virtual]
 

Returns the details of this API's configuration options.

Remarks:
Each render system must be able to inform the world of what options must/can be specified for it's operation.

These are passed as strings for portability, but grouped into a structure (_ConfigOption) which includes both options and current value.

Note that the settings returned from this call are affected by the options that have been set so far, since some options are interdependent.

This routine is called automatically by the default configuration dialogue produced by Root::showConfigDialog or may be used by the caller for custom settings dialogs

Returns:
A 'map' of options, i.e. a list of options which is also indexed by option name.

Implements Ogre::RenderSystem.

D3D9DriverList * Ogre::D3D9RenderSystem::getDirect3DDrivers void    [private]
 

String Ogre::D3D9RenderSystem::getErrorDescription long    errorNumber [virtual]
 

Returns a description of an error code.

Implements Ogre::RenderSystem.

const String & Ogre::D3D9RenderSystem::getName void    const [virtual]
 

Returns the name of the rendering system.

Implements Ogre::RenderSystem.

RenderTarget * Ogre::RenderSystem::getRenderTarget const String   name [virtual, inherited]
 

Returns a pointer to the render target with the passed name, or NULL if that render target cannot be found.

ushort Ogre::D3D9RenderSystem::getStencilBufferBitDepth void    [virtual]
 

See RenderSystem.

Implements Ogre::RenderSystem.

bool Ogre::RenderSystem::getWaitForVerticalBlank void    [inherited]
 

Returns true if the system is synchronising frames with the monitor vertical blank.

bool Ogre::D3D9RenderSystem::hasHardwareStencil void    [virtual]
 

See RenderSystem.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::initConfigOptions void    [private]
 

RenderWindow * Ogre::D3D9RenderSystem::initialise bool    autoCreateWindow [virtual]
 

Start up the renderer using the settings selected (Or the defaults if none have been selected).

Remarks:
Called by Root::setRenderSystem. Shouldn't really be called directly, although this can be done if the app wants to.
Parameters:
autoCreateWindow  If true, creates a render window automatically, based on settings chosen so far. This saves an extra call to RenderSystem::createRenderWindow for the main render window.

If an application has more specific window requirements, however (e.g. a level design app), it should specify false for this parameter and do it manually.

Returns:
A pointer to the automatically created window, if requested, otherwise null.

Reimplemented from Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::initInputDevices void    [private]
 

D3DXMATRIX Ogre::D3D9RenderSystem::makeD3DXMatrix const Matrix4   mat [private]
 

void Ogre::D3D9RenderSystem::processInputDevices void    [private]
 

void Ogre::D3D9RenderSystem::refreshD3DSettings void    [private]
 

void Ogre::D3D9RenderSystem::reinitialise   [virtual]
 

Restart the renderer (normally following a change in settings).

Implements Ogre::RenderSystem.

void Ogre::RenderSystem::removeFrameListener FrameListener   oldListener [virtual, inherited]
 

Removes a FrameListener from the list of listening classes.

Ogre::D3D9RenderSystem::ResizeRepositionWindow HWND    wich [virtual]
 

void Ogre::D3D9RenderSystem::setAmbientLight float    r,
float    g,
float    b
[virtual]
 

Sets the colour & strength of the ambient (global directionless) light in the world.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::setConfigOption const String   name,
const String   value
[virtual]
 

Sets an option for this API.

Remarks:
Used to confirm the settings (normally chosen by the user) in order to make the renderer able to initialise with the settings as required. This may be video mode, D3D driver, full screen / windowed etc. Called automatically by the default configuration dialog, and by the restoration of saved settings. These settings are stored and only activated when RenderSystem::initialise or RenderSystem::reinitialise are called.

If using a custom configuration dialog, it is advised that the caller calls RenderSystem::getConfigOptions again, since some options can alter resulting from a selection.

Parameters:
name  The name of the option to alter.
value  The value to set the option to.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::setD3D9Light int    index,
Light   light
[private]
 

void Ogre::D3D9RenderSystem::SetExternalWindowHandle HWND    externalHandle [inline]
 

void Ogre::D3D9RenderSystem::setFullScreenMultiSamplingPasses DWORD    numPasses
 

void Ogre::D3D9RenderSystem::setLightingEnabled bool    enabled [virtual]
 

Sets whether or not dynamic lighting is enabled.

Parameters:
enabled  If true, dynamic lighting is performed on geometry with normals supplied, geometry without normals will not be displayed. If false, no lighting is applied and all geometry will be full brightness.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::setShadingType ShadeOptions    so [virtual]
 

Sets the type of light shading required (default = Gouraud).

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::setStencilBufferDepthFailOperation StencilOperation    op [virtual]
 

See RenderSystem.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::setStencilBufferFailOperation StencilOperation    op [virtual]
 

See RenderSystem.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::setStencilBufferFunction CompareFunction    func [virtual]
 

See RenderSystem.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::setStencilBufferMask ulong    mask [virtual]
 

See RenderSystem.

Implements Ogre::RenderSystem.

void Ogre::RenderSystem::setStencilBufferParams CompareFunction    func = CMPF_ALWAYS_PASS,
ulong    refValue = 0,
ulong    mask = 0xFFFFFFFF,
StencilOperation    stencilFailOp = SOP_KEEP,
StencilOperation    depthFailOp = SOP_KEEP,
StencilOperation    passOp = SOP_KEEP
[virtual, inherited]
 

This method allows you to set all the stencil buffer parameters in one call.

Remarks:
The stencil buffer is used to mask out pixels in the render target, allowing you to do effects like mirrors, cut-outs, stencil shadows and more. Each of your batches of rendering is likely to ignore the stencil buffer, update it with new values, or apply it to mask the output of the render. The stencil test is:
            (Reference Value & Mask) CompareFunction (Stencil Buffer Value & Mask)
The result of this will cause one of 3 actions depending on whether the test fails, succeeds but with the depth buffer check still failing, or succeeds with the depth buffer check passing too.

Unlike other render states, stencilling is left for the application to turn on and off when it requires. This is because you are likely to want to change parameters between batches of arbitrary objects and control the ordering yourself. In order to batch things this way, you'll want to use OGRE's separate render queue groups (see RenderQueue) and register a RenderQueueListener to get notifications between batches.

There are individual state change methods for each of the parameters set using this method. Note that the default values in this method represent the defaults at system start up too.

Parameters:
func  The comparison function applied.
refValue  The reference value used in the comparison
mask  The bitmask applied to both the stencil value and the reference value before comparison
stencilFailOp  The action to perform when the stencil check fails
depthFailOp  The action to perform when the stencil check passes, but the depth buffer check still fails
passOp  The action to take when both the stencil and depth check pass.

Reimplemented in Ogre::SDLRenderSystem.

void Ogre::D3D9RenderSystem::setStencilBufferPassOperation StencilOperation    op [virtual]
 

See RenderSystem.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::setStencilBufferReferenceValue ulong    refValue [virtual]
 

See RenderSystem.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::setStencilCheckEnabled bool    enabled [virtual]
 

See RenderSystem.

Implements Ogre::RenderSystem.

void Ogre::D3D9RenderSystem::setTextureFiltering TextureFilterOptions    fo [virtual]
 

Sets the type of texture filtering used when rendering.

Remarks:
This method sets the kind of texture filtering applied when rendering textures onto primitives. Filtering covers how the effects of minification and magnification are disguised by resampling.
Parameters:
fo  The type of filtering to apply. The options are described in TextureFilterOptions

Implements Ogre::RenderSystem.

void Ogre::RenderSystem::setWaitForVerticalBlank bool    enabled [inherited]
 

Defines whether or now fullscreen render windows wait for the vertical blank before flipping buffers.

Remarks:
By default, all rendering windows wait for a vertical blank (when the CRT beam turns off briefly to move from the bottom right of the screen back to the top left) before flipping the screen buffers. This ensures that the image you see on the screen is steady. However it restricts the frame rate to the refresh rate of the monitor, and can slow the frame rate down. You can speed this up by not waiting for the blank, but this has the downside of introducing 'tearing' artefacts where part of the previous frame is still displayed as the buffers are switched. Speed vs quality, you choose.
Note:
Has NO effect on windowed mode render targets. Only affects fullscreen mode.
Parameters:
enabled  If true, the system waits for vertical blanks - quality over speed. If false it doesn't - speed over quality.

void Ogre::D3D9RenderSystem::shutdown   [virtual]
 

Shutdown the renderer and cleanup resources.

Reimplemented from Ogre::RenderSystem.

void Ogre::RenderSystem::softwareVertexBlend RenderOperation   op,
Matrix4   pMatrices
[inherited]
 

Performs a software vertex blend on the passed in operation.

Remarks:
This function is supplied to calculate a vertex blend when no hardware support is available, or when the results are required by another software component. The vertices contained in the passed in operation will be modified by the matrices supplied according to the blending weights also in the operation. To avoid accidentally modifying core vertex data, a temporary vertex buffer is used for the result, which is then used in the RenderOperation instead of the original passed in vertex data.

void Ogre::D3D9RenderSystem::startRendering   [virtual]
 

Starts / restarts the automatic rendering cycle.

Remarks:
This method begins the automatic rendering of the scene. This method will NOT RETURN until the rendering cycle is halted.

During rendering, any FrameListener classes registered using addFrameListener will be called back for each frame that is to be rendered, These classes can tell OGRE to halt the rendering if required, which will cause this method to return.

Note - users of the OGRE library do not have to use this automatic rendering loop. It is there as a convenience and is most useful for high frame rate applications e.g. games. For applications that don't need to constantly refresh the rendering targets (e.g. an editor utility), it is better to manually refresh each render target only when required by calling RenderTarget::update.

This frees up the CPU to do other things in between refreshes, since in this case frame rate is less important.

Reimplemented from Ogre::RenderSystem.

String Ogre::D3D9RenderSystem::validateConfigOptions void    [virtual]
 

Validates the options set for the rendering system, returning a message if there are problems.

Note:
If the returned string is empty, there are no problems.

Implements Ogre::RenderSystem.


Member Data Documentation

D3D9Driver* Ogre::D3D9RenderSystem::mActiveD3DDriver [private]
 

RenderTarget* Ogre::RenderSystem::mActiveRenderTarget [protected, inherited]
 

The Active render target.

Viewport* Ogre::RenderSystem::mActiveViewport [protected, inherited]
 

D3DCAPS9 Ogre::D3D9RenderSystem::mCaps [private]
 

CullingMode Ogre::RenderSystem::mCullingMode [protected, inherited]
 

D3DVERTEXELEMENT9 Ogre::D3D9RenderSystem::mCurrentDecl[D3D_MAX_DECLSIZE] [private]
 

D3D9DriverList* Ogre::D3D9RenderSystem::mDriverList [private]
 

HWND Ogre::D3D9RenderSystem::mExternalHandle [private]
 

unsigned int Ogre::RenderSystem::mFaceCount [protected, inherited]
 

std::set<FrameListener*> Ogre::RenderSystem::mFrameListeners [protected, inherited]
 

Set of registered frame listeners.

HINSTANCE Ogre::D3D9RenderSystem::mhInstance [private]
 

Light* Ogre::D3D9RenderSystem::mLights[MAX_LIGHTS] [private]
 

DWORD Ogre::D3D9RenderSystem::mMultiSampleQuality [private]
 

ConfigOptionMap Ogre::RenderSystem::mOptions [protected, inherited]
 

LPDIRECT3DVERTEXDECLARATION9 Ogre::D3D9RenderSystem::mpCurrentVertexDecl [private]
 

LPDIRECT3D9 Ogre::D3D9RenderSystem::mpD3D [private]
 

LPDIRECT3DDEVICE9 Ogre::D3D9RenderSystem::mpD3DDevice [private]
 

HardwareVertexBuffer Ogre::D3D9RenderSystem::mpDiffuseBuffer [private]
 

HardwareIndexBuffer Ogre::D3D9RenderSystem::mpIndicies [private]
 

HardwareVertexBuffer Ogre::D3D9RenderSystem::mpNormalBuffer [private]
 

BYTE* Ogre::D3D9RenderSystem::mpRenderBuffer [private]
 

RenderTargetPriorityMap Ogre::RenderSystem::mPrioritisedRenderTargets [protected, inherited]
 

The render targets, ordered by priority.

HardwareVertexBuffer Ogre::D3D9RenderSystem::mpSpecularBuffer [private]
 

HardwareVertexBuffer Ogre::D3D9RenderSystem::mpTextures[OGRE_MAX_TEXTURE_LAYERS][4] [private]
 

HardwareVertexBuffer Ogre::D3D9RenderSystem::mpXYZBuffer [private]
 

DWORD Ogre::D3D9RenderSystem::mRenderBufferSize [private]
 

RenderTargetMap Ogre::RenderSystem::mRenderTargets [protected, inherited]
 

The render targets.

UINT Ogre::D3D9RenderSystem::mStreamsInUse [private]
 

std::vector<Real> Ogre::RenderSystem::mTempNormalBlendBuffer [protected, inherited]
 

std::vector<Real> Ogre::RenderSystem::mTempVertexBlendBuffer [protected, inherited]
 

Temporary buffer for vertex blending in software.

TextureManager* Ogre::RenderSystem::mTextureManager [protected, inherited]
 

Material::TextureLayer Ogre::RenderSystem::mTextureUnits[OGRE_MAX_TEXTURE_LAYERS] [protected, inherited]
 

unsigned int Ogre::RenderSystem::mVertexCount [protected, inherited]
 

bool Ogre::RenderSystem::mVSync [protected, inherited]
 

Matrix4 Ogre::RenderSystem::mWorldMatrices[256] [protected, inherited]
 

Saved set of world matrices.

Copyright © 2002 by The OGRE Team