Parameter Access

Detailed Description

Functions
void	GlgIHChangeDParameter (GlgIH ih, char *name, double value)
	Changes a double value stored in a named parameter. More...
void	GlgIHChangeIParameter (GlgIH ih, char *name, GlgLong value)
	Changes an integer value stored in a named parameter. More...
void	GlgIHChangeOParameter (GlgIH ih, char *name, GlgObject value)
	Changes a GLG object ID stored in a named parameter. More...
void	GlgIHChangePParameter (GlgIH ih, char *name, void *value)
	Changes a pointer stored in a named parameter. More...
void	GlgIHChangeSParameter (GlgIH ih, char *name, char *value)
	Changes a string value stored in a named parameter. More...
double	GlgIHGetDParameter (GlgIH ih, char *name)
	Returns a double value stored in a named parameter. More...
GlgLong	GlgIHGetIParameter (GlgIH ih, char *name)
	Returns an integer value stored in a named parameter. More...
GlgObject	GlgIHGetOParameter (GlgIH ih, char *name)
	Returns a GLG object ID stored in a named parameter. More...
double	GlgIHGetOptDParameter (GlgIH ih, char *name, double default_value)
	Returns a double value stored in an optional named parameter. More...
GlgLong	GlgIHGetOptIParameter (GlgIH ih, char *name, GlgLong default_value)
	Returns an integer value stored in an optional named parameter. More...
GlgObject	GlgIHGetOptOParameter (GlgIH ih, char *name, GlgObject default_value)
	Returns a GLG object ID stored in an optional named parameter. More...
void *	GlgIHGetOptPParameter (GlgIH ih, char *name, void *default_value)
	Returns a pointer stored in an optional named parameter. More...
char *	GlgIHGetOptSParameter (GlgIH ih, char *name, char *default_value)
	Returns a string value stored in an optional named parameter. More...
void *	GlgIHGetPParameter (GlgIH ih, char *name)
	Returns a pointer stored in a named parameter. More...
char *	GlgIHGetSParameter (GlgIH ih, char *name)
	Returns a pointer stored in a named parameter. More...
void	GlgIHSetDParameter (GlgIH ih, char *name, double value)
	Creates and stores a named double parameter. More...
void	GlgIHSetIParameter (GlgIH ih, char *name, GlgLong value)
	Creates and stores a named integer parameter. More...
void	GlgIHSetOParameter (GlgIH ih, char *name, GlgObject value)
	Creates and stores a named parameter that keeps a GLG object ID. More...
void	GlgIHSetOParameterFromD (GlgIH ih, char *name, double value)
	Creates and stores a named double parameter that is stored as a GLG Data object of the GLG_D type. More...
void	GlgIHSetOParameterFromG (GlgIH ih, char *name, double value1, double value2, double value3)
	Creates and stores a named parameter that keeps X, Y and Z or R, G and B values stored as a GLG Data object of the GLG_G type. More...
void	GlgIHSetPParameter (GlgIH ih, char *name, void *value)
	Creates and stores a named pointer parameter. More...
void	GlgIHSetSParameter (GlgIH ih, char *name, char *value)
	Creates and stores a named string parameter. More...

Function Documentation

GlgIHChangeDParameter()

void GlgIHChangeDParameter	(	GlgIH	ih,
		char *	name,
		double	value
	)

Changes a double value stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to change a global parameter.
name	Parameter name.
value	New parameter value.

This function is similar to GlgIHSetDParameter, but instead of creating a new stored parameter, it changes the value of an existing stored parameter of the handler specified by the id.

If the stored parameter with the specified name does not exist, an error is generated.

GlgIHChangeIParameter()

void GlgIHChangeIParameter	(	GlgIH	ih,
		char *	name,
		GlgLong	value
	)

Changes an integer value stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to change a global parameter.
name	Parameter name.
value	New parameter value.

This function is similar to GlgIHSetIParameter, but instead of creating a new stored parameter, it changes the value of an existing stored parameter of the handler specified by the id.

If the stored parameter with the specified name does not exist, an error is generated.

GlgIHChangeOParameter()

void GlgIHChangeOParameter	(	GlgIH	ih,
		char *	name,
		GlgObject	value
	)

Changes a GLG object ID stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to change a global parameter.
name	Parameter name.
value	New parameter value.

This function is similar to GlgIHSetOParameter, but instead of creating a new stored parameter, it changes the value of an existing stored parameter of the handler specified by the id.

If the stored parameter with the specified name does not exist, an error is generated.

GlgIHChangePParameter()

