GXCopyTex

C Specification

#include <revolution/gx.h>

void GXCopyTex( 
void*         dest, 
GXBool        clear );

Arguments

`dest`	Pointer to the texture image buffer in main memory. This pointer should be 32-byte aligned.
`clear`	When this flag is set to `GX_TRUE`, the frame buffer is cleared while copying.

Return Values

None.

Description

This function copies the ebedded fame bufer (EFB) to a texture image buffer dest in main memory. This is useful when creating textures using the gaphics processor (GP). If the clear flag is GX_TRUE, the EFB will be cleared to the current clear color (see the GXSetCopyClear function) during the copy operation. The source image is described by GXSetTexCopySrc. The EFB is converted to the texture format during the copy. The texture format and an optional box filter enable are set using GXSetTexCopyDst.

The allocated buffer must be padded to texture tiles (32B/tile) in X and Y. The function GXGetTexBufferSize is provided to determine the padded size.

The clear flag indicates the frame buffer should be cleared during the copy operation. The frame buffer is cleared to the constant values specified by GXSetCopyClear.

Note: If the copy format (specified in GXSetTexCopyDst) indicates a Z copy type, then (for the purpose of clearing the frame buffer) the EFB is assumed to be in RGB8 format (regardless of the value of GXSetPixelFmt). This has two implications if the EFB is really in RGBA6 format:

You cannot avoid clearing alpha when clearing RGB (GXSetAlphaUpdate is ignored).
The clear-color value will be written to the frame buffer incorrectly (the clear-color bits [R7:R0][G7:G0][B7:B0] will be written over the EFB bits [R5:R0][G5:G0][B5:B0][A5:A0]).

If you plan to follow the GXCopyTex command with a primitive that will use the newly-copied texture, you must be sure that the texture has been completely copied out before the primitive starts to draw. You may do this by inserting a GXPixModeSync command after the copy and prior to the primitive.

Revision History