Name

cgD3D9SetDevice - set the D3D device

Synopsis

#include <Cg/cgD3D9.h>

HRESULT cgD3D9SetDevice( IDirect3DDevice9 * device );

Parameters

device

Pointer to an IDirect3DDevice9 interface that the expanded interface will use for any D3D-specific routine it may call. This parameter can be NULL to free all D3D resources used by the expanded interface and remove its reference to the D3D device.

Return Values

Returns D3D_OK if the function succeeds.

Returns the D3D failure code if the function fails due to a D3D call.

Description

cgD3D9SetDevice informs the expanded interface of the new D3D device. This will destroy any D3D resources for programs previously loaded with cgD3D9LoadProgram and use the new D3D device to recreate them. The expanded interface will increment the reference count to the D3D device, so this function must eventually be called with NULL to release that reference so D3D can be properly shut down.

If device is NULL, all D3D resources for programs previously loaded with cgD3D9LoadProgram are destroyed. However, these programs are still considered managed by the expanded interface, so if a new D3D device is set later these programs will be recreated using the new D3D device.

If a new device is being set, all D3D resources for programs previously loaded with cgD3D9LoadProgram are rebuilt using the new device. All shadowed parameters for these programs are maintained across D3D device changes except texture parameters. Since textures in D3D are bound to a particular D3D device, these resources cannot be saved across device changes. When these textures are recreated for the new D3D device, they must be re-bound to the sampler parameter.

Note that calling cgD3D9SetDevice(NULL) does not destroy any core runtime resources (CGprograms, CGparameters, etc.) used by the expanded interface. These must be destroyed seperately using cgDestroyProgram and cgDestroyContext.

Examples

// pDev is an IDirect3DDevice9 interface initialized elsewhere
...
cgD3D9SetDevice(pDev);

Errors

cgD3D9Failed is generated if a D3D function returns an error.

History

cgD3D9SetDevice was introduced in Cg 1.1.

See Also

cgD3D9GetDevice, cgDestroyProgram, cgDestroyContext, cgD3D9LoadProgram