D3DRENDERSTATETYPE

Article
06/30/2006

This enumeration defines device render states.

typedef enum _D3DRENDERSTATETYPE {
  D3DRS_ZENABLE = 7,
  D3DRS_FILLMODE = 8,
  D3DRS_SHADEMODE = 9,
  D3DRS_LINEPATTERN = 10,
  D3DRS_ZWRITEENABLE = 14,
  D3DRS_ALPHATESTENABLE = 15,
  D3DRS_LASTPIXEL = 16,
  D3DRS_SRCBLEND = 19,
  D3DRS_DESTBLEND = 20,
  D3DRS_CULLMODE = 22,
  D3DRS_ZFUNC = 23,
  D3DRS_ALPHAREF = 24,
  D3DRS_ALPHAFUNC = 25,
  D3DRS_DITHERENABLE = 26,
  D3DRS_ALPHABLENDENABLE = 27,
  D3DRS_FOGENABLE = 28,
  D3DRS_SPECULARENABLE = 29,
  D3DRS_ZVISIBLE = 30,
  D3DRS_FOGCOLOR = 34,
  D3DRS_FOGTABLEMODE = 35,
  D3DRS_FOGSTART = 36,
  D3DRS_FOGEND = 37,
  D3DRS_FOGDENSITY = 38,
  D3DRS_EDGEANTIALIAS = 40,
  D3DRS_ZBIAS = 47,
  D3DRS_RANGEFOGENABLE = 48,
  D3DRS_STENCILENABLE = 52,
  D3DRS_STENCILFAIL = 53,
  D3DRS_STENCILZFAIL = 54,
  D3DRS_STENCILPASS = 55,
  D3DRS_STENCILFUNC = 56,
  D3DRS_STENCILREF = 57,
  D3DRS_STENCILMASK = 58,
  D3DRS_STENCILWRITEMASK = 59,
  D3DRS_TEXTUREFACTOR = 60,
  D3DRS_WRAP0 = 128,
  D3DRS_WRAP1 = 129,
  D3DRS_WRAP2 = 130,
  D3DRS_WRAP3 = 131,
  D3DRS_WRAP4 = 132,
  D3DRS_WRAP5 = 133,
  D3DRS_WRAP6 = 134,
  D3DRS_WRAP7 = 135,
  D3DRS_CLIPPING = 136,
  D3DRS_LIGHTING = 137,
  D3DRS_AMBIENT = 139,
  D3DRS_FOGVERTEXMODE = 140,
  D3DRS_COLORVERTEX = 141,
  D3DRS_LOCALVIEWER = 142,
  D3DRS_NORMALIZENORMALS = 143,
  D3DRS_DIFFUSEMATERIALSOURCE = 145,
  D3DRS_SPECULARMATERIALSOURCE = 146,
  D3DRS_AMBIENTMATERIALSOURCE = 147,
  D3DRS_EMISSIVEMATERIALSOURCE = 148,
  D3DRS_VERTEXBLEND = 151,
  D3DRS_CLIPPLANEENABLE = 152,
  D3DRS_SOFTWAREVERTEXPROCESSING = 153,
  D3DRS_POINTSIZE = 154,
  D3DRS_POINTSIZE_MIN = 155,
  D3DRS_POINTSPRITEENABLE = 156,
  D3DRS_POINTSCALEENABLE = 157,
  D3DRS_POINTSCALE_A = 158,
  D3DRS_POINTSCALE_B = 159,
  D3DRS_POINTSCALE_C = 160,
  D3DRS_MULTISAMPLEANTIALIAS = 161,
  D3DRS_MULTISAMPLEMASK = 162,
  D3DRS_PATCHEDGESTYLE = 163,
  D3DRS_PATCHSEGMENTS = 164,
  D3DRS_DEBUGMONITORTOKEN = 165,
  D3DRS_POINTSIZE_MAX = 166,
  D3DRS_INDEXEDVERTEXBLENDENABLE = 167,
  D3DRS_COLORWRITEENABLE = 168,
  D3DRS_TWEENFACTOR = 170,
  D3DRS_BLENDOP = 171,
  D3DRS_FORCE_DWORD = 0x7fffffff
} D3DRENDERSTATETYPE;

