---

Creating a Visual Context

Create a visual context if you need to manipulate individual frames before, or instead of, rendering them to the screen.

You create a visual context by calling one of the QT...ContextCreate functions, such as QTPixelBufferContextCreate or QTOpenGLTextureContextCreate. These functions return a QTVisualContextRef, an opaque token that you can pass to NewMovieFromProperties as part of a properties array or apply to an existing movie using SetMovieVisualContext.

QTPixelBufferContextCreate creates a visual context that causes QuickTime to render each frame to a Core Video pixel buffer in main memory. You can inspect or modify the frame and pass the pixel buffer to Core Image or OpenGL for display.

The QTPixelBufferContextCreate function takes a dictionary of attributes as an argument. This is a CFDictionary, an array of key-value pairs. This dictionary contains attributes such as the target dimensions and pixel buffer description. Some of these attributes are themselves contained in dictionaries, so the attributes dictionary can contain references to other dictionaries. Create the dictionaries using CFDictionaryCreate. For additional details, see “Visual Context Types” in QuickTime 7 Update Guide.

To specify a particular pixel buffer format, create a dictionary with the desired attributes as described in “Pixel Buffer Attribute Keys” in Core Video Reference. If you do not specify a pixel buffer format, QuickTime uses the native pixel format of the video frame.

To render each frame as an OpenGL texture, create the context using QTOpenGLTextureContextCreate. You are responsible for passing the textures to OpenGL for display.

QTOpenGLTextureContextCreate takes an OpenGL context and a pixel format object as arguments, as well as a CFDictionary of attributes.

To disable visual rendering, pass NULL instead of a VisualContextRef, either to SetMovieVisualContext or as a visual context movie property. This also frees the context for reuse or disposal.

To render to an offscreen graphics world instead of to a Core Video pixel buffer, disable visual rendering by setting a NULL visual context, then call SetMovieGWorld after the movie is instantiated. Do this if you need to manipulate individual frames using an older technology, such as QuickDraw, that works with GWorlds.

When you render to a pixel buffer or GWorld, you render to main memory and typically lose the advantages of graphics acceleration. When you render to an OpenGL texture, you render directly to video memory. 

When you render to the default graphics port, QuickTime attempts to use video memory, but the actual rendering path depends on factors such as the media types, compressed pixel formats, and available transfer codecs. 

To render to the default graphics port, do not include a visual context in the properties array when calling NewMovieFromProperties. You are not responsible for rendering individual frames in this case; QuickTime renders them automatically as the movie plays. For more information, see “Using a Graphics Port or GWorld.”

---