Lighting properties

Functions
void	LoadProperties (const char *filename)
	Load the lighting properties database from the specified file. More...
int	parse_attenuation (const char *arg)
	Parse the light attenuation style from a string. More...
void	parse_color (const char *str, vec3_t color)
	Parse an RGB color vector from a string. More...
float	parse_float (const char *str)
	Parse a float from a string. More...
float	parse_light (const char *str, vec3_t color)
	Parse a light intensity/color specification. More...
int	parse_noise (const char *arg)
	Parse the light's noise type from a string. More...
void	parse_vector (const char *str, vec3_t vec)
	Parse a vector from a string. More...
void	set_properties (entity_t *ent, struct plitem_s *dict)
	Set the light entity's lighting values based on its fields and the loaded lighting properties database. More...
void	set_sun_properties (entity_t *ent, struct plitem_s *dict)
	Set the world entity's sun values based on its fields and the loaded lighting properties database. More...

Detailed Description

Function Documentation

void LoadProperties

(

const char *

filename

)

Load the lighting properties database from the specified file.

The lighting properties database is a Property List. The property list must be a dictionary of dictionaries. The outer dictionary is keyed by the light entity's _light_name field or classname field (_light_name overrides classname so lights of the same class can have different properties). If a "default" key is provided, that will be used as default settings for all lights that don't find an entry via _light_name or classname.

The inner dictionary is keyed by the fields of the entity (see set_properties), and all values must be strings.

Parameters

filename

The path to the lighting properties database.

int parse_attenuation

(

const char *

arg

)

Parse the light attenuation style from a string.

Valid attenuations:

• linear id style. The light level falls off linearly from "light" at 0 to 0 at distance "light".
• radius Similar to linear, but the cut-off distance is at "radius"
• inverse 1/r attenuation
• realistic 1/(r*r) (inverse-square) attenuation
• none No attenuation. The level is always "light".
• havoc Like realistic, but with a cut-off (FIXME, math?)

Parameters

arg	The string holding the attenuation style.

Returns

The parsed attenuation style value, or -1 if ivalid.

void parse_color	(	const char *	str,
		vec3_t	color
	)

Parse an RGB color vector from a string.

The RGB values are normalized such that the magnitude of the largest component is 1.0. The signs of all components are preserved.

Parameters

str	The string holding the RGB color vector.
color	The destination vector into which the RGB values will be written.

Note

If any error occurs while parsing the RGB values, the resulting color will be white ([1.0 1.0 1.0])

float parse_float

(

const char *

str

)

Parse a float from a string.

Parameters

str	The string holding the float.

Returns

The floating point value parsed from the string.

Bug:

No error checking is performed.

float parse_light	(	const char *	str,
		vec3_t	color
	)

Parse a light intensity/color specification.

There are three possible specification formats:

• HalfLife "R G B i" where R G & B are 0-255 and i is the same as for normal id lights. The RGB values will be scaled by 1/255 such that 255 becomes 1.0.
• RGB "R B B" where R G & B are left as-is and the intensity is set to 1.0.
• id Standard quake single value light intensity. The color is set to white ([1.0 1.0 1.0]).

Parameters

str	The string holding the light specification.
color	The destination vector into which the RGB values will be written.

Returns

The intensity of the light.

Note

If any error occurs while parsing the specification, the resulting color will be while ([1.0 1.0 1.0]) and the intensity will be DEFAULTLIGHTLEVEL.

int parse_noise

(

const char *

arg

)

Parse the light's noise type from a string.

Valid noise types:

• random completely random noise (default)
• smooth low res noise with interpolation
• perlin combines several noise frequencies (Perlin noise).

  Returns

  The parsed noise type value, or -1 if ivalid.

void parse_vector	(	const char *	str,
		vec3_t	vec
	)

Parse a vector from a string.

Parameters

str	The string holding the float.
vec	The destination vector into which the vector values will be written.

Bug:

No error checking is performed.

void set_properties	(	entity_t *	ent,
		struct plitem_s *	dict
	)

Set the light entity's lighting values based on its fields and the loaded lighting properties database.

The database is loaded via LoadProperties().

If the entity has a key named "_light_name", then the value will be used to select a set of default properties from the database.

Should that fail (either no "_light_name" key, or no properties with the given name), then the entity's classname is used.

Should that fail, the set of properties named "default" will be used.

If no set of properties can be found in the database, then the database will be ignored.

Supported properties:

• light see parse_light
• style light style: 0-254
• angle spotlight con angle in degress. defaults to 20
• wait light "falloff". defaults to 1.0
• lightradius size of light. interacts with falloff for distance clipping (?). defaults to 0
• color see parse_color
• attenuation see parse_attenuation
• radius the range of the light.
• noise noise intensity (?)
• noisetype see parse_noise
• persistence noise parameter
• resolution noise parameter

Parameters

ent	The entity for which to set the lighting values.
dict	A dictionary property list item representing the fields of the entity. Values specified in dict will override those specified in the database.

void set_sun_properties	(	entity_t *	ent,
		struct plitem_s *	dict
	)

Set the world entity's sun values based on its fields and the loaded lighting properties database.

The database is loaded via LoadProperties().

If a set of properties named "worldspawn" is in the database, the it will be used for default values, otherwise the database will be ignored.

Supported properties:

• sunlight see parse_light
• sunlight2 see parse_light
• sunlight3 see parse_light
• sunlight_color see parse_color
• sunlight_color2 see parse_color
• sunlight_color3 see parse_color
• sun_mangle see parse_vector

Parameters

ent	The entity for which to set the lighting values.
dict	A dictionary property list item representing the fields of the entity. Values specified in dict will override those specified in the database.