Constants

D3DRS_ZENABLE
Depth-buffering state as one member of the D3DZBUFFERTYPE enumerated type. Set this state to D3DZB_TRUE to enable z-buffering, D3DZB_USEW to enable w-buffering, or D3DZB_FALSE to disable depth buffering.

The default value for this render state is D3DZB_TRUE if a depth stencil was created along with the swap chain by setting the EnableAutoDepthStencil member of the D3DPRESENT_PARAMETERS structure to TRUE, and D3DZB_FALSE otherwise.
D3DRS_FILLMODE
One or more members of the D3DFILLMODE enumerated type. The default value is D3DFILL_SOLID.
D3DRS_SHADEMODE
One or more members of the D3DSHADEMODE enumerated type. The default value is D3DSHADE_GOURAUD.
D3DRS_LINEPATTERN
D3DLINEPATTERN structure. The default values are 0 for wRepeatPattern, and 0 for wLinePattern.
D3DRS_ZWRITEENABLE
TRUE to enable the application to write to the depth buffer. The default value is TRUE. This member enables an application to prevent the system from updating the depth buffer with new depth values. If FALSE, depth comparisons are still made according to the render state D3DRS_ZFUNC, assuming that depth buffering is taking place, but depth values are not written to the buffer.
D3DRS_ALPHATESTENABLE
TRUE to enable alpha tests. The default value is FALSE. This member enables applications to turn off the tests that accept or reject a pixel, based on its alpha value.

The incoming alpha value is compared with the reference alpha value, using the comparison function provided by the D3DRS_ALPHAFUNC render state. When this mode is enabled, alpha blending occurs only if the test succeeds.
D3DRS_LASTPIXEL
FALSE to enable drawing the last pixel in a line or triangle. The default value is TRUE.
D3DRS_SRCBLEND
One member of the D3DBLEND enumerated type. The default value is D3DBLEND_ONE.
D3DRS_DESTBLEND
One member of the D3DBLEND enumerated type. The default value is D3DBLEND_ZERO.
D3DRS_CULLMODE
Specifies how back-facing triangles are culled, if at all. This can be set to one member of the D3DCULL enumerated type. The default value is D3DCULL_CCW.
D3DRS_ZFUNC
One member of the D3DCMPFUNC enumerated type. The default value is D3DCMP_LESSEQUAL. This member enables an application to accept or reject a pixel, based on its distance from the camera.

The depth value of the pixel is compared with the depth-buffer value. If the depth value of the pixel passes the comparison function, the pixel is written.

The depth value is written to the depth buffer only if the render state is TRUE.

Software rasterizers and many hardware accelerators work faster if the depth test fails, because there is no need to filter and modulate the texture if the pixel is not going to be rendered.
D3DRS_ALPHAREF
Value that specifies a reference alpha value against which pixels are tested when alpha-testing is enabled. This is an 8-bit value placed in the low 8 bits of the DWORD render-state value. Values can range from 0x00000000 through 0x000000FF.
D3DRS_ALPHAFUNC
One member of the D3DCMPFUNC enumerated type. The default value is D3DCMP_ALWAYS. This member enables an application to accept or reject a pixel, based on its alpha value.
D3DRS_DITHERENABLE
TRUE to enable dithering. The default value is FALSE.
D3DRS_ALPHABLENDENABLE
TRUE to enable alpha-blended transparency. The default value is FALSE.

The type of alpha blending is determined by the D3DRS_SRCBLEND and D3DRS_DESTBLEND render states.
D3DRS_FOGENABLE
TRUE to enable fog blending. The default value is FALSE. For more information on using fog blending, see Fog.
D3DRS_SPECULARENABLE
TRUE to enable specular highlights. The default value is FALSE.

Specular highlights are calculated as though every vertex in the object being lit were at the object's origin. This gives the expected results as long as the object is modeled around the origin and the distance from the light to the object is relatively large. In other cases the results as undefined.

