READ ME - OpenGLScreenSnapshot

v1.1                    6/27/08

-----------------------------

OpenGLScreenSnapshot is a Mac OS X application which demonstrates how to use OpenGL to grab a "snapshot" of the screen and save it to a image file on disk. This sample uses the OpenGL glReadPixels function to get the pixel data for the screen. This technique is actually very simple to use, and is sufficient for grabbing a single or a very few frames.

Building the Sample

-------------------

The sample was built using Xcode 3 on Mac OS X 10.5. You can just open the project and choose Build from the Build menu.  This will build the OpenGLScreenSnapshot application in the "Build" directory.

Using the Sample

----------------

To try out the OpenGLScreenSnapshot application, launch the application and select the "Capture" menu, then choose the "Screen Snapshot" menu item. The program will then take a single "snapshot" of the current screen and save the screen grab to a TIFF image file on the desktop.

How It Works

------------

As stated above, the sample shows how to use the glReadPixels() function for capturing the screen: a synchronous, but easy way for capturing a single or very few frames. 

Synchronous capture using glReadPixels() is fairly simple approach. Simply call this function and OpenGL will read pixel data from the framebuffer for you. But glReadPixels() by its very nature is an expensive function call. Therefore, care must be taken when using glReadPixels() that it is done in the most effective and efficient way possible. The glReadPixels() function will cause a synch point to be placed in the command stream. This synch point forces a synchronization between the CPU and GPU, which can have the effect of stalling the rendering pipeline. When this occurs, performance is guaranteed to suffer while either CPU or GPU is waiting for the other to catch up.

Asynchronous texture fetching is another technique for grabbing the screen bits, and it offers much better performance, but it is also more complicated. See the OpenGL documentation on the ADC website for more information about asynchronous texture fetching.

Additional Information

----------------

For additional information, see the following documents:

OpenGL Performance Optimizations : The Basics

<http://developer.apple.com/technotes/tn2004/tn2093.html>

OpenGL Programming Guide For Mac OS X

<http://developer.apple.com/documentation/GraphicsImaging/Conceptual/OpenGL-MacProgGuide/index.html>

Finally, note that only minimal error checking is provided in this sample. In production code, a robust error handling strategy must be devised at the architectural level. This is left as an exercise for the reader.