Configure dynamic light, shading, and shadows. More...

#include "lightlut.h"
#include "maths.h"

Data Structures
struct	C3D_Material
	Material. More...

struct	C3D_LightLutInputConf

struct	C3D_LightEnvConf

struct	C3D_LightEnv_t

struct	C3D_LightMatConf

struct	C3D_LightConf

struct	C3D_Light_t

Macros
#define	C3DF_LightEnv_IsCP(n) BIT(18+(n))

#define	C3DF_LightEnv_IsCP_Any (0xFF<<18)

#define	C3DF_LightEnv_LutDirty(n) BIT(26+(n))

#define	C3DF_LightEnv_LutDirtyAll (0x3F<<26)

Light Environment
enum	{ C3DF_LightEnv_Dirty = BIT(0) , C3DF_LightEnv_MtlDirty = BIT(1) , C3DF_LightEnv_LCDirty = BIT(2) }

enum	{ GPU_SHADOW_PRIMARY = BIT(16) , GPU_SHADOW_SECONDARY = BIT(17) , GPU_INVERT_SHADOW = BIT(18) , GPU_SHADOW_ALPHA = BIT(19) }

typedef struct C3D_Light_t	C3D_Light

typedef struct C3D_LightEnv_t	C3D_LightEnv

void	C3D_LightEnvInit (C3D_LightEnv *env)
	Resets and initializes C3D_LightEnv structure to default values.

void	C3D_LightEnvBind (C3D_LightEnv *env)
	Binds C3D_LightEnv pointer to be used for configuring internal state.

void	C3D_LightEnvMaterial (C3D_LightEnv env, const C3D_Material mtl)
	Coppies material properties to C3D_LightEnv.

void	C3D_LightEnvAmbient (C3D_LightEnv *env, float r, float g, float b)
	Sets global ambient lighting.

void	C3D_LightEnvLut (C3D_LightEnv env, GPU_LIGHTLUTID lutId, GPU_LIGHTLUTINPUT input, bool negative, C3D_LightLut lut)
	Uploads pre-calculated lighting lookup table for specified function.

void	C3D_LightEnvFresnel (C3D_LightEnv *env, GPU_FRESNELSEL selector)
	Enables or disables writing fresnel and shadow alpha component to GPU_FRAGMENT_PRIMARY_COLOR and GPU_FRAGMENT_SECONDARY_COLOR.

void	C3D_LightEnvBumpMode (C3D_LightEnv *env, GPU_BUMPMODE mode)
	Configures bump map texture properties.

void	C3D_LightEnvBumpSel (C3D_LightEnv *env, int texUnit)
	Configures bump map texture unit id.

void	C3D_LightEnvBumpNormalZ (C3D_LightEnv *env, bool enable)
	Configures whether to use the z component of the normal map.

void	C3D_LightEnvShadowMode (C3D_LightEnv *env, u32 mode)
	Configures shadow mapping behavior.

void	C3D_LightEnvShadowSel (C3D_LightEnv *env, int texUnit)
	Configures shadow mapping texture.

void	C3D_LightEnvClampHighlights (C3D_LightEnv *env, bool clamp)
	Enables or disables clamping specular highlights.

Light
enum	{ C3DF_Light_Enabled = BIT(0) , C3DF_Light_Dirty = BIT(1) , C3DF_Light_MatDirty = BIT(2) , C3DF_Light_SPDirty = BIT(14) , C3DF_Light_DADirty = BIT(15) }

int	C3D_LightInit (C3D_Light light, C3D_LightEnv env)
	Adds light to C3D_LightEnv.

void	C3D_LightEnable (C3D_Light *light, bool enable)
	Enables or disables light source.

void	C3D_LightTwoSideDiffuse (C3D_Light *light, bool enable)
	Enables or disables light source.

void	C3D_LightGeoFactor (C3D_Light *light, int id, bool enable)
	Enables or disables cock-torrance geometric factor.

void	C3D_LightAmbient (C3D_Light *light, float r, float g, float b)
	Configures global ambient color emitted by light source.

void	C3D_LightDiffuse (C3D_Light *light, float r, float g, float b)
	Configures diffuse lighting color emitted by light source.