When this member is set to TRUE, the specular color is added to the base color after the texture cascade but before alpha blending.
D3DRS_ZVISIBLE
Not supported.
D3DRS_FOGCOLOR
Value whose type is D3DCOLOR. The default value is 0. For more information on fog color, see Fog Color.
D3DRS_FOGTABLEMODE
The fog formula to be used for pixel fog. Set to one of the members of the D3DFOGMODE enumerated type. The default value is D3DFOG_NONE. For more information on pixel fog, see Pixel Fog.
D3DRS_FOGSTART
Depth at which pixel or vertex fog effects begin for linear fog mode. Depth is specified in world space for vertex fog, and either device space [0.0, 1.0] or world space for pixel fog. For pixel fog, these values are in device space when the system uses z for fog calculations, and world-space when the system is using eye-relative fog (w-fog). For more information, see Fog Parameters and Eye-Relative vs. Z-based Depth.

Values for this render state are floating-point values. Because the IDirect3DDevice8::SetRenderState method accepts DWORD values, your application must cast a variable that contains the value, as shown in the following code example.
```
pd3dDevice8->SetRenderState(D3DRS_FOGSTART, *((DWORD*) (&fFogStart)));
```
D3DRS_FOGEND
Depth at which pixel or vertex fog effects end for linear fog mode. Depth is specified in world space for vertex fog, and either device space [0.0, 1.0] or world space for pixel fog. For pixel fog, these values are in device space when the system uses z for fog calculations, and world-space when the system is using eye-relative fog (w-fog). For more information, see Fog Parameters and Eye-Relative vs. Z-based Depth.

Values for this render state are floating-point values. Because the IDirect3DDevice8::SetRenderState method accepts DWORD values, your application must cast a variable that contains the value, as shown in the following code example.
```
pd3dDevice8->SetRenderState(D3DRS_FOGEND, *((DWORD*) (&fFogEnd)));
```
D3DRS_FOGDENSITY
Not supported.
D3DRS_EDGEANTIALIAS
Not supported in Windows CE.
D3DRS_ZBIAS
Integer value in the range 0 through 16 that causes polygons that are physically coplanar to appear separate. Polygons with a high z-bias value appear in front of polygons with a low value, without requiring sorting for drawing order. Polygons with a value of 1 appear in front of polygons with a value of 0, and so on. The default value is 0. For more information, see Using Depth Buffers.
D3DRS_RANGEFOGENABLE
TRUE to enable range-based vertex fog. The default value is FALSE, in which case the system uses depth-based fog. In range-based fog, the distance of an object from the viewer is used to compute fog effects, not the depth of the object (that is, the z-coordinate) in the scene. In range-based fog, all fog methods work as usual, except that they use range instead of depth in the computations.

Range is the correct factor to use for fog computations, but depth is commonly used instead because range is expensive to compute and depth is generally already available. Using depth to calculate fog has the undesirable effect of having the fogginess of peripheral objects change as the viewer's eye moves — in this case, the depth changes, and the range remains constant.

Because no hardware currently supports per-pixel range-based fog, range correction is offered only for vertex fog.

For more information, see Range-Based Fog and Vertex Fog.
D3DRS_STENCILENABLE
TRUE to enable stenciling, or FALSE to disable stenciling. The default value is FALSE. For more information, see Stencil Buffers.
D3DRS_STENCILFAIL
Stencil operation to perform if the stencil test fails. This can be one member of the D3DSTENCILOP enumerated type. The default value is D3DSTENCILOP_KEEP. For more information, see Stencil Buffers.
D3DRS_STENCILZFAIL
Stencil operation to perform if the stencil test passes and the depth test (z-test) fails. This can be one of the members of the D3DSTENCILOP enumerated type. The default value is D3DSTENCILOP_KEEP.
D3DRS_STENCILPASS
Stencil operation to perform if both the stencil and the depth (z) tests pass. This can be one member of the D3DSTENCILOP enumerated type. The default value is D3DSTENCILOP_KEEP.
D3DRS_STENCILFUNC
Comparison function for the stencil test. This can be one member of the D3DCMPFUNC enumerated type. The default value is D3DCMP_ALWAYS.

