GXInitSpecularDir

Syntax

#include <revolution/gx.h>

void GXInitSpecularDir(
    GXLightObj* lt_obj,
    f32         nx,
    f32         ny,
    f32         nz );

Arguments

lt_obj	Pointer to a light object.
nx	X coordinate for the light direction.
ny	Y coordinate for the light direction.
nz	Z coordinate for the light direction

Return Values

None.

Description

This function sets the direction of a specular light for a light object. This direction is used when the light object is used as specular light. The application must allocate the memory for the light object; this function does not load any hardware registers. To load a light object into a hardware light, use the GXLoadLightObjImm or GXLoadLightObjIndx function.

The coordinate space of the light direction should be consistent with a vertex normal transformed by a normal matrix. In other words, it should be transformed to view space. The direction vector must be normalized.

The half-angle vector, necessary for specular lighting, is automatically calculated from the input light direction (nx, ny, nz) by assuming the view vector as (0, 0, 1). If you specify the direction vector as (0, 0, 1), the half-angle vector becomes zero (no lighting effect) because the two vector directions are identical.

When Light objects are being used for specular light, you can specify specular lighting in the GXSetChanCtrl function by setting GXAttnFn to GX_AF_SPEC. Then use the GXInitSpecularDir function to specify the Light objects that you plan to use for specular lighting.

Note: Do not call the GXInitLightDir function or the GXInitLightPos function after Light objects have been specified with the GXInitSpecularDir function. These functions overwrite any information configured by the GXInitSpecularDir function.
The GXInitSpecularDir function adds necessary computation procedures when specular light is used in the GXInitLightDir function. There is no inherent problem setting this up using the GXInitLightDir and GXInitLightPos functions. If you plan to use them, however, be sure to configure the settings correctly and remember that the light being used is specular light.

In contrast to diffuse lights (including spotlights) that are considered local lights, a specular light is a parallel light (i.e., the specular light is infinitely far away such that all rays of the light are parallel); only directional information can be specified. If you use a light object which is set by this function for diffuse light, it acts as a (pseudo) parallel diffuse light.

Revision History

2009/05/13 Added Note to Description.
2006/03/01 Initial version.