Deprecated CGL Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in OS X v10.6

CGLSetFullScreen

Attaches a rendering context to its full-screen drawable object. (Deprecated in OS X v10.6. Use CGLSetFullScreenOnDisplay instead.)

CGLError CGLSetFullScreen (
   CGLContextObj ctx
);
Parameters
ctx

A rendering context.

Return Value

A result code. See “CGL Result Codes.”

Discussion

Before calling this function, you must set up the rendering context using a pixel format object created with the kCGLPFAFullScreen attribute (see “Buffer and Renderer Attributes”). Some OpenGL renderers, such as the software renderer, do not support full-screen mode. After you call the function CGLChoosePixelFormat with the full-screen attribute, you need to check whether the pixel format object is created successfully.

You must capture the display prior to entering full-screen mode and release it after exiting. After calling this function, subsequent OpenGL drawing is rendered into the entire screen. For more information, see OpenGL Programming Guide for Mac.

To exit full-screen mode, call CGLClearDrawable.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Related Sample Code
Declared In
OpenGL.h

Deprecated in OS X v10.7

CGLCreatePBuffer

Creates a pixel buffer of the specified size, compatible with the specified texture target. (Deprecated in OS X v10.7.)

CGLError CGLCreatePBuffer (
   GLsizei width,
   GLsizei height,
   GLenum target,
   GLenum internalFormat,
   GLint max_level,
   CGLPBufferObj *pbuffer
);
Parameters
width

The width, in pixels, of the pixel buffer.

height

The height, in pixels, of the pixel buffer.

target

A constant that specifies the type of the pixel buffer target texture. You can supply any of the following texture targets:

  • GL_TEXTURE_2D, a texture whose dimensions are a power of two.

  • GL_TEXTURE_RECTANGLE_EXT, a texture whose dimensions are not a power of two.

  • GL_TEXTURE_CUBE_MAP, a mapped cube texture.

internalFormat

A constant that specifies the internal color format of the pixel buffer, which can be either GL_RGB or GL_RGBA. The format controls whether the alpha channel of the pixel buffer is used for texturing operations.

max_level

The maximum level of mipmap detail allowable. Pass 0 for a pixel buffer that is not using mipmaps. The value passed should never exceed the actual maximum number of mipmap levels that can be represented with the given width and height.

pbuffer

On return, points to a new pixel buffer object.

Return Value

A result code. See “CGL Result Codes.” This function returns kCGLBadAlloc if it cannot allocate storage for the pixel buffer data structure. It returns kCGLBadValue for any of these conditions:

  • A negative max_level value provided or a max_level value greater than the maximum possible mipmap levels for the given width and height provided.

  • A max_level value greater than 0 used with a GL_TEXTURE_RECTANGLE_EXT texture target

  • The dimensions provided for a GL_TEXTURE_CUBE_MAP texture target aren't equal.

Discussion

This function does not have any knowledge of OpenGL contexts or pixel format objects and does not specifically allocate the storage needed for the actual pixel buffer. These operations occur when you call the function CGLSetPBuffer.

You can determine the dimensional limits of a pixel buffer by calling the OpenGL function glGetInteger. You can find the maximum size supported by querying GL_MAX_VIEWPORT_DIMS and the minimum size by querying GL_MIN_PBUFFER_VIEWPORT_DIMS_APPLE, which returns two integer values (similar to GL_MAX_VIEWPORT_DIMS). All pixel buffer dimensions that you request with the function aglCreatePBuffer should fall within these limits (inclusively) and should comply with any limitations imposed by the texture target you select.

The maximum viewport size supported in OS X is quite large. You should take into consideration the amount of video or system memory required to support the requested pixel buffer size, including additional memory needed for multiple buffers and options such as multisampling.

Starting in OS X v10.5, pixel buffer objects are reference counted. Pixel buffer objects are created with a reference count of 1 and are destroyed when the last reference to the object is released.

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.7.
Declared In
OpenGL.h

CGLDescribePBuffer

Retrieves information that describes the specified pixel buffer object. (Deprecated in OS X v10.7.)

CGLError CGLDescribePBuffer (
   CGLPBufferObj obj,
   GLsizei *width,
   GLsizei *height,
   GLenum *target,
   GLenum *internalFormat,
   GLint *mipmap
);
Parameters
obj

A pointer to the pixel buffer object.

width

On return, points to the width, in pixels, of the pixel buffer.

height

On return, points to the height, in pixels, of the pixel buffer.

target