The comparison function is used to compare the reference value to a stencil buffer entry. This comparison applies only to the bits in the reference value and stencil buffer entry that are set in the stencil mask (set by the D3DRS_STENCILMASK render state). If TRUE, the stencil test passes.
D3DRS_STENCILREF
Integer reference value for the stencil test. The default value is 0.
D3DRS_STENCILMASK
Mask applied to the reference value and each stencil buffer entry to determine the significant bits for the stencil test. The default mask is 0xFFFFFFFF.
D3DRS_STENCILWRITEMASK
Write mask applied to values written into the stencil buffer. The default mask is 0xFFFFFFFF.
D3DRS_TEXTUREFACTOR
Color used for multiple-texture blending with the D3DTA_TFACTOR texture-blending argument or the D3DTOP_BLENDFACTORALPHA texture-blending operation. The associated value is a D3DCOLOR variable.
D3DRS_WRAP0 through D3DRS_WRAP7
Texture-wrapping behavior for multiple sets of texture coordinates. Valid values for these render states can be any combination of the D3DWRAPCOORD_0 (or D3DWRAP_U), D3DWRAPCOORD_1 (or D3DWRAP_V), D3DWRAPCOORD_2 (or D3DWRAP_W), and D3DWRAPCOORD_3 flags. These cause the system to wrap in the direction of the first, second, third, and fourth dimensions, sometimes referred to at the s, t, r, and q directions, for a given texture. The default value for these render states is 0 (wrapping disabled in all directions).
D3DRS_CLIPPING
TRUE to enable primitive clipping by Microsoft® Direct3D®, or FALSE to disable it. The default value is TRUE.
D3DRS_LIGHTING
TRUE to enable Direct3D lighting, or FALSE to disable it. The default value is TRUE. Only vertices that include a vertex normal are properly lit; vertices that do not contain a normal employ a dot product of 0 in all lighting calculations.
D3DRS_AMBIENT
Ambient light color. This value is of type D3DCOLOR. The default value is 0.
D3DRS_FOGVERTEXMODE
Fog formula to be used for vertex fog. Set to one member of the D3DFOGMODE enumerated type. The default value is D3DFOG_NONE.
D3DRS_COLORVERTEX
TRUE to enable per-vertex color, or FALSE to disable it. The default value is TRUE. Enabling per-vertex color allows the system to include the color defined for individual vertices in its lighting calculations.

For more information, see the following render states:
- D3DRS_DIFFUSEMATERIALSOURCE
- D3DRS_SPECULARMATERIALSOURCE
- D3DRS_AMBIENTMATERIALSOURCE
- D3DRS_EMISSIVEMATERIALSOURCE
D3DRS_LOCALVIEWER
TRUE to enable camera-relative specular highlights, or FALSE to use orthogonal specular highlights. The default value is TRUE. Applications that use orthogonal projection should specify false.
D3DRS_NORMALIZENORMALS
TRUE to enable automatic normalization of vertex normals, or FALSE to disable it. The default value is FALSE. Enabling this feature causes the system to normalize the vertex normals for vertices after transforming them to camera space, which can be computationally expensive.
D3DRS_DIFFUSEMATERIALSOURCE
Diffuse color source for lighting calculations. Valid values are members of the D3DMATERIALCOLORSOURCE enumerated type. The default value is D3DMCS_COLOR1. The value for this render state is used only if the D3DRS_COLORVERTEX render state is set to TRUE.
D3DRS_SPECULARMATERIALSOURCE
Specular color source for lighting calculations. Valid values are members of the D3DMATERIALCOLORSOURCE enumerated type. The default value is D3DMCS_COLOR2.
D3DRS_AMBIENTMATERIALSOURCE
Ambient color source for lighting calculations. Valid values are members of the D3DMATERIALCOLORSOURCE enumerated type. The default value is D3DMCS_COLOR2.
D3DRS_EMISSIVEMATERIALSOURCE
Emissive color source for lighting calculations. Valid values are members of the D3DMATERIALCOLORSOURCE enumerated type. The default value is D3DMCS_MATERIAL.
D3DRS_VERTEXBLEND
Not supported in Windows CE.
D3DRS_CLIPPLANEENABLE
Enables or disables user-defined clipping planes. Valid values are any DWORD in which the status of each bit (set or not set) toggles the activation state of a corresponding user-defined clipping plane. The least significant bit (bit 0) controls the first clipping plane at index 0, and subsequent bits control the activation of clipping planes at higher indexes. If a bit is set, the system applies the appropriate clipping plane during scene rendering. The default value is 0.

