This reference page is linked to from the following overview topics: Nitrous Graphics SDK Extensions, Low-level Device API.
#include <IVirtualDevice.h>
This class provides low level access of GPU device.
It wraps variable 3D API into an unified interface. So no matter Direct3D9, Direct3D11 or OpenGL the real device is, most of the time developers don't need to aware of this information. Similar as device interface in Direct3D, this interface provides rendering functions such as Draw/DrawInstanced, apply resource functions like SetVertexStreams, SetIndexBuffer etc. You can also change render states via Get/SetBlendState, Get/SetRasterizerState, Get/SetDepthStencilState. For example, to change Z-Bias of next draw call, use RasterizerState::SetDepthBias or RasterizerState::SetSlopeScaledDepthBias.
Typical usage of rendering geometry data may looks like this:
IVirtualDevice& vd = drawContext.GetVirtualDevice(); vd.SetStreamFormat(material.GetStreamFormat()); vd.SetVertexStreams(vertexBuffers); vd.SetIndexBuffer(&vertexIndex); material.Activate(drawContext); material.ActivatePass(drawContext, 0); //Assuming the effect only has 1 pass vd.Draw(PrimitiveTriangleList, 0, primitiveCount); streamOutEffect.PassesFinished(drawContext); material.Terminate(drawContext);
Typical usage of stream-out data may looks like this:
//Turn off Z-Buffer vd.SetDepthStencilState(mDepthOffState); streamOutEffect.Activate(drawContext); streamOutEffect.ActivatePass(drawContext, 0); vd.SetStreamFormat(streamOutEffect.GetStreamFormat()); vd.SetIndexBuffer(nullptr); vd.SetVertexStreams(mRawDataBuffers); vd.SetOutputStreams(&mStreamOutBuffers); vd.Draw(PrimitivePointList, 0, (int)vertexCount); vd.SetOutputStreams(nullptr); streamOutEffect.PassesFinished(drawContext); streamOutEffect.Terminate(); //Restore Z-Buffer state vd.SetDepthStencilState(mBackupState);
Public Member Functions |
|
virtual unsigned int | ThreadID ()=0 |
Return the thread id of the virtual device.
|
|
virtual bool | IsValid () const =0 |
Gets the status of the device. |
|
virtual bool | BeginFrame ()=0 |
Begins the frame draws. |
|
virtual bool | EndFrame ()=0 |
Ends frame draws. |
|
virtual bool | BeginScene ()=0 |
Begins the scene draws brackets sets of
drawing calls. |
|
virtual bool | EndScene ()=0 |
Ends scene draws. |
|
virtual const RasterizerState & | GetRasterizerState ()=0 |
Gets the current rasterizer state. |
|
virtual void | SetRasterizerState (const RasterizerState &newState)=0 |
Sets the current rasterizer state. |
|
virtual const DepthStencilState & | GetDepthStencilState ()=0 |
Gets the current depth-stencil state.
|
|
virtual void | SetDepthStencilState (const DepthStencilState &newState)=0 |
Sets the current depth stencil state.
|
|
virtual const BlendState & | GetBlendState ()=0 |
Gets the current blend state. |
|
virtual void | SetBlendState (const BlendState &newState)=0 |
Sets the current depth stencil state.
|
|
virtual const Box2 | Viewport ()=0 |
Gets the pixel coordinate viewport for the
drawing. |
|
virtual void | Viewport (const Box2 *vp)=0 |
Sets the pixel coordinate viewport for the
drawing. |
|
virtual const Point2 | DepthRange () const =0 |
Gets the depth range. |
|
virtual void | DepthRange (const Point2 &depthRange)=0 |
Sets the depth range. |
|
virtual const Box2 | ScissorBox ()=0 |
Gets scissor box in pixels. |
|
virtual void | ScissorBox (const Box2 *box)=0 |
Sets scissor box in pixels. |
|
virtual size_t | VertexStreamCount () const =0 |
Gets the current vertex buffer stream.
|
|
virtual VertexBufferHandle | GetVertexStream (int nStream) const =0 |
Gets the current vertex buffer. |
|
virtual void | SetVertexStreams (VertexBufferHandleArray &bufferArray)=0 |
Sets vertex buffer streams. |
|
virtual void | SetStreamFormat (MaxSDK::Graphics::MaterialRequiredStreams &format)=0 |
virtual size_t | OutputStreamCount () const =0 |
Gets the number of current output vertex
buffer stream. |
|
virtual VertexBufferHandle | GetOutputStream (int nStream) const =0 |
Gets the current output vertex buffer.
|
|
virtual void | SetOutputStreams (VertexBufferHandleArray *bufferArray)=0 |
Sets the current output vertex buffer stream
Note: the max number of output stream is 0 for DX9, 4 for DX11
device. |
|
virtual void | SetTarget (TargetHandle *target, TargetHandle *zBuffer)=0 |
Set render target at index 0. |
|
virtual void | SetTargets (TargetHandleArray &targetArray, TargetHandle *zBuffer)=0 |
Set multiple render targets. |
|
virtual TargetHandle | GetTarget (int index)=0 |
Gets current render target. |
|
virtual size_t | TargetCount ()=0 |
Gets current render target count. |
|
virtual TargetHandle | GetZBuffer ()=0 |
Gets current z buffer. |
|
virtual IndexBufferHandle | GetIndexBuffer () const =0 |
Gets the current index buffer. |
|
virtual void | SetIndexBuffer (IndexBufferHandle *indexBuffer)=0 |
Sets the current index buffer. |
|
virtual void | Draw (PrimitiveType type, int start, int primCount)=0 |
Draws part of a set of primitives. |
|
virtual void | DrawInstanced (PrimitiveType type, int instanceCount, int start, int primCount)=0 |
Draws part of a set of primitives with
instance Note: you need call VertexBufferHandle::SetInstanceCount()
to set instance count of the instance data stream. |
|
virtual void | Clear (BufferClearFlag flags, const AColor &color, float z, int stencil)=0 |
Full clear: target( nTargets ) to given
color, z to given z, stencil to given stencil. |
|
virtual void | ClearRegion (const Box2 &rect, BufferClearFlag flags, const AColor &color, float z, int stencil)=0 |
Partial clear: sub-region of
target/z/stencil is cleared. |
|
Protected Member Functions |
|
virtual | ~IVirtualDevice () |
virtual ~IVirtualDevice | ( | ) | [inline, protected, virtual] |
{}
virtual unsigned int ThreadID | ( | ) | [pure virtual] |
Return the thread id of the virtual device.
virtual bool IsValid | ( | ) | const [pure virtual] |
Gets the status of the device.
Note: When IsValid is false, all device related resource may invalid. Some times plugins may dispose after Nitrous. At this time, any calls of device resources may cause crash. So plugins should check this flag to make sure the device is valid before releasing the resources.
virtual bool BeginFrame | ( | ) | [pure virtual] |
Begins the frame draws.
Should pair with EndFrame() brackets sets of drawing calls, only 1 level deep allowed.
virtual bool EndFrame | ( | ) | [pure virtual] |
virtual bool BeginScene | ( | ) | [pure virtual] |
Begins the scene draws brackets sets of drawing calls.
Only 1 level deep allowed.
virtual bool EndScene | ( | ) | [pure virtual] |
Ends scene draws.
virtual const RasterizerState& GetRasterizerState | ( | ) | [pure virtual] |
virtual void SetRasterizerState | ( | const RasterizerState & | newState | ) | [pure virtual] |
virtual const DepthStencilState& GetDepthStencilState | ( | ) | [pure virtual] |
Gets the current depth-stencil state.
virtual void SetDepthStencilState | ( | const DepthStencilState & | newState | ) | [pure virtual] |
Sets the current depth stencil state.
[in] | new | depth stencil state handle |
virtual const BlendState& GetBlendState | ( | ) | [pure virtual] |
virtual void SetBlendState | ( | const BlendState & | newState | ) | [pure virtual] |
Sets the current depth stencil state.
[in] | newState | new blend state handle |
virtual const Box2 Viewport | ( | ) | [pure virtual] |
Gets the pixel coordinate viewport for the drawing.
virtual void Viewport | ( | const Box2 * | vp | ) | [pure virtual] |
Sets the pixel coordinate viewport for the drawing.
[in] | vp | the desired viewport size, or nullptr which means "use the full screen" |
virtual const Point2 DepthRange | ( | ) | const [pure virtual] |
virtual void DepthRange | ( | const Point2 & | depthRange | ) | [pure virtual] |
Sets the depth range.
[in] | depthRange | the depth range, depthRange.x means near distance, depthRange.y means far distance. Normally the values are in 0.0 to 1.0. |
virtual const Box2 ScissorBox | ( | ) | [pure virtual] |
Gets scissor box in pixels.
virtual void ScissorBox | ( | const Box2 * | box | ) | [pure virtual] |
Sets scissor box in pixels.
[in] | box | the scissor box, nullptr means no scissor clip. |
virtual size_t VertexStreamCount | ( | ) | const [pure virtual] |
Gets the current vertex buffer stream.
virtual VertexBufferHandle GetVertexStream | ( | int | nStream | ) | const [pure virtual] |
Gets the current vertex buffer.
[in] | nStream | stream index of the vertex buffer |
virtual void SetVertexStreams | ( | VertexBufferHandleArray & | bufferArray | ) | [pure virtual] |
Sets vertex buffer streams.
[in] | bufferArray | the vertex buffer array |
virtual void SetStreamFormat | ( | MaxSDK::Graphics::MaterialRequiredStreams & | format | ) | [pure virtual] |
virtual size_t OutputStreamCount | ( | ) | const [pure virtual] |
Gets the number of current output vertex buffer stream.
virtual VertexBufferHandle GetOutputStream | ( | int | nStream | ) | const [pure virtual] |
Gets the current output vertex buffer.
Note: this function only works for DX11 device.
[in] | nStream | index of the stream |
virtual void SetOutputStreams | ( | VertexBufferHandleArray * | bufferArray | ) | [pure virtual] |
Sets the current output vertex buffer stream Note: the max number of output stream is 0 for DX9, 4 for DX11 device.
[in] | bufferArray | sets output streams. nullptr to clear output streams. |
virtual void SetTarget | ( | TargetHandle * | target, |
TargetHandle * | zBuffer | ||
) | [pure virtual] |
Set render target at index 0.
[in] | target | the pointer of render target handle. |
[in] | zBuffer | the pointer of z buffer handle. The size of zBuffer must equal or larger than target. Can be nullptr. |
virtual void SetTargets | ( | TargetHandleArray & | targetArray, |
TargetHandle * | zBuffer | ||
) | [pure virtual] |
Set multiple render targets.
[in] | targetArray | render targets to be set. All targets must have same size. |
[in] | zBuffer | the pointer of z buffer handle. The size of zBuffer must equal or larger than render targets. Can be nullptr. |
virtual TargetHandle GetTarget | ( | int | index | ) | [pure virtual] |
Gets current render target.
[in] | index | index of the target. For DX9, maximum number of the index is 4, for DX11, it's 8. |
virtual size_t TargetCount | ( | ) | [pure virtual] |
virtual TargetHandle GetZBuffer | ( | ) | [pure virtual] |
Gets current z buffer.
virtual IndexBufferHandle GetIndexBuffer | ( | ) | const [pure virtual] |
virtual void SetIndexBuffer | ( | IndexBufferHandle * | indexBuffer | ) | [pure virtual] |
Sets the current index buffer.
[in] | indexBuffer | index buffer handle. Passing nullptr to clear current index buffer. |
virtual void Draw | ( | PrimitiveType | type, |
int | start, | ||
int | primCount | ||
) | [pure virtual] |
Draws part of a set of primitives.
[in] | type | primitive type |
[in] | start | start vertex index in current vertex buffer |
[in] | primCount | number of primitives to draw. |
virtual void DrawInstanced | ( | PrimitiveType | type, |
int | instanceCount, | ||
int | start, | ||
int | primCount | ||
) | [pure virtual] |
Draws part of a set of primitives with instance Note: you need call VertexBufferHandle::SetInstanceCount() to set instance count of the instance data stream.
[in] | type | primitive type |
[in] | instanceCount | number of instance |
[in] | start | start vertex index in current vertex buffer |
[in] | primCount | number of primitives to draw. |
virtual void Clear | ( | BufferClearFlag | flags, |
const AColor & | color, | ||
float | z, | ||
int | stencil | ||
) | [pure virtual] |
Full clear: target( nTargets ) to given color, z to given z, stencil to given stencil.
The target (or MRT targets), instead of the viewport, is cleared. The Clear operation is not affected by the scissor box.
[in] | flags | component to clear. |
[in] | color | color after clear. Available when ClearBackbuffer or ClearAll is set. |
[in] | z | z value after clear. Available when ClearDepthBuffer or ClearAll is set. |
[in] | stencil | stencil value after clear. Available when ClearStencilBuffer or ClearAll is set. |
virtual void ClearRegion | ( | const Box2 & | rect, |
BufferClearFlag | flags, | ||
const AColor & | color, | ||
float | z, | ||
int | stencil | ||
) | [pure virtual] |
Partial clear: sub-region of target/z/stencil is cleared.
The region is clipped to the bounds of the viewport rectangle, and the Clear operation is not affected by the scissor box.
[in] | rect | region to clear |
[in] | flags | component to clear. |
[in] | color | color after clear. Available when ClearBackbuffer or ClearAll is set. |
[in] | z,z | value after clear. Available when ClearDepthBuffer or ClearAll is set. |
[in] | stencil | stencil value after clear. Available when ClearStencilBuffer or ClearAll is set. |