GXInitSpecularDir

C Specification

#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 GXLoadLightObjImm or GXLoadLightObjIndx.

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.

Note: This function should be used if the light object is used as specular light. You can activate a channel for specular lighting by setting the GXAttnFn argument in GXSetChanCtrl to GX_AF_SPEC. Do not use the functions GXInitLightDir and GXInitLightPos to set up a light object to be used as a specular light. This is due to the fact that these functions will override data set by GXInitSpecularDir.

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