GXSetPixelFmt

Syntax

#include <revolution/gx.h>

void GXSetPixelFmt(
    GXPixelFmt    pix_fmt, 
    GXZFmt16      z_fmt );

Arguments

pix_fmt

Pixel format. Accepted values are:

Name	Pixel Format
GX_PF_RGB8_Z24	No antialiasing. 8-bit for each RGB value, 24-bit Z value.
GX_PF_RGBA6_Z24	No antialiasing. 6-bit for each RGBA value, 24-bit Z value.
GX_PF_RGB565_Z16	Antialiasing. RGB565, 16-bit Z value.

When GX_PF_RGB565_Z16 is selected, antialiasing mode is turned on. It is off otherwise.

z_fmt

The compression type for the 16-bit Z format. Accepted values are:

Name	Z format
GX_ZC_LINEAR	16-bit linear.
GX_ZC_NEAR	Compressed format for smaller far/near ratio.
GX_ZC_MID	Compressed format for medium far/near ratio.
GX_ZC_FAR	Compressed format for large far/near ratio.

This argument is ignored if a 24-bit Z format is selected.

Return Values

None.

Description

Sets the format of pixels in the embedded frame buffer (EFB) internal to the graphics processor. It also controls the antialiasing (AA) mode.

There are two pix_fmt pixel formats that are not antialiased: GX_PF_RGB8_Z24 and GX_PF_RGBA6_Z24. The EFB stride is 640 pixels. The non-antialiased EFB has 528 lines available.

When pix_fmt is GX_PF_RGB565_Z16, multi-sample antialiasing is enabled. To get the correct results, the GXSetCopyFilter function must also be called. The position of the subsamples and the antialiasing filter coefficients are set using the GXSetCopyFilter function. When antialiasing, three 16-bit color/Z samples are calculated for each pixel, and the total available number of pixels in the EFB is reduced by half (640 pixels x 264 lines).

The GXSetPixelFmt function also sets the compression type for 16-bit Z formats, which allows Z precision tradeoffs related to the range. The following guidelines apply.

a) far/near ratio <= 2^16, use GX_ZC_LINEAR
b) far/near ratio <= 2^18, use GX_ZC_NEAR
c) far/near ratio <= 2^20, use GX_ZC_MID
d) far/near ratio <= 2^24, use GX_ZC_FAR

It is always best to use as little compression as possible: Choice (a) is least compressed, and choice (d) is most compressed. Higher compression results in less precision. The "far" in the above list does not necessarily reference the far clipping plane. You should think of it as the farthest object for which you want to have accurate occlusion.

Note: When the pixel format is changed, the data format inside EFB also changes. Therefore, when you switch pixel formats during rendering, the result of rendering will not be as intended. For example, it is not possible to render up to a certain point in RGB8, and then render only a particular object in the antialiasing mode.

Because changing the pixel format requires the pixel pipeline to be synchronized, the use of this function causes the graphics processor to stall as a result. Therefore, redundant calls of this function should be avoided.

Revision History

2009/01/05 Added the GXGetPixelFmt function under See Also.
2007/06/13 Added a note and included the description about stalling.
2006/03/01 Initial version.

CONFIDENTIAL