quakeforge/tools/qflight/include/properties.h

205 lines
6.8 KiB
C
Raw Normal View History

/*
properties.c
Light properties handling.
Copyright (C) 2004 Bill Currie <bill@taniwha.org>
Author: Bill Currie <bill@taniwha.org>
Date: 2004/01/27
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to:
Free Software Foundation, Inc.
59 Temple Place - Suite 330
Boston, MA 02111-1307, USA
*/
2012-12-26 05:39:05 +00:00
#ifndef __properties_h
#define __properties_h
/** \defgroup qflight_properties Lighting properties
\ingroup qflight
*/
2020-02-11 06:20:49 +00:00
///@{
2012-12-26 05:39:05 +00:00
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 a vector from a string.
\param str The string holding the float.
\param vec The destination vector into which the vector values will
be written.
\bug No error checking is performed.
*/
void parse_vector (const char *str, vec3_t vec);
/** 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 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:
\arg \c sunlight see \ref parse_light
\arg \c sunlight2 see \ref parse_light
\arg \c sunlight3 see \ref parse_light
\arg \c sunlight_color see \ref parse_color
\arg \c sunlight_color2 see \ref parse_color
\arg \c sunlight_color3 see \ref parse_color
\arg \c sun_mangle see \ref parse_vector
\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_sun_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:
\arg \c 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 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);
2012-12-26 05:39:05 +00:00
2020-02-11 06:20:49 +00:00
///@}
2012-12-26 05:39:05 +00:00
#endif//__properties_h