Mac Developer Library

Developer

AppKit Framework Reference NSOpenGLPixelFormat Class Reference

Options
Deployment Target:

On This Page
Language:

NSOpenGLPixelFormat

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

To render with OpenGL into an NSOpenGLContext, you must specify the context’s pixel format. An NSOpenGLPixelFormat object specifies the types of buffers and other attributes of the NSOpenGLContext. This class is similar to the AGLPixelFormat type, which is used in Carbon OpenGL applications.

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

  • Returns an NSOpenGLPixelFormatobject initialized with using an existing CGL pixel format object.

    Declaration

    Swift

    init!(CGLPixelFormatObj format: COpaquePointer)

    Objective-C

    - (NSOpenGLPixelFormat *)initWithCGLPixelFormatObj:(struct _CGLPixelFormatObject *)format

    Parameters

    format

    An existing CGL pixel format object.

    Return Value

    An intialized NSOpenGLPixelFormat object that wraps the CGL pixel format object.

    Discussion

    If your application already has a low-level CGL pixel format object, you can create an NSOpenGLPixelFormat object to wrap it by calling this initializer. The NSOpenGLPixelFormat object retains the CGL pixel format object by calling the CGLRetainPixelFormat function.

    Your application should not call CGLDestroyPixelFormat to dispose of the CGL pixel format object. Instead, your application should call CGLReleasePixelFormat to decrement its reference count.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Returns an NSOpenGLPixelFormat object initialized with specified pixel format attribute data.

    Deprecation Statement

    Use initWithAttributes: instead.

    Declaration

    Objective-C

    - (id)initWithData:(NSData *)attribs

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Returns an NSOpenGLPixelFormat object initialized with specified pixel format attributes.

    Declaration

    Swift

    init!(attributes attribs: UnsafePointer<NSOpenGLPixelFormatAttribute>)

    Objective-C

    - (instancetype)initWithAttributes:(const NSOpenGLPixelFormatAttribute *)attribs

    Parameters

    attribs

    A 0-terminated array containing Boolean and integer attribute constants. The presence of a Boolean attribute implies a value of YEStrue while its absence implies a value of NOfalse. Integer constants must be followed by the desired value. For a listing of attribute constants, see the table in Constants.

    Return Value

    An initialized NSOpenGLPixelFormat object whose attributes match the desired attributes as close as possible, or nil if an object with the desired attributes could not be initialized.

    Discussion

    On return, the Boolean attributes of the receiver match the values specified in attribs, and the integer attributes are as close to the specified values as can be provided by the system.

    The existence of a Boolean attribute constant in attribs implies a YEStrue value. The Boolean attribute constants are:

    • NSOpenGLPFAAllRenderers

    • NSOpenGLPFADoubleBuffer

    • NSOpenGLPFAStereo

    • NSOpenGLPFAMinimumPolicy

    • NSOpenGLPFAMaximumPolicy

    • NSOpenGLPFAOffScreen

    • NSOpenGLPFAFullScreen

    • NSOpenGLPFASingleRenderer

    • NSOpenGLPFANoRecovery

    • NSOpenGLPFAAccelerated

    • NSOpenGLPFAClosestPolicy

    • NSOpenGLPFARobust

    • NSOpenGLPFABackingStore

    • NSOpenGLPFAWindow

    • NSOpenGLPFAMultiScreen

    • NSOpenGLPFACompliant

    • NSOpenGLPFAPixelBuffer

    The integer constants must be followed by a value. These constants are:

    • NSOpenGLPFAAuxBuffers

    • NSOpenGLPFAColorSize

    • NSOpenGLPFAAlphaSize

    • NSOpenGLPFADepthSize

    • NSOpenGLPFAStencilSize

    • NSOpenGLPFAAccumSize

    • NSOpenGLPFARendererID

    • NSOpenGLPFAScreenMask

    This code fragment creates a double-buffered pixel format with a 32-bit depth buffer:

    • NSOpenGLPixelFormatAttribute attrs[] =
    • {
    • NSOpenGLPFADoubleBuffer,
    • NSOpenGLPFADepthSize, 32,
    • 0
    • };
    • NSOpenGLPixelFormat* pixFmt = [[NSOpenGLPixelFormat alloc] initWithAttributes:attrs];
    • /* Check if initWithAttributes succeeded. */
    • if(pixFmt == nil) {
    • /* initWithAttributes failed. Try to alloc/init with a different list of attributes. */
    • }

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the low-level, platform-specific Core OpenGL (CGL) pixel format object represented by the receiver.

    Declaration

    Swift

    var CGLPixelFormatObj: COpaquePointer { get }

    Objective-C

    @property(readonly) struct _CGLPixelFormatObject *CGLPixelFormatObj

    Return Value

    A pointer to the underlying CGLPixelFormatObj object.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Gets the value for the specified pixel format attribute.

    Declaration

    Swift

    func getValues(_ vals: UnsafeMutablePointer<GLint>, forAttribute attrib: NSOpenGLPixelFormatAttribute, forVirtualScreen screen: GLint)

    Objective-C

    - (void)getValues:(GLint *)vals forAttribute:(NSOpenGLPixelFormatAttribute)attrib forVirtualScreen:(GLint)screen

    Parameters

    vals

    On input, a pointer to a long variable. On output, the variable contains the value of the requested attribute.

    attrib

    The requested attribute. For a list of attribute constants, see the table in Constants.

    screen

    The screen from which you want to retrieve the attribute. This parameter must be a value between 0 and the number of virtual screens (numberOfVirtualScreens) minus 1.

    Discussion

    Because the value for an attribute may be different on each virtual screen, the virtual screen must be specified along with the attribute.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the number of virtual screens associated with the receiver.

    Declaration

    Swift

    var numberOfVirtualScreens: GLint { get }

    Objective-C

    @property(readonly) GLint numberOfVirtualScreens

    Return Value

    The number of virtual screens.

    Discussion

    When the attributes are set, OpenGL searches for drivers matching the requested attributes. Each matching driver drives a set of displays. For example, a graphics card in a portable computer might drive the internal screen and an external display. This portable computer would have one virtual screen. A desktop computer might have two different graphics cards, each driving one or more displays. The pairing of an OpenGL driver with its set of associated displays corresponds to one virtual screen. In the above examples, the portable computer would have one virtual screen, while the desktop computer would have two. Another desktop computer with a video card driving two displays at once would have one virtual screen.

    For more information on virtual screens, consult OpenGL Programming Guide for Mac.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • attributes - attributes (OS X v10.6)

    Retrieves the attribute data for the pixel format object.

    Deprecation Statement

    Declaration

    Objective-C

    - (NSData *)attributes

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Sets the attribute data for the pixel format object.

    Deprecation Statement

    Declaration

    Objective-C

    - (void)setAttributes:(NSData *)attribs

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