void GlgIHChangePParameter	(	GlgIH	ih,
		char *	name,
		void *	value
	)

Changes a pointer stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to change a global parameter.
name	Parameter name.
value	New parameter value.

This function is similar to GlgIHSetIParameter, but instead of creating a new stored parameter, it changes the value of an existing stored parameter of the handler specified by the id.

If the stored parameter with the specified name does not exist, an error is generated.

GlgIHChangeSParameter()

void GlgIHChangeSParameter	(	GlgIH	ih,
		char *	name,
		char *	value
	)

Changes a string value stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to change a global parameter.
name	Parameter name.
value	New parameter value.

This function is similar to GlgIHSetSParameter, but instead of creating a new stored parameter, it changes the value of an existing stored parameter of the handler specified by the id.

If the stored parameter with the specified name does not exist, an error is generated.

GlgIHGetDParameter()

double GlgIHGetDParameter	(	GlgIH	ih,
		char *	name
	)

Returns a double value stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.

Returns

Parameter value.

An error is generated if a requested named parameter does not exist, or if its value cannot be converted to the requested return type.

GlgIHGetIParameter()

GlgLong GlgIHGetIParameter	(	GlgIH	ih,
		char *	name
	)

Returns an integer value stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.

Returns

Parameter value.

An error is generated if a requested named parameter does not exist, or if its value cannot be converted to the requested return type.

GlgIHGetOParameter()

GlgObject GlgIHGetOParameter	(	GlgIH	ih,
		char *	name
	)

Returns a GLG object ID stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.

Returns

Parameter value.

An error is generated if a requested named parameter does not exist.

GlgIHGetOptDParameter()

double GlgIHGetOptDParameter	(	GlgIH	ih,
		char *	name,
		double	default_value
	)

Returns a double value stored in an optional named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.
default_value	The default value that will be returned if the named parameter doesn't exist.

Returns

Parameter value or default value.

This function is the same as GlgIHGetDParameter, except that the named parameter is optional. If a stored parameter with the requested name does not exist, a default value provided by default_value is returned.

GlgIHGetOptIParameter()

GlgLong GlgIHGetOptIParameter	(	GlgIH	ih,
		char *	name,
		GlgLong	default_value
	)

Returns an integer value stored in an optional named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.
default_value	The default value that will be returned if the named parameter doesn't exist.

Returns

Parameter value or default value.

This function is the same as GlgIHGetIParameter, except that the named parameter is optional. If a stored parameter with the requested name does not exist, a default value provided by default_value is returned.

GlgIHGetOptOParameter()

GlgObject GlgIHGetOptOParameter	(	GlgIH	ih,
		char *	name,
		GlgObject	default_value
	)

Returns a GLG object ID stored in an optional named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.
default_value	The default value that will be returned if the named parameter doesn't exist.

Returns

Parameter value or default value.

This function is the same as GlgIHGetOParameter, except that the named parameter is optional. If a stored parameter with the requested name does not exist, a default value provided by default_value is returned.

GlgIHGetOptPParameter()

void* GlgIHGetOptPParameter	(	GlgIH	ih,
		char *	name,
		void *	default_value
	)

Returns a pointer stored in an optional named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.
default_value	The default value that will be returned if the named parameter doesn't exist.

Returns

Parameter value or default value.

This function is the same as GlgIHGetPParameter, except that the named parameter is optional. If a stored parameter with the requested name does not exist, a default value provided by default_value is returned.

GlgIHGetOptSParameter()

char* GlgIHGetOptSParameter	(	GlgIH	ih,
		char *	name,
		char *	default_value
	)

Returns a string value stored in an optional named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.
default_value	The default value that will be returned if the named parameter doesn't exist.

Returns

Parameter value or default value.

This function is the same as GlgIHGetSParameter, except that the named parameter is optional. If a stored parameter with the requested name does not exist, a default value provided by default_value is returned.

GlgIHGetPParameter()

void* GlgIHGetPParameter	(	GlgIH	ih,
		char *	name
	)

Returns a pointer stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.

Returns

Parameter value.

An error is generated if a requested named parameter does not exist.

GlgIHGetSParameter()

char* GlgIHGetSParameter	(	GlgIH	ih,
		char *	name
	)

Returns a pointer stored in a named parameter.

Parameters

ih	Handler ID, or GLG_IH_GLOBAL to query a global parameter.
name	Parameter name.

Returns

Parameter value.

An error is generated if a requested named parameter does not exist, or if its value cannot be converted to the requested return type.

GlgIHSetDParameter()

void GlgIHSetDParameter	(	GlgIH	ih,
		char *	name,
		double	value
	)

