GXCopyTex

Syntax

#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 being copied is cleared.

Return Values

None.

Description

This function copies the embedded frame buffer (EFB) to the 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 set by the GXSetTexCopySrc function. The EFB is converted to the texture format during the copy. The texture format and an optional box filter enable are set using the GXSetTexCopyDst function.

The allocated buffer must be padded to texture tiles (32 bytes/tile) in the X and Y directions. The GXGetTexBufferSize function 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 the GXSetCopyClear function.

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

  1. You cannot avoid clearing alpha when clearing RGB (the GXSetAlphaUpdate function is ignored).
  2. 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 the GXPixModeSync function after the copy and prior to the primitive rendering.

Note: Even when copying within a texture buffer, the vertical filter set with GXSetCopyFilter will still operate. You must be careful when you have configured the vertical filter to copy to the external frame buffer.

See Also

GXSetTexCopySrc, GXSetTexCopyDst, GXSetCopyFilter

Revision History

2007/03/05 Added note about and reference to GXSetCopyFilter.
2006/03/01 Initial version.

CONFIDENTIAL