Edit

IDirect3DDevice9::CreateRenderTarget method (d3d9.h)

  • Article

Creates a render-target surface.

Syntax

HRESULT CreateRenderTarget(
  [in]          UINT                Width,
  [in]          UINT                Height,
  [in]          D3DFORMAT           Format,
  [in]          D3DMULTISAMPLE_TYPE MultiSample,
  [in]          DWORD               MultisampleQuality,
  [in]          BOOL                Lockable,
  [out, retval] IDirect3DSurface9   **ppSurface,
  [in]          HANDLE              *pSharedHandle
);

Parameters

[in] Width

Type: UINT

Width of the render-target surface, in pixels.

[in] Height

Type: UINT

Height of the render-target surface, in pixels.

[in] Format

Type: D3DFORMAT

Member of the D3DFORMAT enumerated type, describing the format of the render target.

[in] MultiSample

Type: D3DMULTISAMPLE_TYPE

Member of the D3DMULTISAMPLE_TYPE enumerated type, which describes the multisampling buffer type. This parameter specifies the antialiasing type for this render target. When this surface is passed to IDirect3DDevice9::SetRenderTarget, its multisample type must be the same as that of the depth-stencil set by IDirect3DDevice9::SetDepthStencilSurface.

[in] MultisampleQuality

Type: DWORD

Quality level. The valid range is between zero and one less than the level returned by pQualityLevels used by IDirect3D9::CheckDeviceMultiSampleType. Passing a larger value returns the error, D3DERR_INVALIDCALL. The MultisampleQuality values of paired render targets, depth stencil surfaces, and the multisample type must all match.

[in] Lockable

Type: BOOL

Render targets are not lockable unless the application specifies TRUE for Lockable.

Note that lockable render targets reduce performance on some graphics hardware. The readback performance (moving data from video memory to system memory) depends on the type of hardware used (AGP vs. PCI Express) and is usually far lower than upload performance (moving data from system to video memory). If you need read access to render targets, use GetRenderTargetData instead of lockable render targets.

[out, retval] ppSurface

Type: IDirect3DSurface9**

Address of a pointer to an IDirect3DSurface9 interface.

[in] pSharedHandle

Type: HANDLE*

Reserved. Set this parameter to NULL. This parameter can be used in Direct3D 9 for Windows Vista to share resources.

Return value

Type: HRESULT

If the method succeeds, the return value is D3D_OK. If the method fails, the return value can be one of the following: D3DERR_NOTAVAILABLE, D3DERR_INVALIDCALL, D3DERR_OUTOFVIDEOMEMORY, E_OUTOFMEMORY.

Remarks

Render-target surfaces are placed in the D3DPOOL_DEFAULT memory class.

The creation of lockable, multisampled render targets is not supported.

Requirements

Requirement Value
Target Platform Windows
Header d3d9.h (include D3D9.h)
Library D3D9.lib

See also

IDirect3DDevice9