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 anti-aliasing. 8-bit for each RGB value, 24-bit Z value.
GX_PF_RGBA6_Z24	No anti-aliasing. 6-bit for each RGBA value, 24-bit Z value.
GX_PF_RGB565_Z16	Anti-aliasing. RGB565, 16-bit Z value.

When GX_PF_RGB565_Z16 is selected, anti-aliasing 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

This function sets the format of pixels in the embedded frame buffer (EFB) internal to the graphics processor. It also controls the anti-aliasing (AA) mode.

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

When pix_fmt is GX_PF_RGB565_Z16, multi-sample anti-aliasing is enabled. In order to get the correct results, the GXSetCopyFilter function must also be called. The position of the subsamples and the anti-aliasing filter coefficients are set using the GXSetCopyFilter function. When anti-aliasing, 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 trade-offs 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, 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 anti-aliasing mode.

Since 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

2007/06/13 Added a note and included the description about stalling.
2006/03/01 Initial version.