On return, points to a constant that specifies the pixel buffer texture target:

  • GL_TEXTURE_2D, a texture whose dimensions are a power of two.

  • GL_TEXTURE_RECTANGLE_EXT, a texture whose dimensions are not a power of two.

  • GL_TEXTURE_CUBE_MAP, a mapped cube texture.

internalFormat

On return, points to a constant that specifies the internal color format of the pixel buffer—either GL_RGB or GL_RGBA.

mipmap

On return, points to the mipmap level of the pixel buffer or 0 if it doesn't use mipmaps.

Return Value

A result code. See “CGL Result Codes.”

Discussion

The width, height, texture target, and internal texture color format of a pixel buffer object are set at its creation and cannot be changed without destroying and recreating the object. The level is set when the pixel buffer object is attached to a rendering context by calling the function CGLSetPBuffer.

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.7.
Declared In
OpenGL.h

CGLDestroyPBuffer

Releases the resources associated with a pixel buffer object. (Deprecated in OS X v10.7.)

CGLError CGLDestroyPBuffer (
   CGLPBufferObj pbuffer
);
Parameters
pbuffer

The pixel buffer object whose resources you want to release.

Return Value

A result code. See “CGL Result Codes.”

Discussion

Starting in OS X v10.5, pixel buffer objects are reference counted. Calling this function is equivalent to calling CGLReleasePBuffer.

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.7.
Declared In
OpenGL.h

CGLGetOffScreen

Retrieves an offscreen buffer and its parameters for a specified rendering context. (Deprecated in OS X v10.7.)

CGLError CGLGetOffScreen (
   CGLContextObj ctx,
   GLsizei *width,
   GLsizei *height,
   GLint *rowbytes,
   void **baseaddr
);
Parameters
ctx

A rendering context.

width

On return, points to the width, in pixels, of the offscreen buffer. If the rendering context is not attached to an offscreen drawable object, the value of width is set to 0.

height

On return, points to the height, in pixels, of the offscreen buffer. If the rendering context is not attached to an offscreen drawable object, the value of height is set to 0.

rowbytes

On return, points to the number of bytes per row of the offscreen buffer. If the context is not attached to an offscreen drawable object, the value of rowbytes is set to 0.

baseaddr

On return, points to the base address of the offscreen buffer. If the context is not attached to an offscreen drawable object, the value of baseaddr is set to NULL.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
OpenGL.h

CGLGetPBuffer

Retrieves a pixel buffer and its parameters for a specified rendering context. (Deprecated in OS X v10.7.)

CGLError CGLGetPBuffer (
   CGLContextObj ctx,
   CGLPBufferObj *pbuffer,
   GLenum *face,
   GLint *level,
   GLint *screen
);
Parameters
ctx

A rendering context.

pbuffer

On return, points to the pixel buffer object attached to the rendering context.

face

On return, points to the cube map face that is set if the pixel buffer texture target type is GL_TEXTURE_CUBE_MAP; otherwise 0 for all other texture target types.

level

On return, points to the current mipmap level for drawing.

screen

On return, points to the current virtual screen number, as set by the last valid call to CGLSetPBuffer.

Return Value

A result code. See “CGL Result Codes.”

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.7.
See Also
Declared In
OpenGL.h

CGLGetPBufferRetainCount

Returns the retain count of a pixel buffer object. (Deprecated in OS X v10.7.)

GLuint CGLGetPBufferRetainCount (
   CGLPBufferObj pbuffer
);
Parameters
pbuffer

The pixel buffer object whose retain count you wish to retrieve.

Return Value

The retain count of the pixel buffer object.

Availability
  • Available in OS X v10.5 and later.
  • Deprecated in OS X v10.7.
Declared In
OpenGL.h

CGLReleasePBuffer

Decrements the retain count on a pixel buffer object. (Deprecated in OS X v10.7.)

void CGLReleasePBuffer (
   CGLPBufferObj pbuffer
);
Parameters
pbuffer

The pixel buffer object whose retain count you wish to decrement.

Discussion

Call this function only after you no longer need to use the pixel buffer object. Before releasing the pixel buffer object, you should delete any texture objects associated with it. You do not need to make sure that all texturing commands have completed prior to calling this function, because the OpenGL framework manages texturing synchronization.

Each call to CGLReleasePBuffer decreases the retain count by 1. When the retain count reaches 0, the pixel buffer object’s resources are freed and the object is destroyed. The results of issuing commands to a destroyed pixel buffer object are undefined.

Availability
  • Available in OS X v10.5 and later.
  • Deprecated in OS X v10.7.
