GXSetTexCopyDst

Syntax

#include <revolution/gx.h>

void GXSetTexCopyDst( 
    u16       wd, 
    u16       ht, 
    GXTexFmt  fmt, 
    GXBool    mipmap );

Arguments

wd The distance (in texels) between contiguous lines within the texture buffer. It must be a multiple of the texture tile width dependent on the texture format, fmt.

ht Height of the texture buffer.

fmt

The generated texture format. Accepted values are:

Name	Texture Format
GX_TF_I4	The intensity 4-bit (see note 1).
GX_TF_IA4	The intensity 4-bit plus the alpha 4-bit (see note 1).
GX_TF_I8	The intensity 8-bit (see note 1).
GX_TF_IA8	The intensity 8-bit plus the alpha 8-bit (see note 1).
GX_TF_RGB565	16-bit color (RGB565)
GX_TF_RGB5A3	16-bit color + alpha (RGB555 or RGBA4443)
GX_TF_RGBA8	32-bit full RGBA (8 bits per element).
GX_TF_Z8	The first 8 bits from the Z buffer are copied to the 8-bit format.
GX_TF_Z16	The first 16 bits from the Z buffer are copied to the 16-bit format (see note 2).
GX_TF_Z24X8	All 24 bits from the Z buffer are copied to the 32-bit format. The first 8 bits are set to 0xFF.
GX_CTF_R4	4 bits are copied from the R element. The results are handled in the I4 format.
GX_CTF_RA4	4 bits each are copied from the R and alpha elements. The results are handled in the IA4 format.
GX_CTF_RA8	8 bits each are copied from the R and alpha elements. The results are handled in the IA8 format.
GX_CTF_A8	8 bits are copied from the alpha element. The results are handled in the I8 format.
GX_CTF_R8	8 bits are copied from the R element. The results are handled in the I8 format.
GX_CTF_G8	8 bits are copied from the G element. The results are handled in the I8 format.
GX_CTF_B8	8 bits are copied from the B element. The results are handled in the I8 format.
GX_CTF_RG8	8 bits each are copied from the R and G elements. The results are handled in the IA8 format.
GX_CTF_GB8	8 bits each are copied from the G and B elements. The results are handled in the IA8 format.
GX_CTF_Z4	The first 4 bits from the Z value are copied to the 4-bit format.
GX_CTF_Z8M	The 8 bits from the middle of the Z value are copied to the 8-bit format.
GX_CTF_Z8L	The last 8 bits from the Z value are copied to the 8-bit format.
GX_CTF_Z16L	The last 16 bits from the Z value are copied to the 16-bit format (see note 2).

mipmap When GX_TRUE, a box filter is applied to the EFB before the texture is generated.

Return Values

None.

Description

This function sets the width, wd, and height, ht, of the destination texture buffer in texels. The application may render an image into the embedded frame buffer (EFB, the source) and then copy it into a texture buffer in main memory. wd specifies the number of texels between adjacent lines in the texture buffer and can be different than the width of the source image. This function also sets the texture format, fmt, generated during the copy operation for texel generation. An optional box filter can be enabled using the mipmap flag. This flag will scale the source image by 1/2 in both width and height.

Normally, the width of the EFB and the destination wd are the same. When rendering smaller images that get copied and composited into a larger texture buffer, however, the EFB width and texture buffer wd are not necessarily the same.

The Z buffer can be copied to a Z texture format by setting fmt to GX_TF_Z24X8. Doing so is only valid when the EFB format is GX_PF_RGB8_Z24 or GX_PF_RGBA6_Z24.

The alpha channel can be copied from an EFB with the format GX_PF_RGBA6_Z24 by setting fmt to GX_TF_A8.

The GXGetTexBufferSize function can be used to calculate the texture buffer size based on the texture parameters. The GXCopyTex function actually performs the copy operation.

See GXTexFmt for information on the texture copy format.

Note 1: Texture copies into intensity formats (GX_TF_I8, GX_TF_I4, GX_TF_IA8 and GX_TF_IA4) use the resulting Y value from RGB-YUV conversion as the intensity value. This means that the output range is linearly compressed to a range from 16 to 235. Be sure to use a format such as R8 or RA8 if your intention is not to get an intensity value, but rather to accurately obtain 8-bit data located in the EFB.

Note 2: Due to hardware design issues, texture copies into 16-bit Z formats put data in reverse byte order. Results cannot be directly used for Z textures.

Revision History

2008/09/09 Added information to Note 1 about the reason for using formats such as R8 and RA8.
2008/07/22 Corrected a typo in the description of GX_CTF_A8.
2006/03/01 Initial version.