Move the properties docs into properties.h

tools/qflight/include/properties.h

@@ -37,13 +37,131 @@
 
 struct plitem_s;
 
+/** Parse a float from a string.
+
+	\param str		The string holding the float.
+	\return			The floating point value parsed from the string.
+
+	\bug			No error checking is performed.
+*/
 float parse_float (const char *str);
+
+/** 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.
+
+	\param str		The string holding the RGB color vector.
+	\param 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])
+*/
 void parse_color (const char *str, vec3_t color);
+
+/** Parse a light intensity/color specification.
+
+	There are three possible specification formats:
+	\arg 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.
+	\arg RGB		"R B B" where R G & B are left as-is and the intensity
+					is set to 1.0.
+	\arg id			Standard quake single value light intensity. The color
+					is set to white ([1.0 1.0 1.0]).
+
+	\param str		The string holding the light specification.
+	\param color	The destination vector into which the RGB values will
+					be written.
+	\return			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.
+*/
 float parse_light (const char *str, vec3_t color);
+
+/** Parse the light attenuation style from a string.
+
+	Valid attenuations:
+	\arg \c linear		id style. The light level falls off linearly from
+						"light" at 0 to 0 at distance "light".
+	\arg \c radius		Similar to linear, but the cut-off distance is at
+						"radius"
+	\arg \c inverse		1/r attenuation
+	\arg \c realistic	1/(r*r) (inverse-square) attenuation
+	\arg \c none		No attenuation. The level is always "light".
+	\arg \c havoc		Like realistic, but with a cut-off (FIXME, math?)
+
+	\param arg		The string holding the attenuation style.
+	\return 		The parsed attenuation style value, or -1 if ivalid.
+*/
 int parse_attenuation (const char *arg);
+
+/** Parse the light's noise type from a string.
+
+	Valid noise types:
+	\arg \c random	completely random noise (default)
+	\arg \c smooth	low res noise with interpolation
+	\arg \c perlin	combines several noise frequencies (Perlin noise).
+	\return 		The parsed noise type value, or -1 if ivalid.
+*/
 int parse_noise (const char *arg);
+
+/** 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:
+	\arg \c light/_light	see \ref parse_light
+	\arg \c style			light style: 0-254
+	\arg \c angle			spotlight con angle in degress. defaults to 20
+	\arg \c wait			light "falloff". defaults to 1.0
+	\arg \c _lightradius	size of light. interacts with falloff for
+							distance clipping (?). defaults to 0
+	\arg \c color/_color	see \ref parse_color
+	\arg \c _attenuation	see \ref parse_attenuation
+	\arg \c _radius			the range of the light.
+	\arg \c _noise			noise intensity (?)
+	\arg \c _noisetype		see \ref parse_noise
+	\arg \c _persistence	noise parameter
+	\arg \c _resolution		noise parameter
+
+	\param ent		The entity for which to set the lighting values.
+	\param dict		A dictionary property list item representing the fields
+					of the entity. Values specified in \a dict will override
+					those specified in the database.
+*/
 void set_properties (entity_t *ent, struct plitem_s *dict);
 
+/** Load the lighting properties database from the specified file.
+
+	The lighting properties database is a \ref 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 \ref set_properties), and all values must be strings.
+
+	\param filename	The path to the lighting properties database.
+*/
 void LoadProperties (const char *filename);
 
 //@}

tools/qflight/source/properties.txt

@@ -1,37 +0,0 @@
-light/_light *
-	halflife: "r g b i", r/g/b 0-255, i is id "light"
-	rgb: "r g b"
-	id: "intensity"
-style *
-	light style: 0-254
-angle *
-	spotlight cone angle in degrees. defaults to 20
-wait
-	light "falloff". defaults to 1.0
-_lightradius
-	size of light. interacts with falloff for distance clipping (?)
-	defaults to 0
-color/_color
-	"r g b", r/g/b 0-1.0
-_attenuation
-	attenuation style:
-		linear		id style. level falls off linearly from "light" at 0 to
-					0 at distance "light".
-		radius		similar to linear, but the cutoff distance is at "radius"
-		inverse		1/r attenuation
-		realistic	1/(r*r) (inverse-square) attenuation
-		none		no attenuation, level is always "light"
-		havoc		like realistic, but with a cutoff.
-_radius
-	the range of the light.
-_noise
-	noise intensity (?)
-_noisetype
-	noise type:
-		random
-		smooth
-		perlin
-_persistence
-	noise parameter
-_resolution
-	noise parameter