Name

cgSetParameterSettingMode - set the parameter setting mode for a context

Synopsis

#include <Cg/cg.h>

void cgSetParameterSettingMode( CGcontext context,
                                CGenum parameterSettingMode );

Parameters

context

The context in which to set the parameter setting mode.

parameterSettingMode

The mode to which context will be set. Must be one of the following :

• CG_IMMEDIATE_PARAMETER_SETTING
• CG_DEFERRED_PARAMETER_SETTING

Return Values

None.

Description

cgSetParameterSettingMode controls the behavior of the context when setting parameters. With deferred parameter setting, the corresponding 3D API parameter is not immediately updated by cgSetParameter commands. If the application does not need to access these 3D API parameter values, then this mode allows improved performance by avoiding unnecessary 3D API calls.

Parameters of variability CG_VARYING are never deferred.

When the parameter setting mode is CG_DEFERRED_PARAMETER_SETTING, non-erroneous cgSetParameter commands record the updated parameter value but do not immediately update the corresponding 3D API parameter. Instead the parameter is marked internally as update deferred. The 3D API commands required to update any program parameters marked update deferred are performed as part of the next program bind (see cgGLBindProgram or cgD3D9BindProgram).

If a context's parameter setting mode was CG_DEFERRED_PARAMETER_SETTING and one or more parameters are marked update deferred, changing the parameter setting mode to CG_IMMEDIATE_PARAMETER_SETTING does not cause parameters marked update deferred to be updated. The application can use cgUpdateProgramParameters or cgUpdatePassParameters to force the updating of parameters marked update deferred.

parameterSettingMode must be one of the following enumerants :

CG_IMMEDIATE_PARAMETER_SETTING

Non-erroneous cgSetParameter commands immediately update the corresponding 3D API parameter. This is the default mode.

CG_DEFERRED_PARAMETER_SETTING

Non-erroneous cgSetParameter commands record the updated parameter value but do not immediately update the corresponding 3D API parameter. These updates will happen during the next program bind. The updates can be explicitly forced to occur by using cgUpdateProgramParameters or cgUpdatePassParameters.

Examples

Change context to use deferred parameter updates:

  cgSetParameterSettingMode(myCgContext, CG_DEFERRED_PARAMETER_SETTING);

Change context to its initial behavior of performing parameter updates immediately:

  cgSetParameterSettingMode(myCgContext, CG_IMMEDIATE_PARAMETER_SETTING);

Errors

CG_INVALID_CONTEXT_HANDLE_ERROR is generated if context is not a valid context.

CG_INVALID_ENUMERANT_ERROR is generated if parameterSettingMode is not CG_IMMEDIATE_PARAMETER_SETTING or CG_DEFERRED_PARAMETER_SETTING.

History

cgSetParameterSettingMode was introduced in Cg 2.0.

See Also

cgGetParameterSettingMode, cgUpdateProgramParameters, cgUpdatePassParameters, cgSetParameter, cgSetParameterVariability, cgGetParameterVariability, cgGLBindProgram, cgD3D9BindProgram