Topic

Trace - API Trace for Cg, CgGL, OpenGL and GLUT

Introduction

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.

The libraries are experimental and require some software development expertise.

Requirements And Limitations

Trace supports Cg version 2.2.010 (October 2009) and onwards. Cg, CgGL, OpenGL, and GLUT trace libraries are included.

CgD3D9, CgD3D10 and CgD3D10 are not currently supported.

Cg and GLUT are supported for OSX, but currently not OpenGL.

Trace captures calls and parameters, but not the contents of files referenced by calls such as cgCreateProgramFromFile. Archive the logs, .cg and .cgfx files together into a .zip or .tgz for later reference.

Building

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.

The trace library components are as follows.

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    }

Deployment

Environment Variables

The CG_TRACE_FILE and CG_TRACE_ERROR environment variables specify paths to the trace log and error log. The two file names can be the same. Otherwise stdout and stderr are used.

The CG_TRACE_CG_LIBRARY and CG_TRACE_CGGL_LIBRARY environment variables specify the path of the target Cg and CgGL libraries. The CG_TRACE_GL_LIBRARY environment variable specifies the path of the target OpenGL library. The CG_TRACE_GLUT_LIBRARY environment variable specifies the path of the target OpenGL library.

Otherwise, default system locations are used.

The CG_TRACE_ENABLE environment variable enables or disables trace output. By default trace output is enabled.

The CG_TRACE_BASE64 environment variable specifies base64 encoding for binary data such as float, double and byte arrays. A zero integer value disables base64 encoding for floats, doubles and byte arrays. By default base64 encoding is enabled.

The CG_TRACE_BLOB_LIMIT 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.

The CG_TRACE_TIMESTAMP environment variable specifies timestamp logging for each call. Any non-zero integer value enables timestamp tracing. By default timestamp logging is disabled.

Recommended settings:

CG_TRACE_FILE traceLog.txt
CG_TRACE_ERROR traceError.txt

Windows

Select a trace directory to copy the trace libraries to. This can be the same as the application directory. The directory of the target .exe is recommended.

Copy trace.dll to the trace directory. The API-specific trace libraries depend on trace.dll. The other trace libraries are optional.

Optionally copy trace cg.dll and cgGL.dll to the trace directory. The CG_BIN_PATH (32-bit) or CG_BIN64_PATH (64-bit) environment variables are used unless CG_TRACE_CG_LIBRARY or CG_TRACE_CGGL_LIBRARY are defined.

Optionally copy trace opengl32.dll to the trace directory.

Optionally copy trace glut32.dll to the trace directory.

Linux And Solaris

Set the LD_LIBRARY_PATH environment variable to the directory containing the trace libraries. The API-specific trace libraries depend on libtrace.so. The other trace libraries are optional.

OSX

Set the DYLD_LIBRARY_PATH environment variable to the directory containing the trace libraries. These are installed to /Developer/NVIDIA/Cg/examples/Tools/trace by default. The API-specific trace libraries depend on libtrace.dylib. The Cg and GLUT trace frameworks are both optional. The symlinks libCg.dylib and libGLUT.dylib specify the full path of the native frameworks.

Credits And Licences

The core trace library uses the base64 C implementation of Base64 Content-Transfer-Encoding standard (also known as RFC1113) by Bob Trower, Trantor Standard Systems Inc.

The Cg trace library uses the uthash C hash table implementation by Troy D. Hanson.