Declared In
OpenGL.h

CGLRetainPBuffer

Increments the retain count on a pixel buffer object. (Deprecated in OS X v10.7.)

CGLPBufferObj CGLRetainPBuffer (
   CGLPBufferObj pbuffer
);
Parameters
pbuffer

The pixel buffer object whose retain count you wish to increment.

Return Value

The pixel buffer object that received the call.

Discussion

Each call to CGLRetainPBuffer increases the retain count by 1. To prevent the pixel buffer object from being leaked, each retain call must be matched with a call to CGLReleasePBuffer.

Availability
  • Available in OS X v10.5 and later.
  • Deprecated in OS X v10.7.
Declared In
OpenGL.h

CGLSetFullScreenOnDisplay

Attaches a rendering context to a full-screen drawable object. (Deprecated in OS X v10.7.)

CGLError CGLSetFullScreenOnDisplay (
   CGLContextObj ctx,
   GLuint display_mask
);
Parameters
ctx

A rendering context.

display_mask

A bit field that contains the OpenGL display mask for the screen you wish the context to cover.

Return Value

A result code. See “CGL Result Codes.”

Discussion

This function obtains a drawable object that covers an entire screen and attaches it to the rendering context. A full-screen rendering context may allow the underlying renderer to provide better performance compared to a context associated with a window that partially covers the screen.

Prior to calling this function, your application should ensure that the context is capable of rendering to this display by querying the appropriate renderer properties. For more information, see CGLQueryRendererInfo. Note that some renderers, including the software renderer, do not support full-screen mode.

You must capture the screen prior to entering full-screen mode and release it after exiting. After calling this function, subsequent OpenGL drawing is rendered into the entire screen. For more information, see OpenGL Programming Guide for Mac.

To exit full-screen mode, call CGLClearDrawable.

In OS X v10.6 or later, this function is not deprecated, but is usually not necessary. If your application creates a window that completely covers the screen, the system implicitly creates a full-screen instance, for the same potential performance benefit.

Availability
  • Available in OS X v10.5 and later.
  • Deprecated in OS X v10.7.
Declared In
OpenGL.h

CGLSetOffScreen

Attaches a rendering context to an offscreen buffer. (Deprecated in OS X v10.7.)

CGLError CGLSetOffScreen (
   CGLContextObj ctx,
   GLsizei width,
   GLsizei height,
   GLint rowbytes,
   void *baseaddr
);
Parameters
ctx

A rendering context.

width

The width, in pixels, of the offscreen buffer.

height

The height, in pixels, of the offscreen buffer.

rowbytes

The number of bytes per row of the offscreen buffer, which must be greater than or equal to width times bytes per pixel.

baseaddr

A pointer to a block of memory to use as the offscreen buffer. The size of the memory must be at least rowbytes*height bytes.

Return Value

A result code. See “CGL Result Codes.”

Discussion

Before calling this function, you must set up the rendering context using a pixel format object created with the kCGLPFAOffScreen attribute. For more information about kCGLPFAOffScreen, see “Buffer and Renderer Attributes.”

After calling this function, subsequent OpenGL drawing is rendered into the offscreen buffer and the viewport of the rendering context is set to the full size of the offscreen area.

To exit offscreen mode, call CGLClearDrawable.

To obtain functionality similar to offscreen mode on renderers that do not support it, attach the context to a hidden window and use the OpenGL function glReadPixels.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
OpenGL.h

CGLSetPBuffer

Attaches a pixel buffer object to a rendering context. (Deprecated in OS X v10.7.)

CGLError CGLSetPBuffer (
   CGLContextObj ctx,
   CGLPBufferObj pbuffer,
   GLenum face,
   GLint level,
   GLint screen
);
Parameters
ctx

The rendering context to attach the pixel buffer to.

pbuffer

A pixel buffer object.

face

The cube map face to draw if the pixel buffer texture target type is GL_TEXTURE_CUBE_MAP; otherwise pass 0.

level

The mipmap level to draw. This must not exceed the maximum mipmap level set when the pixel buffer object was created. Pass 0 for a texture target that does not support mipmaps.

screen

A virtual screen value. The virtual screen determines the renderer OpenGL uses to draw to the pixel buffer object. For best performance, for a pixel buffer used as a texture source, you should supply the virtual screen value that results in using the same renderer used by the context that's the texturing target.

Return Value

A result code. See “CGL Result Codes.”

Discussion