Data Types

  • The following attribute names are used by initWithAttributes: and getValues:forAttribute:forVirtualScreen::

    Declaration

    Swift

    typealias NSOpenGLPixelFormatAttribute = UInt32

    Objective-C

    enum { NSOpenGLPFAAllRenderers = 1, NSOpenGLPFATripleBuffer = 3, NSOpenGLPFADoubleBuffer = 5, NSOpenGLPFAStereo = 6, NSOpenGLPFAAuxBuffers = 7, NSOpenGLPFAColorSize = 8, NSOpenGLPFAAlphaSize = 11, NSOpenGLPFADepthSize = 12, NSOpenGLPFAStencilSize = 13, NSOpenGLPFAAccumSize = 14, NSOpenGLPFAMinimumPolicy = 51, NSOpenGLPFAMaximumPolicy = 52, NSOpenGLPFAOffScreen = 53, NSOpenGLPFAFullScreen = 54, NSOpenGLPFASampleBuffers = 55, NSOpenGLPFASamples = 56, NSOpenGLPFAAuxDepthStencil = 57, NSOpenGLPFAColorFloat = 58, NSOpenGLPFAMultisample = 59, NSOpenGLPFASupersample = 60, NSOpenGLPFASampleAlpha = 61, NSOpenGLPFARendererID = 70, NSOpenGLPFASingleRenderer = 71, NSOpenGLPFANoRecovery = 72, NSOpenGLPFAAccelerated = 73, NSOpenGLPFAClosestPolicy = 74, NSOpenGLPFARobust = 75, NSOpenGLPFABackingStore = 76, NSOpenGLPFAMPSafe = 78, NSOpenGLPFAWindow = 80, NSOpenGLPFAMultiScreen = 81, NSOpenGLPFACompliant = 83, NSOpenGLPFAScreenMask = 84, NSOpenGLPFAPixelBuffer = 90, NSOpenGLPFARemotePixelBuffer = 91, NSOpenGLPFAAllowOfflineRenderers = 96, NSOpenGLPFAAcceleratedCompute = 97, NSOpenGLPFAOpenGLProfile = 99, NSOpenGLPFAVirtualScreenCount = 128 }; typedef uint32_t NSOpenGLPixelFormatAttribute;

    Constants

    • NSOpenGLPFAAllRenderers

      NSOpenGLPFAAllRenderers

      A Boolean attribute. If present, this attribute indicates that the pixel format selection is open to all available renderers, including debug and special-purpose renderers that are not OpenGL compliant.

      Available in OS X v10.0 and later.

    • NSOpenGLPFADoubleBuffer

      NSOpenGLPFADoubleBuffer

      A Boolean attribute. If present, this attribute indicates that only double-buffered pixel formats are considered. Otherwise, only single-buffered pixel formats are considered.

      Available in OS X v10.0 and later.

    • NSOpenGLPFATripleBuffer

      NSOpenGLPFATripleBuffer

      A Boolean attribute. If present, this attribute indicates that only triple-buffered pixel formats are considered. Otherwise, only single-buffered pixel formats are considered.

      Available in OS X v10.7 and later.

    • NSOpenGLPFAStereo

      NSOpenGLPFAStereo

      A Boolean attribute. If present, this attribute indicates that only stereo pixel formats are considered. Otherwise, only monoscopic pixel formats are considered.

      Available in OS X v10.0 and later.

    • NSOpenGLPFAAuxBuffers

      NSOpenGLPFAAuxBuffers

      Value is a nonnegative integer that indicates the desired number of auxiliary buffers. Pixel formats with the smallest number of auxiliary buffers that meets or exceeds the specified number are preferred.

      Available in OS X v10.0 and later.

    • NSOpenGLPFAColorSize

      NSOpenGLPFAColorSize

      Value is a nonnegative buffer size specification. A color buffer that most closely matches the specified size is preferred. If unspecified, OpenGL chooses a color size that matches the screen.

      Available in OS X v10.0 and later.

    • NSOpenGLPFAAlphaSize

      NSOpenGLPFAAlphaSize

      Value is a nonnegative buffer size specification. An alpha buffer that most closely matches the specified size is preferred.

      Available in OS X v10.0 and later.

    • NSOpenGLPFADepthSize

      NSOpenGLPFADepthSize

      Value is a nonnegative depth buffer size specification. A depth buffer that most closely matches the specified size is preferred.

      Available in OS X v10.0 and later.

    • NSOpenGLPFAStencilSize

      NSOpenGLPFAStencilSize

      Value is a nonnegative integer that indicates the desired number of stencil bitplanes. The smallest stencil buffer of at least the specified size is preferred.

      Available in OS X v10.0 and later.

    • NSOpenGLPFAAccumSize

      NSOpenGLPFAAccumSize

      Value is a nonnegative buffer size specification. An accumulation buffer that most closely matches the specified size is preferred.

      Available in OS X v10.0 and later.

    • NSOpenGLPFAMinimumPolicy

      NSOpenGLPFAMinimumPolicy

      A Boolean attribute. If present, this attribute indicates that the pixel format choosing policy is altered for the color, depth, and accumulation buffers such that only buffers of size greater than or equal to the desired size are considered.

      Available in OS X v10.0 and later.

    • NSOpenGLPFAMaximumPolicy

      NSOpenGLPFAMaximumPolicy

      A Boolean attribute. If present, this attribute indicates that the pixel format choosing policy is altered for the color, depth, and accumulation buffers such that, if a nonzero buffer size is requested, the largest available buffer is preferred.

      Available in OS X v10.0 and later.

    • NSOpenGLPFAOffScreen

      NSOpenGLPFAOffScreen

      A Boolean attribute. If present, this attribute indicates that only renderers that are capable of rendering to an offscreen memory area and have buffer depth exactly equal to the desired buffer depth are considered. The NSOpenGLPFAClosestPolicy attribute is implied.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.7.

    • NSOpenGLPFAFullScreen

      NSOpenGLPFAFullScreen

      A Boolean attribute. If present, this attribute indicates that only renderers that are capable of rendering to a full-screen drawable are considered. The NSOpenGLPFASingleRenderer attribute is implied.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.6.

    • NSOpenGLPFASampleBuffers

      NSOpenGLPFASampleBuffers

      Value is a nonnegative number indicating the number of multisample buffers.

      Available in OS X v10.2 and later.

    • NSOpenGLPFASamples

      NSOpenGLPFASamples

      Value is a nonnegative indicating the number of samples per multisample buffer.

      Available in OS X v10.2 and later.

    • NSOpenGLPFAAuxDepthStencil

      NSOpenGLPFAAuxDepthStencil

      Each auxiliary buffer has its own depth stencil.

      Available in OS X v10.2 and later.

    • NSOpenGLPFAColorFloat

      NSOpenGLPFAColorFloat

      A Boolean attribute. If present, this attribute indicates that only renderers that are capable using buffers storing floating point pixels are considered. This should be accompanied by a NSOpenGLPFAColorSize of 64 (for half float pixel components) or 128 (for full float pixel components). Note, not all hardware supports floating point color buffers thus the returned pixel format could be NULL.

      Available in OS X v10.4 and later.

    • NSOpenGLPFAMultisample

      NSOpenGLPFAMultisample

      A Boolean attribute. If present and used with NSOpenGLPFASampleBuffers and NSOpenGLPFASamples, this attribute hints to OpenGL to prefer multi-sampling. Multi-sampling will sample textures at the back buffer dimensions vice the multi-sample buffer dimensions and use that single sample for all fragments with coverage on the back buffer location. This means less total texture samples than with super-sampling (by a factor of the number of samples requested) and will likely be faster though less accurate (texture sample wise) than super-sampling. If the underlying video card does not have enough VRAM to support this feature, this hint does nothing.

      The NSOpenGLPFASampleBuffers and NSOpenGLPFASamples attributes must be configured to request anti-aliasing as follows:

      • NSOpenGLPFAMultisample,
      • NSOpenGLPFASampleBuffers, (NSOpenGLPixelFormatAttribute)1
      • NSOpenGLPFASamples, (NSOpenGLPixelFormatAttribute)4,

      If after adding these options, multisamping still does not work, try removing the NSOpenGLPFAPixelBuffer attribute (if present). Some graphics cards may not support this option in specific versions of OS X. If removing the attribute still does not enable multisampling, try adding the NSOpenGLPFANoRecovery attribute.

      Available in OS X v10.4 and later.

    • NSOpenGLPFASupersample

      NSOpenGLPFASupersample

      A Boolean attribute. If present and used with NSOpenGLPFASampleBuffers and NSOpenGLPFASamples, this attribute hints to OpenGL to prefer super-sampling. Super-sampling will process fragments with a texture sample per fragment and would likely be slower than multi-sampling. If the pixel format is not requesting anti-aliasing, this hint does nothing.

      Available in OS X v10.4 and later.

    • NSOpenGLPFASampleAlpha

      NSOpenGLPFASampleAlpha

      A Boolean attribute. If present and used with NSOpenGLPFASampleBuffers and NSOpenGLPFASampleBuffers, this attribute hints to OpenGL to update multi-sample alpha values to ensure the most accurate rendering. If pixel format is not requesting anti-aliasing then this hint does nothing.

      Available in OS X v10.4 and later.

    • NSOpenGLPFARendererID

      NSOpenGLPFARendererID

      Value is a nonnegative renderer ID number. OpenGL renderers that match the specified ID are preferred. Constants to select specific renderers are provided in the CGLRenderers.h header of the OpenGL framework. Of note is kCGLRendererGenericID which selects the Apple software renderer. The other constants select renderers for specific hardware vendors.

      Available in OS X v10.0 and later.

    • NSOpenGLPFASingleRenderer

      NSOpenGLPFASingleRenderer

      A Boolean attribute. If present, this attribute indicates that a single rendering engine is chosen. On systems with multiple screens, this disables OpenGL’s ability to drive different monitors through different graphics accelerator cards with a single context. This attribute is not generally useful.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • NSOpenGLPFANoRecovery

      NSOpenGLPFANoRecovery

      A Boolean attribute. If present, this attribute indicates that OpenGL’s failure recovery mechanisms are disabled. Normally, if an accelerated renderer fails due to lack of resources, OpenGL automatically switches to another renderer. This attribute disables these features so that rendering is always performed by the chosen renderer. This attribute is not generally useful.

      Available in OS X v10.0 and later.

    • NSOpenGLPFAAccelerated

      NSOpenGLPFAAccelerated

      A Boolean attribute. If present, this attribute indicates that only hardware-accelerated renderers are considered. If not present, accelerated renderers are still preferred.

      Available in OS X v10.0 and later.

    • NSOpenGLPFAClosestPolicy

      NSOpenGLPFAClosestPolicy

      A Boolean attribute. If present, this attribute indicates that the pixel format choosing policy is altered for the color buffer such that the buffer closest to the requested size is preferred, regardless of the actual color buffer depth of the supported graphics device.

      Available in OS X v10.0 and later.

    • NSOpenGLPFARobust

      NSOpenGLPFARobust

      A Boolean attribute. If present, this attribute indicates that only renderers that do not have any failure modes associated with a lack of video card resources are considered. This attribute is not generally useful.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSOpenGLPFABackingStore

      NSOpenGLPFABackingStore

      A Boolean attribute. If present, this attribute indicates that OpenGL only considers renderers that have a back color buffer the full size of the drawable (regardless of window visibility) and that guarantee the back buffer contents to be valid after a call to NSOpenGLContext object’s flushBuffer.

      Available in OS X v10.0 and later.

    • NSOpenGLPFAMPSafe

      NSOpenGLPFAMPSafe

      A Boolean attribute. If present, this attribute indicates that the renderer is multi-processor safe.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSOpenGLPFAWindow

      NSOpenGLPFAWindow

      A Boolean attribute. If present, this attribute indicates that only renderers that are capable of rendering to a window are considered. This attribute is implied if neither NSOpenGLPFAFullScreen nor NSOpenGLPFAOffScreen is specified.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • NSOpenGLPFAMultiScreen

      NSOpenGLPFAMultiScreen

      A Boolean attribute. If present, this attribute indicates that only renderers capable of driving multiple screens are considered. This attribute is not generally useful.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • NSOpenGLPFACompliant

      NSOpenGLPFACompliant

      A Boolean attribute. If present, this attribute indicates that pixel format selection is only open to OpenGL-compliant renderers. This attribute is implied unless NSOpenGLPFAAllRenderers is specified. This attribute is not useful in the attribute array.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • NSOpenGLPFAScreenMask

      NSOpenGLPFAScreenMask

      Value is a bit mask of supported physical screens. All screens specified in the bit mask are guaranteed to be supported by the pixel format. Screens not specified in the bit mask may still be supported. The bit mask is managed by the CoreGraphics’s DirectDisplay, available in the CGDirectDisplay.h header of the ApplicationServices umbrella framework. A CGDirectDisplayID must be converted to an OpenGL display mask using the function CGDisplayIDToOpenGLDisplayMask. This attribute is not generally useful.

      Available in OS X v10.0 and later.

    • NSOpenGLPFAPixelBuffer

      NSOpenGLPFAPixelBuffer

      A Boolean attribute. If present, this attribute indicates that rendering to a pixel buffer is enabled.

      Available in OS X v10.3 and later.

      Deprecated in OS X v10.7.

    • NSOpenGLPFARemotePixelBuffer

      NSOpenGLPFARemotePixelBuffer

      A Boolean attribute. If present, this attribute indicates that rendering to a pixel buffer on an offline renderer is enabled.

      Available in OS X v10.3 and later.

      Deprecated in OS X v10.7.

    • NSOpenGLPFAAllowOfflineRenderers

      NSOpenGLPFAAllowOfflineRenderers

      A Boolean attribute. If present, this attribute indicates that offline renderers may be used.

      Available in OS X v10.5 and later.

    • NSOpenGLPFAAcceleratedCompute

      NSOpenGLPFAAcceleratedCompute

      If present, this attribute indicates that only renderers that can execute OpenCL programs should be used.

      Available in OS X v10.6 and later.

    • NSOpenGLPFAOpenGLProfile

      NSOpenGLPFAOpenGLProfile

      The associated value can be any of the constants defined in NSOpenGLPFAOpenGLProfile Values. If it is present in the attribute arrays, only renderers capable of supporting an OpenGL context that provides the functionality promised by the profile are considered.

      Available in OS X v10.7 and later.

    • NSOpenGLPFAVirtualScreenCount

      NSOpenGLPFAVirtualScreenCount

      The number of virtual screens in this format.

      Available in OS X v10.2 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Defines constants that specify the functionality provided by the renderer.

    Declaration

    Swift

    var NSOpenGLProfileVersionLegacy: Int { get } var NSOpenGLProfileVersion3_2Core: Int { get }

    Objective-C

    /* NSOpenGLPFAOpenGLProfile values */ enum { NSOpenGLProfileVersionLegacy = 0x1000, NSOpenGLProfileVersion3_2Core = 0x3200 };

    Constants

    • NSOpenGLProfileVersionLegacy

      NSOpenGLProfileVersionLegacy

      The requested profile is a legacy (pre-OpenGL 3.0) profile.

      Available in OS X v10.7 and later.

    • NSOpenGLProfileVersion3_2Core

      NSOpenGLProfileVersion3_2Core

      The requested profile must implement the OpenGL 3.2 core functionality.

      Available in OS X v10.7 and later.

    Discussion

    An OpenGL Profile is requested as part of the pixel format attributes string. When a context is created for a profile, the context must at least implement the requested version of the OpenGL specification. The context may implement a different version of the OpenGL specification as long as the version it implements is compatible with the requested version.