The IDirect3DDevice2::SetRenderTarget method permits the application to easily route rendering output to a new DirectDraw surface as a render target.
HRESULT SetRenderTarget(
LPDIRECTDRAWSURFACE lpNewRenderTarget,
DWORD dwFlags
);
If the method succeeds, the return value is DD_OK.
If the method fails, the return value is an error. The error may be one of the following values:
| DDERR_INVALIDPARAMS | One of the arguments is invalid. |
| DDERR_INVALIDSURFACETYPE | The surface passed as the first parameter is invalid. |
When you change the rendering target, all of the handles associated with the previous rendering target become invalid. This means that you will have to reacquire all of the texture handles. If you are using ramp mode, you should also update the texture handles inside materials, by calling the IDirect3DMaterial2::SetMaterial method. Any execute buffers (which have embedded handles) also need to be updated. The IDirect3DDevice2::SetRenderState method is most useful to applications that use the DrawPrimitive methods, especially when these applications do not use ramp mode.
If the new render target surface has different dimensions from the old (length, width, pixel-format), this method marks the viewport as invalid. The viewport may be revalidated after calling IDirect3DDevice2::SetRenderTarget by calling IDirect3DViewport2::SetViewport to restate viewport parameters that are compatible with the new surface.
Capabilities do not change with changes in the properties of the render target surface. Both the Direct3D HAL and the software rasterizers have only one opportunity to expose capabilities to the application. The system cannot expose different sets of capabilities depending on the format of the destination surface.
If a z-buffer is attached to the new render target, it replaces the previous z-buffer for the context. Otherwise, the old z-buffer is detached and z-buffering is disabled.
If more than one z-buffer is attached to the render target, this function fails.
This method was introduced with the IDirect3DDevice2 interface.
Windows NT: Use version 5.0 or later.
Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in d3d.h.
Import Library: Use ddraw.lib.
IDirect3DDevice2::GetRenderTarget