Share via

StateBlock.Capture() Method (Microsoft.DirectX.Direct3D)

  • Article

How Do I...?

  • Record and Apply StateBlocks

Captures a device's current state.

Definition

Visual Basic Public Sub Capture()
C# public void Capture();
C++ public:
void Capture();
JScript public function Capture();

Remarks

Exceptions

InvalidCallException

The method call is invalid. For example, a method's parameter might contain an invalid value.

How Do I...?

Record and Apply StateBlocks

This example demonstrates how to use state blocks to set and retrieve a device's state.

A StateBlock instance can be used to return a device to a default state. It also can be stored as a member of a class to quickly restore a desired rendering state for that class. A StateBlock is most useful when used to save default device state once a device is created. This allows for rapid restoration of default state when needed during rendering.

To record and apply a state block:

  1. Call Device.BeginStateBlock to begin recording device state.
  2. Tell the device the states and values to record.
  3. Call Device.EndStateBlock to stop recording device state and return a StateBlock instance containing the recorded states.
  4. Capture the device's current state by calling StateBlock.Capture using the previously obtained StateBlock instance.
  5. Do some processing that changes device state.
  6. Restore the device's saved states by calling StateBlock.Apply.

In the following C# code example, device is assumed to be the rendering Device.

              [C#]
              
// begin recording device state
device.BeginStateBlock();

// tell device the states and values to record
device.RenderState.FogStart = 0.3f;
device.RenderState.FogEnd = 100.0f;
device.RenderState.FogColor = Color.Gray;

// stop recording device state
StateBlock sb = device.EndStateBlock();

// save device states recorded above
sb.Capture;

// change device states
device.RenderState.FogStart = 2000.0f;
device.RenderState.FogEnd = 35000.0f;
device.RenderState.FogColor = Color.Yellow;

// render scene w/changed states
device.DrawPrimitives();

// restore device's saved states
sb.Apply();

// render scene w/saved states
device.DrawPrimitives();