GXSetTexCopyDst

C Specification

#include <revolution/gx.h>

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

Arguments

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

ht the height of the texture buffer

fmt

the generated texture format
Accepted values are:

Name	Texture Format
`GX_TF_I4`	intensity 4-bit value (see 1)
`GX_TF_IA4`	intensity 4-bit plus the alpha 4-bit value (see 1)
`GX_TF_I8`	intensity 8-bit value (see 1)
`GX_TF_IA8`	intensity 8-bit plus the alpha 8-bit value (see 1)
`GX_TF_RGB565`	16-bit color (RGB565)
`GX_TF_RGB5A3`	16-bit color + alpha (RGB555 or RGBA4443)
`GX_TF_RGBA8`	the 32-bit full color RGBA (8 bits per element)
`GX_TF_Z8`	the first 8 bits from the Z buffer copied to 8-bit format
`GX_TF_Z16`	the first 16 bits from the Z buffer copied to 16-bit format (see 2)
`GX_TF_Z24X8`	all 24 bits from the Z buffer copied to 32-bit format The upper 8 bits are set to 0xFF.
`GX_CTF_R4`	4 bits copied from the red element Results can be used as I4 format.
`GX_CTF_RA4`	4 bits each copied from the red and alpha elements Results can be used as IA4 format.
`GX_CTF_RA8`	8 bits each copied from the red and alpha elements Results can be used as IA8 format.
`GX_CTF_A8`	8 bits copied from the alpha element Results can be used as I8 format.
`GX_CTF_R8`	8 bits copied from the red element Results can be used as I8 format.
`GX_CTF_G8`	8 bits copied from the green element Results can be used as I8 format.
`GX_CTF_B8`	8 bits copied from the blue element Results can be used as I8 format.
`GX_CTF_RG8`	8 bits each copied from the red and green elements Results can be used as IA8 format.
`GX_CTF_GB8`	8 bits each copied from the green and blue elements Results can be used as IA8 format.
`GX_CTF_Z4`	upper 4 bits from the Z value copied to 4-bit format
`GX_CTF_Z8M`	middle 8 bits of the Z value copied to 8-bit format
`GX_CTF_Z8L`	lower 8 bits from the Z value copied to 8-bit format
`GX_CTF_Z16L`	lower 16 bits from the Z value copied to 16-bit format (see 2)

mipmap For 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, 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 more information on the texture copy format.

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 16 to 235. If exact values from the EFB are needed, formats like R8 and RA8 can be used.

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