Creates and stores a named double parameter.

Parameters

ih	Handler ID.
name	Parameter name.
value	Parameter value.

The name argument specifies the name of the parameter; this name can be used to query the value of the parameter using GlgIHGetDParameter. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

See the Using IH Parameters section for information on how parameters are used.

GlgIHSetIParameter()

void GlgIHSetIParameter	(	GlgIH	ih,
		char *	name,
		GlgLong	value
	)

Creates and stores a named integer parameter.

Parameters

ih	Handler ID.
name	Parameter name.
value	Parameter value.

The name argument specifies the name of the parameter; this name can be used to query the value of the parameter using GlgIHGetIParameter. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

Using IH Parameters

A parameter is added to the data storage of the handler specified by the ih argument. The GLG_IH_CURR macro can be used to specify the currently active handler, which can eliminate the need to pass the ih handler ID into all functions the handler may invoke.

The GLG_IH_GLOBAL macro can be used to add parameters to the global data storage instead of the data storage of the current handler. When parameters are added, string parameters are cloned and object parameters are referenced.

When a handler is uninstalled, all parameters stored in its data storage are automatically cleaned: string parameters are freed and object parameters are dereferenced. If pointer parameters are used to store addresses of allocated memory, the memory should be freed, as shown in the following example:

case GLG_HI_SETUP_EVENT:
  ptr = GlgAlloc( sizeof my_struct );
  GlgIHSetPParameter( ih, "my_struct", ptr );
  break;
 
...
 
case GLG_CLEANUP_EVENT:
  ptr = GlgIHGetPParameter( "my_struct" );
  GlgFree( ptr );
  break;

GlgIHSetOParameter()

void GlgIHSetOParameter	(	GlgIH	ih,
		char *	name,
		GlgObject	value
	)

Creates and stores a named parameter that keeps a GLG object ID.

Parameters

ih	Handler ID.
name	Parameter name.
value	Parameter value.

The name argument specifies the name of the parameter; this name can be used to query the value of the parameter using GlgIHGetOParameter. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

The stored object is referenced and is dereferenced when the handler's data storage is destroyed on the GLG_CLEANUP_EVENT event.

See the Using IH Parameters section for information on how parameters are used.

GlgIHSetOParameterFromD()

void GlgIHSetOParameterFromD	(	GlgIH	ih,
		char *	name,
		double	value
	)

Creates and stores a named double parameter that is stored as a GLG Data object of the GLG_D type.

Parameters

ih	Handler ID.
name	Parameter name.
value	Parameter value.

The name argument specifies the name of the parameter; this name can be used to query parameter value using GlgIHGetDParameter, or to query the parameter's object ID using GlgIHGetOParameter. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

See the Using IH Parameters section for information on how parameters are used.

GlgIHSetOParameterFromG()

void GlgIHSetOParameterFromG	(	GlgIH	ih,
		char *	name,
		double	value1,
		double	value2,
		double	value3
	)

Creates and stores a named parameter that keeps X, Y and Z or R, G and B values stored as a GLG Data object of the GLG_G type.

Parameters

ih	Handler ID.
name	Parameter name.
value1,value2,value3	Parameter values.

The name argument specifies the name of the parameter; this name can be used to query the parameter's object ID using GlgIHGetOParameter. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

See the Using IH Parameters section for information on how parameters are used.

GlgIHSetPParameter()

void GlgIHSetPParameter	(	GlgIH	ih,
		char *	name,
		void *	value
	)

Creates and stores a named pointer parameter.

Parameters

ih	Handler ID.
name	Parameter name.
value	Parameter value.

The name argument specifies the name of the parameter; this name can be used to query the value of the parameter using GlgIHGetPParameter. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

It is an application's responsibility to allocate memory used by the stored pointer and free it when the handler's data storage is destroyed on the GLG_CLEANUP_EVENT event.

See the Using IH Parameters section for information on how parameters are used.

GlgIHSetSParameter()

void GlgIHSetSParameter	(	GlgIH	ih,
		char *	name,
		char *	value
	)

Creates and stores a named string parameter.

Parameters

ih	Handler ID.
name	Parameter name.
value	Parameter value.

The name argument specifies the name of the parameter; this name can be used to query the value of the parameter using GlgIHGetSParameter. If a parameter with the specified name already exists, it will be replaced, which can change the type of the parameter associated with the name.

A copy of the string is stored and is freed when the handler's data storage is destroyed on the GLG_CLEANUP_EVENT event.

See the Using IH Parameters section for information on how parameters are used.