The first time you call this function for a specific pixel buffer object, the system creates the necessary buffers. The buffers are created to support the attributes dictated by the pixel format object used to create the rendering context and by the parameters used to create the pixel buffer object. The storage requirements for pixel buffer objects, which can be quite large, are very similar to the requirements for windows or views with OpenGL contexts attached. All drawable objects compete for the same scarce resources. This function can fail is there is not enough contiguous VRAM for each buffer. It's best to code defensively with a scheme that reduces resource consumption without causing the application to resort to failure. Unless, of course, failure is the only viable alternative.

The ability to attach a pixel buffer to a context is supported only on renderers that export GL_APPLE_pixel_buffer in the GL_EXTENSIONS string. Before calling this function, you should programmatically determine if it’s possible to attach a pixel buffer to a context by querying GL_EXTENSIONS in the context and looking for GL_APPLE_pixel_buffer. If that extension is not present, the renderer won’t allow setting the pixel buffer.

In order of performance, these are the renderers you should consider using when setting up a rendering context to attach to a pixel buffer:

  • A hardware renderer.

  • The generic render, but only with an offscreen pixel format and glTexSubImage.

  • The Apple software renderer, which supports pixel buffers in OS X v10.4.8 and later.

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.7.
See Also
Declared In
OpenGL.h

CGLTexImagePBuffer

Binds the contents of a pixel buffer to a data source for a texture object. (Deprecated in OS X v10.7.)

CGLError CGLTexImagePBuffer (
   CGLContextObj ctx,
   CGLPBufferObj pbuffer,
   GLenum source
);
Parameters
ctx

A rendering context, which is the target context for the texture operation. This is the context that you plan to render content to. This is not the context attached to the pixel buffer.

pbuffer

A pixel buffer object.

source

The source buffer to get the texture from, which should be a valid OpenGL buffer such as GL_FRONT or GL_BACK and should be compatible with the buffer and renderer attributes that you used to create the rendering context attached to the pixel buffer. This means that the pixel buffer must possess the buffer in question for the texturing operation to succeed.

Return Value

A result code. See “CGL Result Codes.”

Discussion

You must generate and bind a texture name (using standard OpenGL texturing calls) that is compatible with the pixel buffer texture target. Don't supply a texture object that was used previously for nonpixel buffer texturing operations unless you first call glDeleteTextures to regenerate the texture name.

If you modify the content of a pixel buffer that uses mipmap levels, you must call this function again before drawing with the pixel buffer, to ensure that the content is synchronized with OpenGL. For pixel buffers without mipmaps, simply rebind to the texture object to synchronize content.

No OpenGL texturing calls that modify a pixel buffer texture content are permitted (such as glTexSubImage2D or glCopyTexImage2D) with the pixel buffer texture as the destination. It is permitted to use texturing commands to read data from a pixel buffer texture, such as glCopyTexImage2D, with the pixel buffer texture as the source. It is also legal to use OpenGL functions such as glReadPixels to read the contents of a pixel buffer directly through the pixel buffer context.

Note that texturing with the CGLTexImagePBuffer function can fail to produce the intended results without error in the same way other OpenGL texturing commands can normally fail. The function fails if you set an incompatible filter mode, do not enable the proper texture target, or other conditions described in the OpenGL specification.

You don't need to share a context to use a pixel buffer object as a texture source. You can use independent pixel format objects and OpenGL contexts for both the pixel buffer and the target drawable object without sharing resources, and still texture using a pixel buffer in the target context.

For details on how to use a pixel buffer object as a texture source, see OpenGL Programming Guide for Mac.

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.7.
Declared In
OpenGL.h

Deprecated in OS X v10.8

CGLCopyContext

Copies the specified state variables from one rendering context to another. (Deprecated in OS X v10.8.)

CGLError CGLCopyContext (
   CGLContextObj src,
   CGLContextObj dst,
   GLbitfield mask
);
Parameters
src

The source rendering context.

dst

The destination rendering context.

mask

A mask that specifies the state variables to copy. Pass a bit field that contains the bitwise OR of the state variable names that you want to copy. Use the symbolic mask constants that are passed to the OpenGL function glPushAttrib. To copy as many state variables as possible, supply the constant GL_ALL_ATTRIB_BITS. For a description of the symbolic mask constants, see OpenGL Reference Manual.

Return Value

A result code. See “CGL Result Codes.”

Discussion

Not all OpenGL state values can be copied. For example, pixel pack and unpack state, render mode state, and select and feedback state are not copied. The state that can be copied is exactly the state that is manipulated by the OpenGL call glPushAttrib.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
OpenGL.h