void	C3D_LightSpecular0 (C3D_Light *light, float r, float g, float b)
	Configures specular0 lighting color emitted by light source.

void	C3D_LightSpecular1 (C3D_Light *light, float r, float g, float b)
	Configures specular1 lighting color emitted by light source.

void	C3D_LightPosition (C3D_Light light, C3D_FVec pos)
	Configures light position vector.

void	C3D_LightShadowEnable (C3D_Light *light, bool enable)
	Enables or disables shadow mapping on light source.

void	C3D_LightSpotEnable (C3D_Light *light, bool enable)
	Enables or disables spot light for specified light source.

void	C3D_LightSpotDir (C3D_Light *light, float x, float y, float z)
	Configures spot light direction vector for specified light source.

void	C3D_LightSpotLut (C3D_Light light, C3D_LightLut lut)
	Configures spotlight lookup table.

void	C3D_LightDistAttnEnable (C3D_Light *light, bool enable)
	Enables or disables distance attenuation for specified light source.

void	C3D_LightDistAttn (C3D_Light light, C3D_LightLutDA lut)
	Uploads pre-calculated distance attenuation lookup table for specified light source.

static void	C3D_LightColor (C3D_Light *light, float r, float g, float b)
	Configures diffuse and specular0/1 color emitted by light source.

Detailed Description

Configure dynamic light, shading, and shadows.

Fragment Light Equations

The equations used for calculating fragment lighting appears to be as follows:

\[ C_{pri} = s^{(a)} + \sum_{i = 0}^{\#lights} a * SpotlightLut(d_0) * o * (l_i^{(d)} * f_i(L_i \cdot N) + l_i^{(a)}) \]

\[ C_{sec} = \sum_{i = 0}^{\#lights} a * SpotlightLut(d_0) * h * o * (l_i^{(s_0)}LutD_0(d_1)*G_i^{(0)} + l_i^{(s_1)}LutD_1(d_3)*G_i^{(1)}*ReflectionLutsRGB(d_2)) \]

\[ C_{alpha} = FresnelLut(d_4) \]

Outputs:

\(C_{pri}\) - GPU_FRAGMENT_PRIMARY_COLOR
\(C_{sec}\) - GPU_FRAGMENT_SECONDARY_COLOR
\(C_{alpha}\) - Primary and/or secondary alpha. Output is selectable using C3D_LightEnvFresnel().

Inputs, per-fragment:

\(a\) - Distance attenuation factor calculated from distance attenuation LUT.
\(N\) - Interpolated normal
\(V\) - View direction vector (fragment <-> camera)
\(T\) - Tangent direction vector

Inputs, per-pass:

\(d_{0...4}\) - Configurable LUT inputs - one of the following: \(N \cdot H\), \(V \cdot H_i\), \(N \cdot V\), \(L_i \cdot N\), \(-L_i \cdot P\), \(\cos \phi_i\).
\(s^{(a)}\) - Scene ambient color
\(o\) - Shadow attenuation from the shadow map (if there is one). Output is selectable using C3D_LightEnvShadowMode().
\(h\) - Clamps lighting for \(N \cdot L_i < 0\) if C3D_LightEnvClampHighlights() is enabled

Inputs, per-Light:

\(P_i\) - Spotlight direction
\(L_i\) - Light vector (just lightPosition when positional lighting is enabled, lightPosition + view when directional lighting is enabled)
\(H_i\) - Half-vector between \(L_i\) and \(V\)
\(\phi_i\) - Angle between the projection of \(H_i\) into the tangent plane and \(T\)
\(f_i\) - Clamps product of \(N \cdot L_i\) to zero if C3D_LightTwoSideDiffuse() is disabled for the light source, otherwise gets the absolute value
\(l_i^{(a)}\) - Light ambient color
\(l_i^{(d)}\) - Light diffuse color
\(l_i^{(s_0)}\) - Light specular0 color
\(l_i^{(s_1)}\) - Light specular1 color
\(G_i^{(0)},G_i^{(1)}\) - Cook-Torrance geometric factor, or 1 when disabled

In citro3d, some inputs may be configured by multiple variables, for example:

\(s^{(a)}\) = mtl.emission + mtl.ambient * env.ambient
\(l_i^{(a)}\) = mtl.ambient * light.ambient
\(l_i^{(d)}\) = mtl.diffuse * light.diffuse
\(l_i^{(s_0)}\) = mtl.specular0 * light.specular0
\(l_i^{(s_1)}\) = mtl.specular1 * light.specular1

See also: https://github.com/PabloMK7/citra/blob/baca2bfc6bd0af97ce74b911d69af2391815c9d7/src/video_core/renderer_software/sw_lighting.cpp#L26-L332

Function Documentation

◆ C3D_LightAmbient()

void C3D_LightAmbient	(	C3D_Light *	light,
		float	r,
		float	g,
		float	b
	)

Configures global ambient color emitted by light source.

Parameters

[out]	light	Light source structure.
[in]	r	Red component.
[in]	g	Green component.
[in]	b	Blue component.

◆ C3D_LightColor()

static void C3D_LightColor	(	C3D_Light *	light,
		float	r,
		float	g,
		float	b
	)

inlinestatic

Configures diffuse and specular0/1 color emitted by light source.

Parameters

[out]	light	Light source structure.
[in]	r	Red component.
[in]	g	Green component.
[in]	b	Blue component.

◆ C3D_LightDiffuse()

void C3D_LightDiffuse	(	C3D_Light *	light,
		float	r,
		float	g,
		float	b
	)

Configures diffuse lighting color emitted by light source.

Parameters

[out]	light	Light source structure.
[in]	r	Red component.
[in]	g	Green component.
[in]	b	Blue component.

◆ C3D_LightDistAttn()

void C3D_LightDistAttn	(	C3D_Light *	light,
		C3D_LightLutDA *	lut
	)

Uploads pre-calculated distance attenuation lookup table for specified light source.

Parameters

[out]	light	Light source structure.
[in]	lut	Pointer to pre-computed distance attenuation lookup table.

◆ C3D_LightDistAttnEnable()

void C3D_LightDistAttnEnable	(	C3D_Light *	light,
		bool	enable
	)

Enables or disables distance attenuation for specified light source.

Parameters

[out]	light	Light source structure.
[in]	enable	Enable distance attenuation factor for light source.

◆ C3D_LightEnable()

void C3D_LightEnable	(	C3D_Light *	light,
		bool	enable
	)

Enables or disables light source.

Note: At least one light source must be enabled at all times. Disabling all light sources will result in undefined behavior.

Parameters

[out]	light	Light source structure.
[in]	enable	true to enable light source, false to disable light source.

◆ C3D_LightEnvAmbient()

void C3D_LightEnvAmbient	(	C3D_LightEnv *	env,
		float	r,
		float	g,
		float	b
	)

Sets global ambient lighting.

Parameters

[out]	env	Pointer to light environment structure.
[in]	r	Red component.
[in]	g	Green component.
[in]	b	Blue component.

◆ C3D_LightEnvBind()

void C3D_LightEnvBind ( C3D_LightEnv * env )

Binds C3D_LightEnv pointer to be used for configuring internal state.

Parameters

[in] env Pointer to light environment structure or NULL to disable the fragment lighting stage altogether.

◆ C3D_LightEnvBumpMode()

void C3D_LightEnvBumpMode	(	C3D_LightEnv *	env,
		GPU_BUMPMODE	mode
	)

Configures bump map texture properties.

Parameters

[out]	env	Pointer to light environment structure.
[in]	mode	Bump map type. Use GPU_BUMP_AS_BUMP to specify normal map, use GPU_BUMP_AS_TANG to specify tangent map, or use GPU_BUMP_NOT_USED to disable bump mapping.

See also: C3D_LightEnvBumpSel()

◆ C3D_LightEnvBumpNormalZ()

void C3D_LightEnvBumpNormalZ	(	C3D_LightEnv *	env,
		bool	enable
	)

Configures whether to use the z component of the normal map.

Parameters

[out]	env	Pointer to light environment structure.
[in]	enable	true enables using the z component from the normal map, false enables z component reconstruction from the xy components of the normal map.

◆ C3D_LightEnvBumpSel()

void C3D_LightEnvBumpSel	(	C3D_LightEnv *	env,
		int	texUnit
	)

Configures bump map texture unit id.

Parameters

[out]	env	Pointer to light environment structure.
[in]	texUnit	Id of texture unit the bump texture is bound to (IDs 0 through 2).

See also: C3D_LightEnvBumpMode(); C3D_TexBind()

◆ C3D_LightEnvClampHighlights()

void C3D_LightEnvClampHighlights	(	C3D_LightEnv *	env,
		bool	clamp
	)

Enables or disables clamping specular highlights.

Parameters

[out]	env	Pointer to light environment structure.
[in]	clamp	true to enable clamping specular highlights based on the normal vector, false to disable clamping specular highlights.

◆ C3D_LightEnvFresnel()

void C3D_LightEnvFresnel	(	C3D_LightEnv *	env,
		GPU_FRESNELSEL	selector
	)

Enables or disables writing fresnel and shadow alpha component to GPU_FRAGMENT_PRIMARY_COLOR and GPU_FRAGMENT_SECONDARY_COLOR.

Parameters

[out]	env	Light environment.
[in]	selector	Output selector, or GPU_NO_FRESNEL to disable writing the alpha component to both GPU_FRAGMENT_PRIMARY_COLOR and GPU_FRAGMENT_SECONDARY_COLOR.

See also: Fragment Light Equations

◆ C3D_LightEnvInit()

void C3D_LightEnvInit ( C3D_LightEnv * env )

Resets and initializes C3D_LightEnv structure to default values.

Note: Using fragment lighting without at least one light source configured and enabled may result in undefined behavior.

Parameters

[out] env Pointer to light environment structure.

Returns: Light id on success, negative on failure.

See also: C3D_LightInit(); Fragment Light Equations

◆ C3D_LightEnvLut()

void C3D_LightEnvLut	(	C3D_LightEnv *	env,
		GPU_LIGHTLUTID	lutId,
		GPU_LIGHTLUTINPUT	input,
		bool	negative,
		C3D_LightLut *	lut
	)

Uploads pre-calculated lighting lookup table for specified function.

Note: For the full lighting equation see the Fragment Light Equations section. This is used to calculate the values of GPU_FRAGMENT_PRIMARY_COLOR and GPU_FRAGMENT_SECONDARY_COLOR.

Parameters

[out]	env	Pointer to light environment structure.
[in]	lutId	Specify function of the lookup table.
[in]	input	Specify arguments of the function.
[in]	negative	If true, the LUT inputs can be read as positive or negative, if false the absolute value of the lut inputs will be used.
[in]	lut	Pointer to pre-computed lookup table, or NULL to disable the function.

See also: LightLut_FromArray(); LightLut_FromFunc()

◆ C3D_LightEnvMaterial()

void C3D_LightEnvMaterial	(	C3D_LightEnv *	env,
		const C3D_Material *	mtl
	)

Coppies material properties to C3D_LightEnv.

Parameters

[out]	env	Pointer to light environment structure.
[in]	mtl	Pointer to material properties structure.

◆ C3D_LightEnvShadowMode()

void C3D_LightEnvShadowMode	(	C3D_LightEnv *	env,
		u32	mode
	)

Configures shadow mapping behavior.

Parameters

[out]	env	Pointer to light environment structure.
[in]	mode	One or more of the following bitflags, GPU_SHADOW_PRIMARY, GPU_SHADOW_SECONDARY, GPU_INVERT_SHADOW, and GPU_SHADOW_ALPHA.

◆ C3D_LightEnvShadowSel()

void C3D_LightEnvShadowSel	(	C3D_LightEnv *	env,
		int	texUnit
	)

Configures shadow mapping texture.

Note: Shadow depth textures must be assigned to texture unit 0.

Parameters

[out]	env	Pointer to light environment structure.
[in]	texUnit	Id of texture unit the shadow texture is bound to (IDs 0 through 2).

◆ C3D_LightGeoFactor()

void C3D_LightGeoFactor	(	C3D_Light *	light,
		int	id,
		bool	enable
	)

Enables or disables cock-torrance geometric factor.

Parameters

[out]	light	Light source structure.
[in]	id	Geometric factor id. (0 or 1)
[in]	enable	true to enable geometric factor id, false to disable it.

◆ C3D_LightInit()

int C3D_LightInit	(	C3D_Light *	light,
		C3D_LightEnv *	env
	)

Adds light to C3D_LightEnv.

Note: Only 8 lights can be configured simultaneously.

Parameters

[in]	light	Light struct to add to light environment.
[out]	env	Light environment.

Returns: Light id on success, negative on failure.

See also: Fragment Light Equations

◆ C3D_LightPosition()

void C3D_LightPosition	(	C3D_Light *	light,
		C3D_FVec *	pos
	)

Configures light position vector.

Note: The w-component of the position vector is a flag where 0 specifies positional lighting and any other value specifies directional lighting.

Parameters

[out]	light	Light source structure.
[in]	pos	Position vector.

◆ C3D_LightShadowEnable()

void C3D_LightShadowEnable	(	C3D_Light *	light,
		bool	enable
	)

Enables or disables shadow mapping on light source.

Note: The shadow mapping texture can be specified using C3D_LightEnvShadowSel().

Parameters

[out]	light	Light source structure.
[in]	enable	true to enable shadow mapping, false to disable shadow mapping.

◆ C3D_LightSpecular0()

void C3D_LightSpecular0	(	C3D_Light *	light,
		float	r,
		float	g,
		float	b
	)

Configures specular0 lighting color emitted by light source.

Parameters

[out]	light	Light source structure.
[in]	r	Red component.
[in]	g	Green component.
[in]	b	Blue component.

◆ C3D_LightSpecular1()

void C3D_LightSpecular1	(	C3D_Light *	light,
		float	r,
		float	g,
		float	b
	)

Configures specular1 lighting color emitted by light source.

Parameters

[out]	light	Light source structure.
[in]	r	Red component.
[in]	g	Green component.
[in]	b	Blue component.

◆ C3D_LightSpotDir()

void C3D_LightSpotDir	(	C3D_Light *	light,
		float	x,
		float	y,
		float	z
	)

Configures spot light direction vector for specified light source.

Parameters

[out]	light	Light source structure.
[in]	x	X component.
[in]	y	Y component.
[in]	z	Z component.

◆ C3D_LightSpotEnable()

void C3D_LightSpotEnable	(	C3D_Light *	light,
		bool	enable
	)

Enables or disables spot light for specified light source.

Parameters

[out]	light	Light source structure.
[in]	enable	true to enable spot light, false to disable spot light.

◆ C3D_LightSpotLut()

void C3D_LightSpotLut	(	C3D_Light *	light,
		C3D_LightLut *	lut
	)

Configures spotlight lookup table.

Parameters

[out]	light	Light source structure.
[in]	lut	Pointer to pre-computed lighting lookup table.

◆ C3D_LightTwoSideDiffuse()

void C3D_LightTwoSideDiffuse	(	C3D_Light *	light,
		bool	enable
	)

Enables or disables light source.

Parameters

[out]	light	Light source structure.
[in]	enable	true to enable two sided lighting (illuminates both the inside and outside of a mesh), false to disable two sided lighting.

Data Structures

Macros

Light Environment

Light

Detailed Description

Fragment Light Equations

Function Documentation

◆ C3D_LightAmbient()

◆ C3D_LightColor()

◆ C3D_LightDiffuse()

◆ C3D_LightDistAttn()

◆ C3D_LightDistAttnEnable()

◆ C3D_LightEnable()

◆ C3D_LightEnvAmbient()

◆ C3D_LightEnvBind()

◆ C3D_LightEnvBumpMode()

◆ C3D_LightEnvBumpNormalZ()

◆ C3D_LightEnvBumpSel()

◆ C3D_LightEnvClampHighlights()

◆ C3D_LightEnvFresnel()

◆ C3D_LightEnvInit()

◆ C3D_LightEnvLut()

◆ C3D_LightEnvMaterial()

◆ C3D_LightEnvShadowMode()

◆ C3D_LightEnvShadowSel()

◆ C3D_LightGeoFactor()

◆ C3D_LightInit()

◆ C3D_LightPosition()

◆ C3D_LightShadowEnable()

◆ C3D_LightSpecular0()

◆ C3D_LightSpecular1()

◆ C3D_LightSpotDir()

◆ C3D_LightSpotEnable()

◆ C3D_LightSpotLut()

◆ C3D_LightTwoSideDiffuse()