NSOpenGLPixelBuffer Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.3 and later.
Companion guide
Cocoa Drawing Guide
Declared in
NSOpenGL.h
Related sample code

Overview

The NSOpenGLPixelBuffer class gives Cocoa OpenGL implementations access to accelerated offscreen rendering. With this offscreen rendering you could, for instance, draw into the pixel buffer, then use the contents as a texture map elsewhere. Typically you initialize an NSOpenGLPixelBuffer object using the initWithTextureTarget:textureInternalFormat:textureMaxMipMapLevel:pixelsWide:pixelsHigh: method and attach the resulting object to an OpenGL context with the setPixelBuffer:cubeMapFace:mipMapLevel:currentVirtualScreen: method of NSOpenGLContext.

Every NSOpenGLPixelBuffer object wraps a low-level, platform-specific Core OpenGL (CGL) pixel buffer object. Your application can retrieve the CGL pixel buffer by calling the CGLPBufferObj method. For more information on the underling CGL pixel buffer, see CGL Reference.

Tasks

Initializing an OpenGL Pixel Buffer

Obtaining Information About an OpenGL Pixel Buffer

Instance Methods

CGLPBufferObj

Returns the underlying CGLPBufferObj object associated with the NSOpenGLPixelBuffer object.

- (void *)CGLPBufferObj
Return Value

The CGL pixel buffer object that encapsulates the actual pixel buffer.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSOpenGL.h

initWithCGLPBufferObj:

Initializes and returns an NSOpenGLPixelBuffer object that encapsulates an existing CGL pixel buffer object.

- (id)initWithCGLPBufferObj:(void *)pbuffer
Parameters
pbuffer

The CGL pixel buffer object to wrap.

Return Value

An initialized NSOpenGLPixelBuffer object.

Discussion

If your application already has a CGL pixel buffer object, you can wrap it inside an NSOpenGLPixelBuffer object by using this initializer. This method retains the CGL pixel buffer object by calling the CGLRetainPBuffer function.

Your application should not call CGLDestroyPBuffer to dispose of the CGL pixel buffer object. Instead, your application should call CGLReleasePBuffer to decrement its reference count.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSOpenGL.h

initWithTextureTarget:textureInternalFormat:textureMaxMipMapLevel:pixelsWide:pixelsHigh:

Returns an NSOpenGLPixelBuffer object initialized with the specified parameters.

- (id)initWithTextureTarget:(GLenum)target textureInternalFormat:(GLenum)format textureMaxMipMapLevel:(GLint)maxLevel pixelsWide:(GLsizei)pixelsWide pixelsHigh:(GLsizei)pixelsHigh
Parameters
target

The texture object. This value should be one of the following: GL_TEXTURE_2D,GL_TEXTURE_CUBE_MAP, or GL_TEXTURE_RECTANGLE_EXT.

format

The base internal format of the texture. This value should be GL_RGB, GL_RGBA, or GL_DEPTH_COMPONENT.

maxLevel

The desired maximum mipmap level of the structure, starting with zero.

pixelsWide

The width of the texture (in pixels) in the pixel buffer.

pixelsHigh

The height of the texture (in pixels) in the pixel buffer.

Return Value

An initialized NSOpenGLPixelBuffer object or nil if the initialization failed. Initialization can fail if there is inconsistency among the parameter values. See the OpenGL documentation for glTexImage2D for more information.

Discussion

The value you pass to the target parameter defines several other constraints that are then applied to the remaining parameters. The list below gives the values you can pass to target and the additional constraints.

  • GL_TEXTURE_2D

  • GL_TEXTURE_CUBE_MAP - the values in pixelsWide and pixelsHigh must be equal.

  • GL_TEXTURE_RECTANGLE_EXT - maxLevel must be zero.

Normally, when using the GL_TEXTURE_2D and GL_TEXTURE_CUBE_MAP targets, you must specify width and height values that are powers of two. When the ARB_texture_non_power_of_two extension is present, however, some types of hardware can support values that are not powers of two. You should check for the presence of this extension before specifying non power-of-two values.

If the texture map cannot be created, you can use the glGetError function to get the error code.

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
NSOpenGL.h

pixelsHigh

Returns the height of the receiver’s texture (in pixels).

- (GLsizei)pixelsHigh
Return Value

The height of the texture (in pixels).

Availability
  • Available in OS X v10.3 and later.
See Also
Related Sample Code
Declared In
NSOpenGL.h

pixelsWide

Returns the width of the receiver’s texture (in pixels).

- (GLsizei)pixelsWide
Return Value

The width of the texture (in pixels).

Availability
  • Available in OS X v10.3 and later.
See Also
Related Sample Code
Declared In
NSOpenGL.h

textureInternalFormat

Returns the internal format of the receiver’s texture.

- (GLenum)textureInternalFormat
Return Value

The texture format, which can be one of the following values: GL_RGB, GL_RGBA, or GL_DEPTH_COMPONENT.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSOpenGL.h

textureMaxMipMapLevel

Returns the maximum mipmap level of the receiver’s texture.

- (GLint)textureMaxMipMapLevel
Return Value

The maximum mipmap level.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSOpenGL.h

textureTarget

Returns the texture target of the receiver.

- (GLenum)textureTarget
Return Value

The texture target, which can be one of the following values: GL_TEXTURE_2D, GL_TEXTURE_CUBE_MAP, or GL_TEXTURE_RECTANGLE_EXT.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSOpenGL.h


© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-08-13)

Did this document help you? Yes It's good, but... Not helpful...