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_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 :

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_3000 */

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

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_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