The IDirect3DDevice3::SetRenderTarget method permits the application to easily route rendering output to a new DirectDraw surface as a render target.
HRESULT SetRenderTarget(
LPDIRECTDRAWSURFACE4 lpNewRenderTarget,
DWORD dwFlags
);
If the method succeeds, the return value is D3D_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. |
You cannot use this method to set a new render target surface with a depth-buffer if the current render target does not have a depth buffer. Likewise, you cannot use this method to switch from a non-depth-buffered render target to a depth-buffered render target. Attempts to do this will fail in debug builds, and can exhibit unreliable behavior in retail builds. Given that both the new and old render targets use depth buffers, the depth-buffer attached to the new render target replaces the previous depth-buffer for the context.
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 IDirect3DMaterial3::SetMaterial method. Any execute buffers (which have embedded handles) also need to be updated. The IDirect3DDevice3::SetRenderTarget 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 IDirect3DDevice3::SetRenderTarget by calling IDirect3DViewport3::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 more than one depth-buffer is attached to the render target, this function fails.
This method was introduced with the IDirect3DDevice2 interface.
Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in d3d.h.
Import Library: Use ddraw.lib.