Package com.ms.com.directX

Previous

Microsoft Packages

Index

Next

Class d3dDevice

Applications use the methods of the d3dDevice class to retrieve and set the capabilities of Direct3D devices.

public class d3dDevice implements Id3dDevice
{
  public void InternalSetObject(IUnknown lpdd);
  public IUnknown InternalGetObject();
  public void Initialize(d3d dev, GuidData g, d3dDeviceDesc desc);
  public void GetCaps(d3dDeviceDesc HWDesc, d3dDeviceDesc HELDesc);
  public void SwapTextureHandles(d3dTexture tex1, d3dTexture tex2);
  public d3dExecuteBuffer CreateExecuteBuffer(d3dExecuteBufferDesc desc, int[] buf, IUnknown punk);
  public void FlushExecuteBuffer(d3dExecuteBufferDesc buf, int[] buffer);
  public void GetStats(d3dstats stat);
  public void Execute(d3dExecuteBuffer eb, d3dViewport vp, int flags);
  public void AddViewport(d3dViewport vport);
  public void DeleteViewport(d3dViewport vport);
  public d3dViewport NextViewport(d3dViewport vp1, int flags);
  public void Pick(d3dExecuteBuffer eb, d3dViewport vport, int flags, d3dRect Rect);
  public void GetPickRecords(int[] flags, d3dPickRecord val);
  public void EnumTextureFormats(IEnumTextureFormatsCallback fn, IUnknown args);
  public int CreateMatrix();
  public void SetMatrix(int hdl, d3dMatrix mat);
  public void GetMatrix(int hdl, d3dMatrix mat);
  public void DeleteMatrix(int hdl);
  public void BeginScene();
  public void EndScene();
  public d3d GetDirect3D();
}

The methods can be organized into the following groups:

Execution	CreateExecuteBuffer
	Execute
	FlushExecuteBuffer
Information	EnumTextureFormats
	GetCaps
	GetDirect3D
	GetPickRecords
	GetStats
Matrices	CreateMatrix
	DeleteMatrix
	GetMatrix
	SetMatrix
Miscellaneous	Initialize
	Pick
	SwapTextureHandles
Scenes	BeginScene
	EndScene
Viewports	AddViewport
	DeleteViewport
	NextViewport

AddViewport

public void AddViewport(d3dViewport vport);

Adds the specified viewport to the list of viewport objects associated with the device.

Return Value:

No return value.

Parameter	Description
vport	Viewport object that should be associated with this d3dDevice object.

BeginScene

public void BeginScene();

Begins a scene.

Return Value:

No return value.

Remarks:

Applications must call this method before performing any rendering, and must call EndScene when rendering is complete.

See Also: EndScene

CreateExecuteBuffer

public d3dExecuteBuffer CreateExecuteBuffer(d3dExecuteBufferDesc desc, int[] buf, IUnknown punk);

Allocates an execute buffer for a display list. The list may be read by hardware DMA into VRAM for processing. All display primitives in the buffer that have indices to vertices must also have those vertices in the same buffer.

Return Value:

Returns the d3dExecuteBuffer if successful; null otherwise.

Parameter	Description
desc	Describes the d3dExecuteBuffer object to be created. The call will fail if a buffer of at least the specified size cannot be created.
buf	Array variable that contains the initial data for the buffer. Used only if the D3DDEB_LPDATA flag is set in the dwCaps field of desc. If used, the length of this array must be set in the dwBufferSize field.
punk	Reserved; must be null.

Remarks:

The d3dExecuteBufferDesc object describes the execute buffer to be created. At a minimum, the application must specify the size required. If the application specifies DEBCAPS_VIDEO_MEMORY in the capabilities field, Direct3D will attempt to keep the execute buffer in video memory.

The application can use the Lock method to request that the memory be moved. When this method returns, it will adjust the contents of the d3dExecuteBufferDesc object to indicate whether the data resides in system or video memory.

CreateMatrix

public int CreateMatrix();

Creates a matrix.

Return Value:

Returns a handle to the matrix that is created. The call will fail if a buffer of at least the size of the matrix cannot be created.

See Also: DeleteMatrix, SetMatrix

DeleteMatrix

public void DeleteMatrix(int hdl);

Deletes a matrix handle. This matrix handle must have been created by using the CreateMatrix method.

Return Value:

No return value.

Parameter	Description
hdl	Matrix handle to be deleted.

See Also: CreateMatrix, SetMatrix

DeleteViewport

public void DeleteViewport(d3dViewport vport);

Removes the specified viewport from the list of viewport objects associated with the device.

Return Value:

No return value.

Parameter	Description
vport	Viewport object that should be disassociated with this d3dDevice object.

EndScene

public void EndScene();

Ends a scene that was begun by calling the BeginScene method.

Return Value:

No return value.

See Also: BeginScene

EnumTextureFormats

public void EnumTextureFormats(IEnumTextureFormatsCallback fn, IUnknown args);

Queries the current driver for a list of supported texture formats.

Return Value:

No return value.

