Setting a Breakpoint

Your application can programmatically set breakpoints when it is attached to OpenGL Profiler.

To set a breakpoint:

1. Include the CGLProfiler.h and CGLProfilerFunctionEnum.h header files in your application.

2. Declare an array of three GLint values, set to the following:

   • The function ID, as defined in the header file CGLProfilerFunctionEnum.h.

   • The logical OR of kCGLProfBreakBefore or kCGLProfBreakAfter, indicating how you want the breakpoint to stop—before entering the OpenGL function, on return from it, or both.

   • A Boolean that turns the breakpoint on or off.

3. Call the function CGLSetOption, passing the array as a parameter.

Listing 4-1 shows code that sets a breakpoint before the CGLFlushDrawable function.

Listing 4-1  Code that sets a breakpoint

#include "OpenGL/CGLProfiler.h"

#include "OpenGL/CGLProfilerFunctionEnum.h"

...

   GLint myBreakpoint[] = { kCGLFECGLFlushDrawable, kCGLProfBreakBefore, 1;}

   CGLSetOption( kCGLGOEnableBreakpoint, myBreakpoint );

...

Writing Comments to the Trace Window

Your application can programmatically write comments to the Trace window during a profiling session. To write comments:

1. Include the CGLProfiler.h header file in your application.

2. Call the function CGLSetOption with the constant kCGLGOComment and your comment cast as a long.

Listing 4-2 shows code that writes a comment that looks like this in the Trace window:

21561: 0.00 µs /* ***** My Comment is here ***** */

Listing 4-2  Code that writes a comment to the Trace window

#include <OpenGL/CGLProfiler.h>

...

  CGLSetOption(kCGLGOComment, (long) "***** My Comment is here *****");

...

Controlling Trace Collection

Your application can programmatically control when to start and stop collecting a trace, which lets you control which traces to collect in a specific part of your application or during a particular period of time. You can also clear the Trace window.

To control trace collection:

1. Include the CGLProfiler.h header file in your application.

2. Call the function CGLSetOption with the constant kCGLGOEnableFunctionTrace and either GL_TRUE (to turn on trace collection) or GL_FALSE (to turn off trace collection).

Listing 4-3 shows code that enables trace collection.

Listing 4-3  Code that enables trace collection

#include <OpenGL/CGLProfiler.h>

...

  CGLSetOption(kCGLGOEnableFunctionTrace, GL_TRUE);

...

To clear the Trace window:

1. Include the CGLProfiler.h header file in your application.

2. Call the function CGLSetOption with the constant kCGLGOResetFunctionTrace and the value NULL.

Listing 4-4 shows code that enables trace collection.

Listing 4-4  Code that clears the Trace window

#include <OpenGL/CGLProfiler.h>

...

  CGLSetOption(kCGLGOResetFunctionTrace, NULL);

...

Controlling Statistics Collection

You application can programmatically control when to start and stop collecting statistics. You must make sure that the Statistics window in OpenGL Profiler is open when you profile your application.

To control statistics collection:

1. Include the CGLProfiler.h header file in your application.

2. Call the function CGLSetOption with the constant kCGLGOResetFunctionStatistics and the value NULL to first reset counters to 0. This step is optional.

3. Call the function CGLSetOption with the constant kCGLGOResetFunctionStatistics and the value GL_TRUE to start statistics collection.

4. When you are done collecting statistics, call the function CGLSetOption with the constant kCGLGOResetFunctionStatistics and the value GL_FALSE.

Listing 4-5 shows code that resets counters, starts statistics collection, and then stops it.

Listing 4-5  Code that starts and stops statistics collection

#include <OpenGL/CGLProfiler.h>

...

  // Reset counters to 0

  CGLSetOption(kCGLGOResetFunctionStatistics, NULL);

  // Start statistics collection

  CGLSetOption(kCGLGOEnableFunctionStatistics, GL_TRUE);

...

  // Stop statistics collection

  CGLSetOption(kCGLGOEnableFunctionStatistics, GL_FALSE);

...