Name

cgSetContextBehavior - set the behavior for a context

Synopsis

#include <Cg/cg.h>

void cgSetContextBehavior( CGcontext context,
                           CGbehavior behavior );

Parameters

context

The context for which the behavior will be set.

behavior

An enumerant which defines the behavior that will be exhibited by context. The following enumerants are allowed:

• CG_BEHAVIOR_3100
• CG_BEHAVIOR_3000
• CG_BEHAVIOR_2200
• CG_BEHAVIOR_CURRENT
• CG_BEHAVIOR_LATEST

Return Values

None.

Description

Each new version of Cg is supposed to be completely backwards compatible with previous versions, providing bug fixes and/or new capabilities while maintaining the behavior which applications were written against. The intent is to allow Cg to be updated and have existing applications continue to work exactly as designed.

Occasionally a case is made that some behavior of Cg is wrong, but fixing that behavior could break existing applications. This is a problem. cgSetContextBehavior provides a solution by documenting such changes to the library's behavior and allowing applications to explicitly opt-in to the new behavior. For applications which don't use cgSetContextBehavior Cg will continue to behave exactly as it did before this routine was introduced.

It is expected that the definition of a new context behavior will be a rare occurance and not something that happens with every new Cg release. Routine bug fixes and additions to the API won't result in creating new values of behavior. Instead this will only be done when the fix for a broken library behavior could cause a correctly written application to fail.

behavior must be one of the following enumerants :

CG_BEHAVIOR_3100

Cg 3.1 added a new method to define constant blocks using the uniform keyword. Using CG_BEHAVIOR_3100 enables recognition of this new construct and deprecates use of the BUFFER semantic on a struct to define a constant block. With CG_BEHAVIOR_3100 use of a buffer semantic on a struct will result in an error for GLSL profiles and a warning for all other profiles. See the Constant Buffers section of the Language Specification for details on defining constant buffers using the uniform keyword.

CG_BEHAVIOR_3000

Cg 3.0 added support for 16 additional texture units for a total of 32 using the semantics TEXUNIT16 through TEXUNIT31 and resource enums CG_TEXUNIT16 through CG_TEXUNIT31. To use these new resources, CG_BEHAVIOR_3000 is required. Using CG_BEHAVIOR_2200 with these new texture unit resources will result in a Cg error.

CG_BEHAVIOR_2200

This value specifies a pattern of behavior matching what was seen from Cg through release 2.2. Applications which specify CG_BEHAVIOR_2200 do not need to be modified to handle new context behaviors since they will continue to get the oldest behavior from the library.

Note that this selection is the default behavior for applications which never call cgSetContextBehavior, which means that existing binaries will continue to get the behavior they expect from Cg. This is also the fallback behavior if an invalid value of behavior is passed to cgSetContextBehavior.

CG_BEHAVIOR_CURRENT

When this value is used the most advanced context behavior supported by the library will be determined at compile time and will become part of the application binary. Updating the Cg runtime files will not change the behavior seen by the application at runtime. However, if the updated version of Cg defines a new value for behavior then this new behavior will be used after the application is recompiled.

CG_BEHAVIOR_LATEST

When this value is used the most advanced context behavior supported by the library will be determined at application runtime. Updating the Cg runtime files may result in new behavior from Cg even though the same application binaries are being used.

CG_BEHAVIOR_UNKNOWN

This value is returned by cgGetBehaviorString to indicate an invalid string argument has been used. Passing CG_BEHAVIOR_UNKNOWN to cgSetContextBehavior will generate an CG_INVALID_ENUMERANT_ERROR and result in the context's behavior being set to CG_BEHAVIOR_2200 instead.

If the environment variable CG_BEHAVIOR is set to any of the valid CGbehavior enumerant names, then that context behavior will be used instead of the behavior compiled into the application binary. This is true even when the application doesn't explicitly call cgSetContextBehavior. Note that CG_BEHAVIOR_CURRENT and CG_BEHAVIOR_UNKNOWN are not valid choices for CG_BEHAVIOR. Trying to use either will result in an error.

Examples

/* create a context and set the behavior to CG_BEHAVIOR_3100 */

CGcontext context = cgCreateContext();
cgSetContextBehavior(context, CG_BEHAVIOR_3100);

Errors

CG_INVALID_CONTEXT_HANDLE_ERROR is generated if context is not a valid context.

CG_INVALID_ENUMERANT_ERROR is generated if behavior is not CG_BEHAVIOR_3100, CG_BEHAVIOR_3000, CG_BEHAVIOR_2200, CG_BEHAVIOR_CURRENT, or CG_BEHAVIOR_LATEST.

History

cgSetContextBehavior was introduced in Cg 3.0.

See Also

cgCreateContext, cgGetContextBehavior, cgGetBehavior, cgGetBehaviorString