Parameter	Description
fn	Callback interface containing the function that the enumeration procedure will call for each texture format.
args	Application-defined data passed to the callback function.

Execute

public void Execute(d3dExecuteBuffer eb, d3dViewport vp, int flags);

Executes a buffer.

Return Value:

No return value.

Parameter	Description
eb	Execute buffer to be executed.
vp	The d3dViewport object that describes the transformation context into which the execute buffer will be rendered.
flags	A value of D3DEXECUTE_ type, specifying whether or not objects in the buffer should be clipped.

See Also: Validate

FlushExecuteBuffer

public void FlushExecuteBuffer(d3dExecuteBufferDesc buf, int[] buffer);

Flushes command data into the execute buffer.

Return Value:

No return value.

Parameter	Description
buf	The d3dExecuteBufferDesc object that describes the execute buffer to receive the command data.
buffer	Array variable that contains the command data to flush. The length of the array assigned to this variable must be set in the dwBufferSize field before making the call.

GetCaps

public void GetCaps(d3dDeviceDesc HWDesc, d3dDeviceDesc HELDesc);

Retrieves the capabilities of the d3dDevice object.

Return Value:

No return value.

Parameter	Description
HWDesc	The d3dDeviceDesc object that receives the hardware features of the device.
HELDesc	The d3dDeviceDesc object that receives the software emulation being provided.

Remarks:

This method does not retrieve the capabilities of the display device. To retrieve this information, use the GetCaps method.

GetDirect3D

public d3d GetDirect3D();

Retrieves the current d3d object.

Return Value:

Returns the d3d object if successful; null otherwise.

GetMatrix

public void GetMatrix(int hdl, d3dMatrix mat);

Retrieves a matrix from a matrix handle. This matrix handle must have been created by using the CreateMatrix method.

Return Value:

No return value.

Parameter	Description
hdl	Handle of the matrix to be retrieved.
mat	The d3dMatrix object that receives the matrix.

See Also: CreateMatrix, DeleteMatrix, SetMatrix

GetPickRecords

public void GetPickRecords(int[] flags, d3dPickRecord val);

Retrieves the pick records for a device.

Return Value:

No return value.

Parameter	Description
flags	An array variable.
val	The d3dPickRecord object that receives a pick record.

GetStats

public void GetStats(d3dstats stat);

Retrieves statistics about a device.

Return Value:

No return value.

Parameter	Description
stat	The d3dstats object that receives the statistics.

Initialize

public void Initialize(d3d dev, GuidData g, d3dDeviceDesc desc);

Initializes a d3dDevice object.

Return Value:

No return value.

Parameter	Description
dev	The Direct3D device to use as an initializer.
g	The globally unique identifier (GUID) used as the interface identifier.
desc	The d3dDeviceDesc object describing the d3dDevice object to be initialized.

NextViewport

public d3dViewport NextViewport(d3dViewport vp1, int flags);

Enumerates the viewports associated with the device.

Return Value:

Returns the next d3dViewport object in the list of viewports associated with this Direct3DDevice object if successful; null otherwise.

Parameter	Description
vpl	A viewport in the list of viewports associated with this d3dDevice object.
flags	One value of D3DNEXT_ type, specifying which viewport to retrieve from the list of viewports. The default setting is D3DNEXT_NEXT.

Pick

public void Pick(d3dExecuteBuffer eb, d3dViewport vport, int flags, d3dRect Rect);

Executes a buffer without performing any rendering, but returns a z-ordered list of offsets to the primitives that cover the rectangle specified by Rect.

This call fails if the d3dExecuteBuffer object is locked.

Return Value:

No return value.

Parameter	Description
eb	An execute buffer from which the z-ordered list is retrieved.
vport	A viewport in the list of viewports associated with this d3dDevice object.
flags	No flags are currently defined for this method.
Rect	The d3dRect object specifying the range of device coordinates to be picked.

Remarks:

If the x1 and x2 fields of the object specified in the Rect parameter are equal, and the y1 and y2 members are equal, a single pixel is used for picking. The coordinates are specified in device-pixel space.

All d3dExecuteBuffer objects must be attached to a d3dDevice object in order for this method to succeed.

See Also: GetPickRecords

SetMatrix

public void SetMatrix(int hdl, d3dMatrix mat);

Applies a matrix to a matrix handle. This matrix handle must have been created by using the CreateMatrix method.

Return Value:

No return value.

Parameter	Description
hdl	Matrix handle to be set.
mat	The d3dMatrix object that describes the matrix to be set.

Remarks:

Transformations inside the execute buffer include a handle of a matrix. The SetMatrix method enables an application to change this matrix without having to lock and unlock the execute buffer.

See Also: CreateMatrix, GetMatrix, DeleteMatrix

SwapTextureHandles

public void SwapTextureHandles(d3dTexture tex1, d3dTexture tex2);

Swaps two texture handles.

Return Value:

No return value.

Parameter	Description
tex1 and tex2	The textures to be swapped.

Remarks:

This method is useful when an application is changing all the textures in a complicated object.