Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This method sets a new color buffer, depth buffer, or both for the device.

Syntax 

HRESULT SetRenderTarget(
  IDirect3DMobileSurface* 
pRenderTarget,
  IDirect3DMobileSurface* 
pNewZStencil
);

Parameters

pRenderTarget

[in] Pointer to a new color buffer. If NULL, the existing color buffer is retained. If this parameter is not NULL, the reference count on the new render target is incremented. Devices always have to be associated with a color buffer.

The new render target surface must have at least D3DMUSAGE_RENDERTARGET (see D3DMUSAGE Values) specified.

pNewZStencil

[in] Pointer to a new depth-stencil buffer. If there is an existing depth-stencil buffer, it is released. If this parameter is not NULL, the reference count on the new depth-stencil buffer surface is incremented. Applications can change the render target without changing the depth buffer by passing in the ppZStencilSurfaceparameter of IDirect3DMobileDevice::GetDepthStencilSurface.

The new depth-stencil surface must at least have D3DMPOOL_SYSTEMMEM (see D3DMPOOL) specified.

Return Value

If the method succeeds, the return value is D3DM_OK (see D3DM Values).

If the method fails, the return value can be D3DMERR_INVALIDCALL (see D3DMERR Values), if pRenderTargetor pNewZStencilare not NULL and invalid, or if the new depth buffer is smaller than the new or retained color buffer.

Remarks

When a color buffer and a depth-stencil surface have been associated with the same device by this method, they are said to be paired.

The device will call IUnknown::AddRefon each non-NULL surface passed to IDirect3DMobileDevice::SetRenderTarget. After that, the device calls IUnknown::Releaseon the previously set color buffer.

The previous depth-stencil surface's contents persist after a call to IDirect3DMobileDevice::SetRenderTargetto disassociate the previous depth-stencil surface from the device. If the surface is re-associated with the device, then the contents of the surface will be unchanged — if the color buffer to which the new depth-stencil surface is being paired is the same size and format as the color buffer to which the depth-stencil surface was most recently paired.

Calling this method resets the current viewport of the device to the size of the current render target. This is done regardless of whether the z-buffer is the only one that is being changed.

Requirements

Header d3dm.h
Library D3dm.lib, D3dmguid.lib
Windows Embedded CE Windows CE 5.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also