The D3DCLIPPLANEn macros are defined to provide a convenient way to enable clipping planes.
D3DRS_SOFTWAREVERTEXPROCESSING
BOOL value that enables applications to query and select hardware or software vertex processing. For a D3DDEVTYPE_SW device type this value is fixed to TRUE. This value can be set by the application for a D3DDEVTYPE_REF device type. For a D3DDEVTYPE_HAL device type, this value can be set only by the application when D3DDEVCAPS_HWTRANSFORMANDLIGHT is set; otherwise this flag is fixed to TRUE. When variable, the default value is FALSE.

Changing the vertex processing render state in mixed vertex processing mode will reset the current stream, indices, and vertex shader to their default values of NULL or 0.
D3DRS_POINTSIZE
Float value that specifies the size to use for point size computation in cases where point size is not specified for each vertex. This value is not used when the vertex contains point size. This value is in screen space units if D3DRS_POINTSCALEENABLE is FALSE; otherwise this value is in world space units. The default value is 1.0f. The range for this value is greater than or equal to 0.0f. Because the IDirect3DDevice8::SetRenderState method accepts DWORD values, you application must cast a variable that contains the value, as shown in the following code example.
```
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*)&PointSize));
```
D3DRS_POINTSIZE_MIN
Float value that specifies the minimum size of point primitives. Point primitives are clamped to this size during rendering. Setting this to values smaller than 1.0 results in points dropping out when the point does not cover a pixel center. The default value is 1.0f. The range for this value is greater than or equal to 0.0f. Because the IDirect3DDevice8::SetRenderState method accepts DWORD values, you application must cast a variable that contains the value, as shown in the following code example.
```
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*)&PointSizeMin));
```
D3DRS_POINTSPRITEENABLE
Not supported.
D3DRS_POINTSCALEENABLE
BOOL value that controls computation of size for point primitives. When TRUE, the point size is interpreted as a camera space value and is scaled by the distance function and the frustum to viewport Y axis scaling to compute the final screen space point size. When FALSE, the point size is interpreted as screen space and used directly. The default value is FALSE.
D3DRS_POINTSCALE_A
Float value that controls for distance-based size attenuation for point primitives. Active only whenD3DRS_POINTSCALEENABLE is TRUE. The default value is 1.0f. The range for this value is greater than or equal to 0.0f. Because the IDirect3DDevice8::SetRenderState method accepts DWORD values, you application must cast a variable that contains the value, as shown in the following code example.
```
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*)&PointScaleA));
```
D3DRS_POINTSCALE_B
Float value that controls for distance-based size attenuation for point primitives. Active only when D3DRS_POINTSCALEENABLE is TRUE. The default value is 0.0f. The range for this value is greater than or equal to 0.0f. Because the IDirect3DDevice8::SetRenderState method accepts DWORD values, you application must cast a variable that contains the value, as shown in the following code example.
```
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*)&PointScaleB));
```
D3DRS_POINTSCALE_C
Float value that controls for distance-based size attenuation for point primitives. Active only when D3DRS_POINTSCALEENABLE is TRUE. The default value is 0.0f. The range for this value is greater than or equal to 0.0f. Because the IDirect3DDevice8::SetRenderState method accepts DWORD values, you application must cast a variable that contains the value, as shown in the following code example.
```
pd3dDevice8->SetRenderState(D3DRS_PATCHSEGMENTS, *((DWORD*)&PointScaleC));
```
D3DRS_MULTISAMPLEANTIALIAS
BOOL value that determines how individual samples are computed when using a multisample render target buffer. When set to TRUE, the multiple samples are computed so that full-scene antialiasing is performed by sampling at different sample positions for each multiple sample. When set to FALSE, the multiple samples are all written with the same sample value — sampled at the pixel center, which allows non-antialiased rendering to a multisample buffer. This render state has no effect when rendering to a single sample buffer. The default value is TRUE.
D3DRS_MULTISAMPLEMASK
Each bit in this mask, starting at the LSB, controls modification of one of the samples in a multisample render target. Thus, for an 8-sample render target, the low byte contains the 8 write enables for each of the 8 samples. This render state has no effect when rendering to a single sample buffer. The default value is 0xFFFFFFFF.

