PFND3DDDI_DRAWTRIPATCH callback function

Description

The DrawTriPatch function draws a new or cached triangular patch or updates the specification of a previously defined patch.

Parameters

hDevice [in]

A handle to the display device (graphics context).

unnamedParam2

pData [in]

A pointer to a D3DDDIARG_DRAWTRIPATCH structure that describes the triangular patch to draw.

unnamedParam3

pInfo [in]

Optional. A pointer to a D3DDDITRIPATCH_INFO structure that describes information about the triangular patch.

unnamedParam4

pPatch [in]

Optional. A pointer to a buffer that contains three floating-point values (D3DFLOAT[3]) that provide the segment counts for each of the three edges of the triangular patch.

Return value

DrawTriPatch returns S_OK or an appropriate error result if the triangular patch is not successfully drawn.

Remarks

When the Microsoft Direct3D runtime calls the user-mode display driver's DrawTriPatch function, it can optionally supply information in the pInfo and pPatch parameters. The runtime sets flags in the Flags member of the D3DDDIARG_DRAWTRIPATCH structure that is specified by pData to indicate if it supplies this optional information.

The runtime supplies a UINT value in the Handle member of D3DDDIARG_DRAWTRIPATCH to refer to the patch surface. Whenever the runtime redraws the patch surface, it passes the patch handle value and is not required to re-specify the D3DDDITRIPATCH_INFO data structure for the patch surface. The user-mode display driver can precompute and cache forward-difference coefficients and any other information. Therefore, subsequent calls to the driver's DrawTriPatch function that use the same patch handle value run more efficiently.

The actual value in Handle is determined by the application and is not under runtime control. Therefore, the driver must handle any value that can be specified by a UINT.

The special Handle value of zero indicates that the patch is dynamic; therefore, the driver cannot precompute or cache information for the patch. A nonzero value for Handle indicates that the patch is static (or updated with low frequency); therefore, the driver can precompute and cache information for the patch.

The driver must handle the following scenarios in its DrawTriPatch function:

• If the Handle member is zero, the patch is dynamic. The driver should neither precompute nor cache information for the patch. In this situation, the runtime passes a pointer to a D3DDDITRIPATCH_INFO structure in the pInfo parameter and sets the RTPATCHFLAG_HASINFO flag in the Flags member of the D3DDDIARG_DRAWTRIPATCH structure to indicate the presence of the D3DDDITRIPATCH_INFO structure at pInfo. Optionally, the runtime can also set the RTPATCHFLAG_HASSEGS flag in Flags to indicate the presence of the segment information that is specified the pPatch parameter. However, if the runtime does not supply segment information at pPatch, the runtime should instead use the D3DRS_PATCHSEGMENTS render state value.
• If a nonzero Handle value has not been previously specified in an earlier call to the driver's DrawTriPatch function, the runtime draws a new cacheable patch. The driver should allocate memory to store cached data and should add this data to its patch handle table. Because the runtime has not previously drawn this patch, the runtime should set the RTPATCHFLAG_HASINFO flag and pass a pointer to a D3DDDIRECTPATCH_INFO structure in the pInfo parameter. The driver must check for the RTPATCHFLAG_HASINFO flag to verify the presence of the patch information. If no patch information is specified, the driver should ignore the DrawTriPatch call and should not allocate memory for cached data in its patch handle table. Optionally, the runtime can set the RTPATCHFLAG_HASSEGS flag to indicate the presence of the segment information. However, if the runtime does not supply segment information at pPatch, the runtime should instead use the D3DRS_PATCHSEGMENTS render state value.
• If a nonzero Handle value has been previously specified in an earlier call to the driver's DrawTriPatch function and the RTPATCHFLAG_HASINFO flag is set, the runtime updates the definition for the patch. The runtime passes a pointer to a D3DDDITRIPATCH_INFO structure in the pInfo parameter, and the driver must recompute and recache the patch information. Optionally, the runtime can set the RTPATCHFLAG_HASSEGS flag to indicate the presence of the segment information. However, if the runtime does not supply segment information at pPatch, the runtime should instead use the D3DRS_PATCHSEGMENTS render state value.
• If a nonzero Handle value has been previously specified in an earlier call to the driver's DrawTriPatch function and the RTPATCHFLAG_HASINFO flag is not set, the runtime redraws the patch. The driver should use the cached information to draw the patch. In this situation, the driver ignores the current vertex streams and the cached information is used instead. However, the runtime can still specify new segment information; therefore, the driver should check for the RTPATCHFLAG_HASSEGS flag and handle specified segment information even if it uses a cached patch.

The driver receives notification to release cached patch information through the D3DRS_DELETERTPATCH render state. The value of this render state is the patch to delete.

See also

D3DDDIARG_DRAWTRIPATCH

D3DDDI_DEVICEFUNCS