<HTML>
<HEAD>
<TITLE>trace</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="TOPIC"><A NAME="1">TOPIC
</A></A></H1>
<P>
<B>Trace</B> - API Trace for Cg, CgGL, OpenGL and GLUT
</P>
<H2><A NAME="INTRODUCTION"><A NAME="2">INTRODUCTION
</A></A></H2>
<P>
The NVIDIA Cg Toolkit provides trace wrapper libraries for logging API calls
to Cg, CgGL, OpenGL and GLUT libraries. The log includes nested function
call information and function parameter and return values. The logged data can be
useful for debugging, trouble shooting and reporting issues.
</P>
<P>
The libraries are experimental and require some software development expertise.
</P>
<H2><A NAME="REQUIREMENTS_AND_LIMITATIONS"><A NAME="3">REQUIREMENTS AND LIMITATIONS
</A></A></H2>
<P>
Trace supports Cg version 2.2.010 (October 2009) and onwards.
Cg, CgGL, OpenGL, and GLUT trace libraries are included.
</P>
<P>
CgD3D8, CgD3D9, CgD3D10 and CgD3D10 are not currently supported.
</P>
<P>
Cg and GLUT are supported for OSX, but currently not OpenGL.
</P>
<P>
Trace captures calls and parameters, but not the contents of files
referenced by calls such as <A HREF="cgCreateProgramFromFile.html"><I>cgCreateProgramFromFile</I></A>.
Archive the logs, .cg and .cgfx files together into a .zip or .tgz for later reference.
</P>
<H2><A NAME="BUILDING"><A NAME="4">BUILDING
</A></A></H2>
<P>
The trace library source code, makefile and Visual Studio projects are
located in the examples/Tools/trace directory of the Cg Toolkit installation.
Pre-built binaries are also included.
</P>
<P>
The trace library components are as follows.
</P>
<PRE> trace.c }
traceOutput.c } ----> trace library
traceFilter.c }
traceTime.c }
b64.c }
traceCg.c ----> Cg wrapper library
traceCgGL.c ----> CgGL wrapper library
traceGLUT.c ----> GLUT wrapper library
traceGL.c }
traceGLX.c } ----> GL wrapper library
traceWGL.c }
</PRE>
<H2><A NAME="DEPLOYMENT"><A NAME="5">DEPLOYMENT
</A></A></H2>
<H3><A NAME="ENVIRONMENT_VARIABLES"><A NAME="6">ENVIRONMENT VARIABLES
</A></A></H3>
<P>
The <B>CG_TRACE_FILE</B> and <B>CG_TRACE_ERROR</B> environment variables specify
paths to the trace log and error log. The two file names can be the same.
Otherwise <B>stdout</B> and <B>stderr</B> are used.
</P>
<P>
The <B>CG_TRACE_CG_LIBRARY</B> and <B>CG_TRACE_CGGL_LIBRARY</B> environment variables
specify the path of the target Cg and CgGL libraries.
The <B>CG_TRACE_GL_LIBRARY</B> environment variable specifies the path of the
target OpenGL library.
The <B>CG_TRACE_GLUT_LIBRARY</B> environment variable specifies the path of the
target OpenGL library.
</P>
<P>
Otherwise, default system locations are used.
</P>
<P>
The <B>CG_TRACE_BLOB_LIMIT</B> environment variable limits the size of raw data logged.
Just the pointer value is stored for parameters that exceed the limit.
This variable is typically set to avoid capturing texture image data.
By default there is no limit and all parameter data is logged.
</P>
<P>
The <B>CG_TRACE_TIMESTAMP</B> environment variable specifies timestamp logging for each call.
Any non-zero integer value enables timestamp tracing.
By default timestamp logging is disabled.
</P>
<P>
Recommended settings:
</P>
<PRE> CG_TRACE_FILE traceLog.txt
CG_TRACE_ERROR traceError.txt
</PRE>
<H3><A NAME="WINDOWS"><A NAME="7">WINDOWS
</A></A></H3>
<P>
Select a trace directory to copy the trace libraries to.
This can be the same as the application directory.
The directory of the target <B>.exe</B> is recommended.
</P>
<P>
Copy <B>trace.dll</B> to the trace directory.
The API-specific trace libraries depend on <B>trace.dll</B>.
The other trace libraries are optional.
</P>
<P>
Optionally copy trace <B>cg.dll</B> and <B>cgGL.dll</B> to the trace directory.
The <B>CG_BIN_PATH</B> (32-bit) or <B>CG_BIN64_PATH</B> (64-bit) environment variables are used
unless <B>CG_TRACE_CG_LIBRARY</B> or <B>CG_TRACE_CGGL_LIBRARY</B> are defined.
</P>
<P>
Optionally copy trace <B>opengl32.dll</B> to the trace directory.
</P>
<P>
Optionally copy trace <B>glut32.dll</B> to the trace directory.
</P>
<H3><A NAME="LINUX_AND_SOLARIS"><A NAME="8">LINUX and SOLARIS
</A></A></H3>
<P>
Set the <B>LD_LIBRARY_PATH</B> environment variable to the directory containing the trace libraries.
The API-specific trace libraries depend on <B>libtrace.so</B>.
The other trace libraries are optional.
</P>
<H3><A NAME="OSX"><A NAME="9">OSX
</A></A></H3>
<P>
Set the <B>DYLD_LIBRARY_PATH</B> environment variable to the directory containing the trace libraries.
These are installed to <B>/Developer/NVIDIA/Cg/examples/Tools/trace</B> by default.
The API-specific trace libraries depend on <B>libtrace.dylib</B>.
The <B>Cg</B> and <B>GLUT</B> trace frameworks are both optional.
The symlinks <B>libCg.dylib</B> and <B>libGLUT.dylib</B> specify the full path of the native frameworks.
</P>
<H2><A NAME="CREDITS_AND_LICENCES"><A NAME="10">CREDITS AND LICENCES
</A></A></H2>
<P>
The core trace library uses the <A HREF="<A HREF="http:.html">.html</A>">base64</A> C implementation of
Base64 Content-Transfer-Encoding standard (also known as <A HREF="<A HREF="http:.html">.html</A>">RFC1113</A>) by Bob Trower, Trantor Standard Systems Inc.
</P>
<P>
The Cg trace library uses the <A HREF="<A HREF="http:.html">.html</A>">uthash</A> C hash table implementation by Troy D. Hanson.
</P>
</BLOCKQUOTE>
</BODY>
