<HTML>
<HEAD>
<TITLE>cg1_2_runtime_changes</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="CG_1.2_RUNTIME_API_ADDITIONS"><A NAME="1">Cg 1.2 RUNTIME API ADDITIONS
</A></A></H1>
<P>
Version 1.2 of the Cg runtime adds a number of new capabilities to the
existing set of functionality from previous releases. These new features
include functionality that make it possible to write programs that can run
more efficiently on the GPU, techniques that help hide some of the inherent
limitations of some Cg profiles on the GPU, and entrypoints that support
new language functionality in the Cg 1.2 release.
</P>
<H2><A NAME="PARAMETER_LITERALIZATION"><A NAME="2">Parameter Literalization
</A></A></H2>
<P>
The 1.2 Cg runtime makes it possible to denote some of the parameters to a
program as having a fixed constant value. This feature can lead to
substantially more efficient programs in a number of cases. For example,
a program might have a block of code that implements functionality that is
only used some of the time:
</P>
<PRE> float4 main(uniform float enableDazzle, ...) : COLOR {
if (enableDazzle) {
// do lengthy computation
}
else {
// do basic computation
}
}
</PRE><P>
Some hardware profiles don't directly support branching (this includes all
of the fragment program profiles supported in this release), and have to
handle code like the program by effectively following both sides of the
if() test. (They still compute the correct result in the end, just not
very efficiently.)
</P>
<P>
However, if the "enableDazzle" parameter is marked as a literal parameter
and a value is provided for it, the compiler can generate an optimized
version of the program with the knowledge of "enableDazzle"'s value, just
generating GPU code for one of the two cases. This can lead to substantial
performance improvments. This feature also makes it easier to write
general purpose shaders with a wide variety of supported functionality,
while only paying the runtime cost for the functionality provided.
</P>
<P>
This feature is also useful for parameters with numeric values. For
example, consider a shader that implements a diffuse reflection model:
</P>
<PRE> float4 main(uniform float3 lightPos, uniform float3 lightColor,
uniform float3 Kd, float3 pos : TEXCOORD0,
float3 normal : TEXCOORD1) : COLOR
{
return Kd*lightColor*max(0., dot(normalize(lightPos-pos), normal));
}
</PRE><P>
If the "lightColor" and "Kd" parameters are set to literals, it is possible
for the compiler to compute the product "Kd * lightColor" once, rather than
once each time the program executes.
</P>
<P>
Given a parameter handle, the cgSetParameterVariability() entrypoint sets
the variability of a parameter:
</P>
<PRE> void cgSetParameterVariability(CGparameter param, CGenum vary);
</PRE><P>
To set it to a literal parameter, the CG_LITERAL enumerant should be passed
as the second parameter.
</P>
<P>
After a parameter has set to be a literal, the following routines should be
used to set the parameter's value.
</P>
<PRE> void cgSetParameter1f(CGparameter param, float x);
void cgSetParameter2f(CGparameter param, float x, float y);
void cgSetParameter3f(CGparameter param, float x, float y, float z);
void cgSetParameter4f(CGparameter param, float x, float y, float z,
float w);
void cgSetParameter1d(CGparameter param, double x);
void cgSetParameter2d(CGparameter param, double x, double y);
void cgSetParameter3d(CGparameter param, double x, double y, double z);
void cgSetParameter4d(CGparameter param, double x, double y, double z,
double w);
void cgSetParameter1fv(CGparameter param, const float *v);
void cgSetParameter2fv(CGparameter param, const float *v);
void cgSetParameter3fv(CGparameter param, const float *v);
void cgSetParameter4fv(CGparameter param, const float *v);
void cgSetParameter1dv(CGparameter param, const double *v);
void cgSetParameter2dv(CGparameter param, const double *v);
void cgSetParameter3dv(CGparameter param, const double *v);
void cgSetParameter4dv(CGparameter param, const double *v);
void cgSetMatrixParameterdr(CGparameter param, const double *matrix);
void cgSetMatrixParameterfr(CGparameter param, const float *matrix);
void cgSetMatrixParameterdc(CGparameter param, const double *matrix);
void cgSetMatrixParameterfc(CGparameter param, const float *matrix);
</PRE><P>
After a parameter has been set to be a literal, or after the value of a
literal parameter has been changed, the program must be compiled and loaded
into the GPU, regardless of whether it had already been compiled. This
issue is discussed further in the section on program recompilation below.
</P>
<H2><A NAME="ARRAY_SIZE_SPECIFICATION"><A NAME="3">Array Size Specification
</A></A></H2>
<P>
The Cg 1.2 language also adds support for ``unsized array'' variables;
programs can be written to take parameters that are arrays with an
indeterminate size. The actual size of these arrays is then set via the Cg
runtime. This feature is useful for writing general-purpose shaders
with a minimal performance penalty.
</P>
<P>
For example, consider a shader that computes shading given some number of
light sources. If the information about each light source is stored in a
struct LightInfo, the shader might be written as:
</P>
<PRE> float4 main(LightInfo lights[], ...) : COLOR
{
float4 color = float4(0,0,0,1);
for (i = 0; i < lights.length; ++i) {
// add lights[i]'s contribution to color
}
return color;
}
</PRE><P>
The runtime can then be used to set the length of the lights[] array (and
then to initialize the values of the LightInfo structures.) As with
literal parameters, the program must be recompiled and reloaded after a
parameter's array size is set or changes.
</P>
<P>
These two entrypoints set the size of an unsized array parameter referenced
by the given parameter handle. To set the size of a multidimensional
unsized array, all of the dimensions' sizes must be set simultaneously, by
providing them all via the pointer to an array of integer values.
</P>
<PRE> void cgSetArraySize(CGparameter param, int size);
void cgSetMultiDimArraySize(CGparameter param, const int *sizes);
</PRE><P>
XXX what happens if these are called with an already-sized array?? XXX
</P>
<P>
To get the size of an array parameter, the cgGetArraySize() entrypoint can
be used.
</P>
<PRE> int cgGetArraySize(CGparameter param, int dimension);
</PRE>
<H2><A NAME="PROGRAM_RECOMPILATION_AT_RUNTIME"><A NAME="4">Program Recompilation at Runtime
</A></A></H2>
<P>
The Cg 1.2 runtime environment will allow automatic and manual recompilation
of programs. This functionality is useful for multiple reasons :
</P>
<UL>
<LI>
<B>Changing variability of parameters</B>
</LI>
<P>
Parameters may be changed from uniform variability to literal variability
as described above.
</P>
<LI>
<B>Changing value of literal parameters</B>
</LI>
<P>
Changing the value of a literal parameter will require recompilation since
the value is used at compile time.
</P>
<LI>
<B>Resizing parameter arrays</B>
</LI>
<P>
Changing the length of a parameter array may require recompilation depending
on the capabilities of the profile of the program.
</P>
<LI>
<B>Binding sub-shader parameters</B>
</LI>
<P>
Sub-shader parameters are structures that overload methods that need to be
provided at compile time; they are described below. Binding such
parameters to program parameters will require recompilation. See
<A HREF="#SUB-SHADERS"><I>Sub-Shaders</I> within this document</A> for more information.
</P>
</UL>
<P>
Recompilation can be executed manually by the application using the runtime
or automatically by the runtime.
</P>
<P>
The entry point:
</P>
<PRE> void cgCompileProgram(CGprogram program);
</PRE><P>
causes the given program to be recompiled, and the function:
</P>
<PRE> CGbool cgIsProgramCompiled(CGprogram program);
</PRE><P>
reurns a boolean value indicating whether the current program needs
recompilation.
</P>
<P>
By default, programs are automatically compiled when cgCreateProgram() or
cgCreateProgramFromFile() is called. This behavior can be controled with the
entry point :
</P>
<PRE> void cgSetAutoCompile(CGcontext ctx, CGenum flag);
</PRE><P>
Where flag is one of the following three enumerants :
</P>
<UL>
<LI>
<B>CG_COMPILE_MANUAL</B>
</LI>
<P>
With this method the application is responsible for manually recompiling
a program. It may check to see if a program requires recompilation with
the entry point <A HREF="cgIsProgramCompiled.html">cgIsProgramCompiled()</A>.
<A HREF="cgCompileProgram.html">cgCompileProgram()</A> can then
be used to force compilation.
</P>
<LI>
<B>CG_COMPILE_IMMEDIATE</B>
</LI>
<P>
<B>CG_COMPILE_IMMEDIATE</B> will force recompilation automatically and
immediately when a program enters an uncompiled state.
</P>
<LI>
<B>CG_COMPILE_LAZY</B>
</LI>
<P>
This method is similar to <B>CG_COMPILE_IMMEDIATE</B> but will delay
program recompilation until the program object code is needed. The
advantage of this method is the reduction of extraneous recompilations.
The disadvantage is that compile time errors will not be encountered
when the program is enters the uncompiled state but will instead be
encountered at some later time.
</P>
</UL>
<P>
For programs that use features like unsized arrays that can not be compiled until
their array sizes are set, it is good practice to change the default behavior
of compilation to CG_COMPILE_MANUAL so that cgCreateProgram() or
cgCreateProgramFromFile() do not unnecessarily encounter and report
compilation errors.
</P>
<H2><A NAME="SHARED_PARAMETERS_(CONTEXT_GLOBAL_PARAMETERS)"><A NAME="5">Shared Parameters (context global parameters)
</A></A></H2>
<P>
Version 1.2 of the runtime introduces parameters that may be shared across
programs in the same context via a new binding mechanism. Once shared
parameters are constructed and bound to program parameters, setting the
value of the shared parameter will automatically set the value of all of
the program parameters they are bound to.
</P>
<P>
<A NAME="CREATEPARAMETER"> </A>
Shared parameters belong to a <B>CGcontext</B> instead of a <B>CGprogram</B>.
They may be created with the following new entry points :
</P>
<PRE> CGparameter cgCreateParameter(CGcontext ctx, CGtype type);
CGparameter cgCreateParameterArray(CGcontext ctx, CGtype type,
int length);
CGparameter cgCreateParameterMultiDimArray(CGcontext ctx, CGtype type,
int dim, const int *lengths);
</PRE><P>
They may be deleted with :
</P>
<PRE> void cgDestroyParameter(CGparameter param);
</PRE><P>
After a parameter has been created, its value should be set with the
cgSetParameter*() routines described in the literalization section above.
</P>
<P>
<A NAME="BINDPARAMETER"> </A>
Once a shared parameter is created it may be associated with any number of program
parameters with the call:
</P>
<PRE> void cgConnectParameter(CGparameter from, CGparameter to);
</PRE><P>
where ``from'' is a parameter created with one of the cgCreateParameter()
calls, and ``to'' is a program parameter.
</P>
<P>
Given a program parameter, the handle to the shared parameter that is bound
to it (if any) can be found with the call:
</P>
<PRE> CGparameter cgGetConnectedParameter(CGparameter param);
</PRE><P>
It returns NULL if no shared parameter has been connected to ``param''.
</P>
<P>
There are also calls that make it possible to find the set of program
parameters to which a given shared parameter has been connected to. The
entry point:
</P>
<PRE> int cgGetNumConnectedToParameters(CGparameter param);
</PRE><P>
returns the total number of program parameters that ``param'' has been
conencted to, and the entry point:
</P>
<PRE> CGparameter cgGetConnectedToParameter(CGparameter param, int index);
</PRE><P>
can be used to get CGparameter handles for each of the program parameters
to which a shared parameter is connected.
</P>
<P>
A shared parameter can be unbound from a program parameter with :
</P>
<PRE> void cgDisconnectParameter(CGparameter param);
</PRE><P>
The context in which a shared parameter was created can be returned with:
</P>
<PRE> CGcontext cgGetParameterContext(CGparameter param);
</PRE><P>
And the entrypoint:
</P>
<PRE> CGbool cgIsParameterGlobal(CGparameter param);
</PRE><P>
can be used to determine if a parameter is a shared (global) parameter.
</P>
<H2><A NAME="SHADER_INTERFACE_SUPPORT"><A NAME="6">Shader Interface Support
</A></A></H2>
<P>
From the runtime's perspective, shader interfaces are simply struct parameters that have
a <B>CGtype</B> associated with them. For example, if the following Cg code is included
in some program source compiled in the runtime :
</P>
<PRE> interface FooInterface
{
float SomeMethod(float x);
}
struct FooStruct : FooInterface
{
float SomeMethod(float x);
{
return(Scale * x);
}
float Scale;
};
</PRE><P>
The named types <B>FooInterface</B> and <B>FooStruct</B> will be added to the context.
Each one will have a unique <B>CGtype</B> associated with it. The <B>CGtype</B> can
be retrieved with :
</P>
<PRE> CGtype cgGetNamedUserType(CGprogram program, const char *name);
int cgGetNumUserTypes(CGprogram program);
CGtype cgGetUserType(CGprogram program, int index);
CGbool cgIsParentType(CGtype parent, CGtype child);
CGbool cgIsInterfaceType(CGtype type);
</PRE><P>
Once the <B>CGtype</B> has been retrieved, it may be used to construct an instance
of the struct using <A HREF="#CREATEPARAMETER">cgCreateParameter()</A>. It may then
be bound to a program parameter of the parent type (in the above example this
would be FooInterface) using <A HREF="#BINDPARAMETER">cgBindParameter()</A>.
</P>
<P>
Calling <A HREF="cgGetParameterType.html">cgGetParameterType()</A> on such a parameter will
return the <B>CG_STRUCT</B> to keep backwards compatibility with code that recurses
parameter trees. In order to obtain the enumerant of the named type the
following entry point should be used :
</P>
<PRE> CGtype cgGetParameterNamedType(CGparameter param);
</PRE><P>
The parent types of a given named type may be obtained with the following
entry points :
</P>
<PRE> int cgGetNumParentTypes(CGtype type);
CGtype cgGetParentType(CGtype type, int index);
</PRE><P>
If Cg source modules with differing definitions of named types are added to the
same context, an error will be thrown.
</P>
<P>
XXX update for new scoping/context/program local definitions stuff XXX
</P>
<H2><A NAME="UPDATED_PARAMETER_MANAGEMENT_ROUTINES"><A NAME="7">Updated Parameter Management Routines
</A></A></H2>
<P>
XXX where should these go?
</P>
<P>
Some entrypoints from before have been updated in backwards compatible ways
</P>
<PRE> CGparameter cgGetFirstParameter(CGprogram program, CGenum name_space);
CGparameter cgGetFirstLeafParameter(CGprogram program, CGenum name_space);
</PRE><P>
like cgGetNamedParameter, but limits search to the given name_space
(CG_PROGRAM or CG_GLOBAL)...
</P>
<PRE> CGparameter cgGetNamedProgramParameter(CGprogram program, CGenum name_space,
const char *name);</PRE>
</BLOCKQUOTE>
</BODY>