This render state enables use of a multisample buffer as an accumulation buffer, doing multipass rendering of geometry where each pass updates a subset of samples.
D3DRS_PATCHEDGESTYLE
Not supported in Windows CE.
D3DRS_PATCHSEGMENTS
Not supported in Windows CE.
D3DRS_DEBUGMONITORTOKEN
Set only for debugging the monitor. Possible values are defined by the D3DDEBUGMONITORTOKENS enumerated type. Note that if D3DRS_DEBUGMONITORTOKEN is set, the call is treated as passing a token to the debug monitor. For example, if, after passing D3DDMT_ENABLE or D3DDMT_DISABLE to D3DRS_DEBUGMONITORTOKEN, other token values are passed in, the state (enabled or disabled) of the debug monitor will still persist.

This state is only useful for debug builds. The debug monitor defaults to D3DDMT_ENABLE.
D3DRS_POINTSIZE_MAX
Not supported in Windows CE.
D3DRS_INDEXEDVERTEXBLENDENABLE
BOOL value that is always set to FALSE in Windows CE.
D3DRS_COLORWRITEENABLE
UINT value that enables a per-channel write for the render target color buffer. A set bit results in the color channel being updated during 3-D rendering. A clear bit results in the color channel being unaffected. This functionality is available if the D3DPMISCCAPS_COLORWRITEENABLE capabilities bit is set in the PrimitiveMiscCaps member of the D3DCAPS8 structure for the device. This render state does not affect the clear operation. The default value is 0x0000000F.

Valid values for this render state can be any combination of the D3DCOLORWRITEENABLE_ALPHA, D3DCOLORWRITEENABLE_BLUE, D3DCOLORWRITEENABLE_GREEN, or D3DCOLORWRITEENABLE_RED flags.
D3DRS_TWEENFACTOR
Not supported in Windows CE.
D3DRS_BLENDOP
Value used to select the arithmetic operation applied when the alpha blending render state, D3DRS_ALPHABLENDENABLE, is set to TRUE. Valid values are defined by the D3DBLENDOP enumerated type. The default value is D3DBLENDOP_ADD.

If the D3DPMISCCAPS_BLENDOP device capability is not supported, then D3DBLENDOP_ADD is performed.
D3DRS_FORCE_DWORD
Forces this enumeration to compile to 32 bits in size. This value is not used.

Remarks

Direct3D defines the D3DRENDERSTATE_WRAPBIAS constant as a convenience for applications to enable or disable texture wrapping, based on the zero-based integer of a texture coordinate set (rather than explicitly using one of the D3DRS_WRAPn state values). Add the D3DRENDERSTATE_WRAPBIAS value to the zero-based index of a texture coordinate set to calculate the D3DRS_WRAPn value that corresponds to that index, as shown in the following example.

// Enable U/V wrapping for textures that use the texture 
// coordinate set at the index within the dwIndex variable.
HRESULT hr = pd3dDevice->SetRenderState(
    dwIndex + D3DRENDERSTATE_WRAPBIAS,  
    D3DWRAPCOORD_0 | D3DWRAPCOORD_1);
 
// If dwIndex is 3, the value that results from 
// the addition equals D3DRS_WRAP3 (131).

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: D3d8types.h.

D3DRENDERSTATETYPE

Constants

Remarks

Requirements

See Also

Additional resources