cgSetContextBehavior(3)

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 :

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