IVirtualDevice Class Reference
 
 
 
IVirtualDevice Class Reference

This reference page is linked to from the following overview topics: Nitrous Graphics SDK Extensions, Low-level Device API.


#include <IVirtualDevice.h>

Inheritance diagram for IVirtualDevice:
MaxHeapOperators

Class Description

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 ()

Constructor & Destructor Documentation

virtual ~IVirtualDevice ( ) [inline, protected, virtual]
{}

Member Function Documentation

virtual unsigned int ThreadID ( ) [pure virtual]

Return the thread id of the virtual device.

Returns:
Return 0 for DirectX9, the real thread id for DirectX11
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.

Returns:
true if the device is valid. false if not.
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]

Ends frame draws.

Should pare with BeginFrame()

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]

Gets the current rasterizer state.

Returns:
the rasterizer state handle
virtual void SetRasterizerState ( const RasterizerState newState ) [pure virtual]

Sets the current rasterizer state.

Parameters:
[in] new rasterizer state
virtual const DepthStencilState& GetDepthStencilState ( ) [pure virtual]

Gets the current depth-stencil state.

Returns:
the depth stencil state handle
virtual void SetDepthStencilState ( const DepthStencilState newState ) [pure virtual]

Sets the current depth stencil state.

Parameters:
[in] new depth stencil state handle
virtual const BlendState& GetBlendState ( ) [pure virtual]

Gets the current blend state.

Returns:
current blend state handle
virtual void SetBlendState ( const BlendState newState ) [pure virtual]

Sets the current depth stencil state.

Parameters:
[in] newState new blend state handle
virtual const Box2 Viewport ( ) [pure virtual]

Gets the pixel coordinate viewport for the drawing.

Returns:
viewport's {0,0,w,h}, or {0,0,0,0} if no target defined.
virtual void Viewport ( const Box2 vp ) [pure virtual]

Sets the pixel coordinate viewport for the drawing.

Parameters:
[in] vp the desired viewport size, or nullptr which means "use the full screen"
virtual const Point2 DepthRange ( ) const [pure virtual]

Gets the depth range.

Returns:
the depth range, normally 0.0 to 1.0.
virtual void DepthRange ( const Point2 depthRange ) [pure virtual]

Sets the depth range.

Parameters:
[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.

Returns:
the scissor box. Default value is current render target size.
virtual void ScissorBox ( const Box2 box ) [pure virtual]

Sets scissor box in pixels.

Parameters:
[in] box the scissor box, nullptr means no scissor clip.
virtual size_t VertexStreamCount ( ) const [pure virtual]

Gets the current vertex buffer stream.

Returns:
current number of active streams
virtual VertexBufferHandle GetVertexStream ( int  nStream ) const [pure virtual]

Gets the current vertex buffer.

Parameters:
[in] nStream stream index of the vertex buffer
Returns:
vertex buffer handle at nStream
virtual void SetVertexStreams ( VertexBufferHandleArray bufferArray ) [pure virtual]

Sets vertex buffer streams.

Parameters:
[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.

Returns:
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.

Parameters:
[in] nStream index of the stream
Returns:
vertex buffer handle at output nStream. For dx9 device(feature level < LEVEL_4_0, an invalid handle will be returned. (Use VertexBufferHandle::IsValid() to check the validity)
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.

Parameters:
[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.

Parameters:
[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.

Parameters:
[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.

Parameters:
[in] index index of the target. For DX9, maximum number of the index is 4, for DX11, it's 8.
Returns:
the target handle. The handle might be invalid if corresponding index doesn't exist.
virtual size_t TargetCount ( ) [pure virtual]

Gets current render target count.

Returns:
current target count
virtual TargetHandle GetZBuffer ( ) [pure virtual]

Gets current z buffer.

Returns:
current z buffer. The handle might be invalid if z buffer doesn't exist.
virtual IndexBufferHandle GetIndexBuffer ( ) const [pure virtual]

Gets the current index buffer.

Returns:
current index buffer handle
virtual void SetIndexBuffer ( IndexBufferHandle indexBuffer ) [pure virtual]

Sets the current index buffer.

Parameters:
[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.

Parameters:
[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.

Parameters:
[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.

Parameters:
[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.

Parameters:
[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.