<HTML>
<HEAD>
<TITLE>cgSetContextBehavior</TITLE>
<STYLE TYPE="text/css" MEDIA=screen>
<!--
BODY {
font-family: Arial,Helvetica;
}
BLOCKQUOTE { margin: 10pt; }
H1,A { color: #336699; }
/*** Top menu style ****/
.mmenuon {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #ff6600; font-size: 10pt;
}
.mmenuoff {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #ffffff; font-size: 10pt;
}
.cpyright {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #ffffff; font-size: xx-small;
}
.cpyrightText {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #ffffff; font-size: xx-small;
}
.sections {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 11pt;
}
.dsections {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 12pt;
}
.slink {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
color: #336699; font-size: 9pt;
}
.slink2 { font-family: Arial,Helvetica; text-decoration: none; color: #336699; }
.maintitle {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 18pt;
}
.dblArrow {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: small;
}
.menuSec {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: small;
}
.newstext {
font-family: Arial,Helvetica; font-size: small;
}
.linkmenu {
font-family: Arial,Helvetica; color: #000000; font-weight: bold;
text-decoration: none;
}
P {
font-family: Arial,Helvetica;
}
PRE {
font-family: monospace;
white-space: pre;
font-color: #333333;
font-weight: 100;
background-color: #eeeeee;
padding: 5px;
width: 90%;
border-style: solid;
border-width: 2px;
border-color: #bebebe;
}
.quote {
font-family: Times; text-decoration: none;
color: #000000; font-size: 9pt; font-style: italic;
}
.smstd { font-family: Arial,Helvetica; color: #000000; font-size: x-small; }
.std { font-family: Arial,Helvetica; color: #000000; }
.meerkatTitle {
font-family: sans-serif; font-size: x-small; color: black; }
.meerkatDescription { font-family: sans-serif; font-size: 10pt; color: black }
.meerkatCategory {
font-family: sans-serif; font-size: 9pt; font-weight: bold; font-style: italic;
color: brown; }
.meerkatChannel {
font-family: sans-serif; font-size: 9pt; font-style: italic; color: brown; }
.meerkatDate { font-family: sans-serif; font-size: xx-small; color: #336699; }
.tocTitle {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #333333; font-size: 10pt;
}
.toc-item {
font-family: Arial,Helvetica; font-weight: bold;
color: #336699; font-size: 10pt; text-decoration: underline;
}
.perlVersion {
font-family: Arial,Helvetica; font-weight: bold;
color: #336699; font-size: 10pt; text-decoration: none;
}
.docTitle {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #000000; font-size: 10pt;
}
.dotDot {
font-family: Arial,Helvetica; font-weight: bold;
color: #000000; font-size: 9pt;
}
.docSec {
font-family: Arial,Helvetica; font-weight: normal;
color: #333333; font-size: 9pt;
}
.docVersion {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 10pt;
}
.docSecs-on {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
color: #ff0000; font-size: 10pt;
}
.docSecs-off {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
color: #333333; font-size: 10pt;
}
h3 {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: small;
}
h2 {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: medium;
}
h1 {
font-family: Verdana,Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: large;
}
DL {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: none;
color: #333333; font-size: 10pt;
}
UL > LI > A {
font-family: Arial,Helvetica; font-weight: bold;
color: #336699; font-size: 10pt;
}
.moduleInfo {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #333333; font-size: 11pt;
}
.moduleInfoSec {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 10pt;
}
.moduleInfoVal {
font-family: Arial,Helvetica; font-weight: normal; text-decoration: underline;
color: #000000; font-size: 10pt;
}
.cpanNavTitle {
font-family: Arial,Helvetica; font-weight: bold;
color: #ffffff; font-size: 10pt;
}
.cpanNavLetter {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #333333; font-size: 9pt;
}
.cpanCat {
font-family: Arial,Helvetica; font-weight: bold; text-decoration: none;
color: #336699; font-size: 9pt;
}
-->
</STYLE>
</HEAD>
<BODY>
<object type="application/x-oleobject" classid="clsid:1e2a7bd0-dab9-11d0-b93a-00c04fc99f9e">
</object>
<BLOCKQUOTE>
<H1><A NAME="NAME"><A NAME="1">NAME
</A></A></H1>
<P>
<B>cgSetContextBehavior</B> - set the behavior for a context
</P>
<H1><A NAME="SYNOPSIS"><A NAME="2">SYNOPSIS
</A></A></H1>
<PRE> #include <Cg/cg.h>
void cgSetContextBehavior( CGcontext context,
CGbehavior behavior );
</PRE>
<H1><A NAME="PARAMETERS"><A NAME="3">PARAMETERS
</A></A></H1>
<DL>
<DT><STRONG><I>context</I>
</STRONG></DT>
<DD>
<P>
The context for which the behavior will be set.
</P>
<DT><STRONG><I>behavior</I>
</STRONG></DT>
<DD>
<P>
An enumerant which defines the behavior that will be exhibited
by <B>context</B>. The following enumerants are allowed:
</P>
<UL>
<LI>
<B>CG_BEHAVIOR_3000</B>
</LI>
<LI>
<B>CG_BEHAVIOR_2200</B>
</LI>
<LI>
<B>CG_BEHAVIOR_CURRENT</B>
</LI>
<LI>
<B>CG_BEHAVIOR_LATEST</B>
</LI>
</UL>
</DD></DL>
<H1><A NAME="RETURN_VALUES"><A NAME="4">RETURN VALUES
</A></A></H1>
<P>
None.
</P>
<H1><A NAME="DESCRIPTION"><A NAME="5">DESCRIPTION
</A></A></H1>
<P>
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.
</P>
<P>
Occasionally a case is made that some behavior of Cg is wrong, but fixing
that behavior could break existing applications. This is a problem.
<B>cgSetContextBehavior</B> 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 <B>cgSetContextBehavior</B>
Cg will continue to behave exactly as it did before this routine was introduced.
</P>
<P>
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 <B>behavior</B>. Instead this will only be done when the fix for a broken
library behavior could cause a correctly written application to fail.
</P>
<P>
<B>behavior</B> must be one of the following enumerants :
</P>
<UL>
<LI>
<B>CG_BEHAVIOR_3000</B>
</LI>
<P>
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.
</P>
<LI>
<B>CG_BEHAVIOR_2200</B>
</LI>
<P>
This value specifies a pattern of behavior matching what was seen from Cg
through release 2.2. Applications which specify <B>CG_BEHAVIOR_2200</B>
do not need to be modified to handle new context behaviors since they will
continue to get the oldest behavior from the library.
</P>
<P>
Note that this selection is the default behavior for applications which
never call <B>cgSetContextBehavior</B>, 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 <B>behavior</B> is passed to
<B>cgSetContextBehavior</B>.
</P>
<LI>
<B>CG_BEHAVIOR_CURRENT</B>
</LI>
<P>
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 <B>behavior</B> then this new
behavior will be used after the application is recompiled.
</P>
<LI>
<B>CG_BEHAVIOR_LATEST</B>
</LI>
<P>
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.
</P>
<LI>
<B>CG_BEHAVIOR_UNKNOWN</B>
</LI>
<P>
This value is returned by <A HREF="cgGetBehaviorString.html">cgGetBehaviorString</A>
to indicate an invalid string argument has been used. Passing
<B>CG_BEHAVIOR_UNKNOWN</B> to <B>cgSetContextBehavior</B> will generate an
<B>CG_INVALID_ENUMERANT_ERROR</B> and result in the context's behavior
being set to <B>CG_BEHAVIOR_2200</B> instead.
</P>
</UL>
<P>
If the environment variable <B>CG_BEHAVIOR</B> is set to any of
the valid <B>CGbehavior</B> 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 <B>cgSetContextBehavior</B>. Note that <B>CG_BEHAVIOR_CURRENT</B> and
<B>CG_BEHAVIOR_UNKNOWN</B> are not valid choices for <B>CG_BEHAVIOR</B>.
Trying to use either will result in an error.
</P>
<H1><A NAME="EXAMPLES"><A NAME="6">EXAMPLES
</A></A></H1>
<PRE> /* create a context and set the behavior to CG_BEHAVIOR_3000 */
CGcontext context = cgCreateContext();
cgSetContextBehavior(context, CG_BEHAVIOR_3000);
</PRE>
<H1><A NAME="ERRORS"><A NAME="7">ERRORS
</A></A></H1>
<P>
<B>CG_INVALID_CONTEXT_HANDLE_ERROR</B> is generated if <B>context</B> is not a valid context.
</P>
<P>
<B>CG_INVALID_ENUMERANT_ERROR</B> is generated if <B>behavior</B> is not
<B>CG_BEHAVIOR_3000</B>, <B>CG_BEHAVIOR_2200</B>,
<B>CG_BEHAVIOR_CURRENT</B>, or <B>CG_BEHAVIOR_LATEST</B>.
</P>
<H1><A NAME="HISTORY"><A NAME="8">HISTORY
</A></A></H1>
<P>
<B>cgSetContextBehavior</B> was introduced in Cg 3.0.
</P>
<H1><A NAME="SEE_ALSO"><A NAME="9">SEE ALSO
</A></A></H1>
<P>
<A HREF="cgCreateContext.html">cgCreateContext</A>,
<A HREF="cgGetContextBehavior.html">cgGetContextBehavior</A>,
<A HREF="cgGetBehavior.html">cgGetBehavior</A>,
<A HREF="cgGetBehaviorString.html">cgGetBehaviorString</A>
</P>
</BLOCKQUOTE>
</BODY>
