Mailing Lists: Apple Mailing Lists
Image of Mac OS face in stamp
 
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: GL_APPLE_pixel_buffer (pt3)

Preliminary PBuffer Documentation (Pt3):

API Reference:
Note: These descriptions apply equally well to the AGL interface.

CGLError CGLCreatePBuffer
(long width, long height, unsigned long target, unsigned long
internalFormat, long max_level, CGLPBufferObj *pbuffer);

Parameter Descriptions
width
The width of the new Pbuffers image area in pixels.
height
The height of the new Pbuffers image area in pixels.
target
The OpenGL texture target, currently GL_TEXTURE_2D,
GL_TEXTURE_RECTANGLE_EXT, or GL_TEXTURE_CUBE_MAP are supported
internalFormat
A constant that specifies the new Pbuffers internal color format
which should be either GL_RGB or GL_RGBA
max_level
The maximum level of mipmap detail; pass 0 if only the base level is
used.
pbuffer
On return, a handle to a CGLPBufferObject struct, which is opaque.
function result
An error code; returns 0 if successful.

Description
Creates a Pixel Buffer of specified size that is compatible with
specified texture target. The internalFormat parameter, which should
be GL_RGB or GL_RGBA, controls whether the alpha channel of the PBuffer
will be used for texturing operations. Max_level similarly controls
the creation of mipmap levels and sets the limit on the maximum mipmap
levels usage when texturing from the PBuffer. Max_level should never
exceed the actual maximum number of mipmap levels representable with
the given width and height. For PBuffers without mipmaps, clients
should specify 0 for the max_level and all other PBuffer API should use
0 when referring to a mipmap level. The newly created pixel buffer is
returned in the memory pointed to by the pbuffer parameter. On exit
the function will return 0 for success with no errors or a CGLError
code for failures. Clients should note that this function does not
have any knowledge of OpenGL contexts or pixel formats and does not
specifically allocate the storage needed for the actual pixel buffers,
that occurs when CGLSetPBuffer is called.


Errors
kCGLBadAlloc: cannot allocate storage for the basic PBuffer data
structure.

kCGLBadValue: Non-power of two width or height used with GL_TEXTURE_2D
or GL_TEXTURE_CUBE_MAP targets. Negative max_level provided or
max_level greater than the maximum possible mipmap levels for the width
and height provided. Max_level other than zero used with
GL_TEXTURE_RECTANGLE_EXT as the target. Non-square values provided for
GL_TEXTURE_CUBE_MAP target.

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

CGLError CGLDestroyPBuffer
(CGLPBufferObj pbuffer);

Parameter Descriptions
pbuffer
A handle to the opaque CGLPBufferObj struct.
function result
An error code; returns 0 if successful.

Description
Destroys an existing PBuffer. This should be called once use of the
PBuffer is finished. It is recommended that clients delete texture
objects associated with PBuffers prior to destroying the associated
PBuffer. This will ensure these textures are not used once the PBuffer
is destroyed. This ensures problem free behavior on all versions of
the PBuffer API but a client is still not require to ensure all
texturing commands have completed prior to calling CGLDestroyPBuffer as
the OpenGL framework will manage texturing synchronization. On exit
the function will return 0 for success with no errors or a CGLError
code for failures. Behavior of commands issued using a destroyed
PBuffer object are undefined.

Errors
kCGLBadAddress: NULL passed in for pbuffer.

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

CGLError CGLDescribePBuffer
(CGLPBufferObj obj, long *width, long *height, unsigned long
*target, unsigned long *internalFormat, long *mipmap);

Parameter Descriptions
obj
A handle to the opaque CGLPBufferObj struct.
width
On return the memory pointed to contains the width of the Pbuffers
image area in pixels.
height
On return the memory pointed to contains the height of the Pbuffers
image area in pixels.
target
On return the memory pointed to contains a constant that specifies the
type of the Pbuffers target texture.
Currently will return either GL_TEXTURE_2D, GL_TEXTURE_RECTANGLE_EXT
or GL_TEXTURE_CUBE_MAP
internalFormat
On return the memory pointed to contains a constant that specifies the
new Pbuffers internal color format.
Which will be either GL_RGB or GL_RGBA
mipmap
On return the memory pointed to contains the Pbuffers current mipmap
level, which is 0 if mipmapping is not used.
function result
An error code; returns 0 if successful.

Description
Describes the state of the PBuffer. Upon return the pointers provided
by the client will contain width, height, texture target, internal
texture color format and current mipmap level. Note, width, height,
texture target, and internal texture color format are set on PBuffer
creation and cannot be changed without destroying and recreating the
PBuffer. Current mipmap level is set when attaching to the PBuffer's
drawable with CGLSetPBuffer and will reflect the level parameter
provided in the last successful CGLSetPBuffer command.

Errors
kCGLBadAddress: NULL passed in for pbuffer.
---
Geoff Stahl
3D Software Engineer
Apple
_______________________________________________
mac-opengl mailing list | email@hidden
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/mac-opengl
Do not post admin requests to the list. They will be ignored.



Visit the Apple Store online or at retail locations.
1-800-MY-APPLE

Contact Apple | Terms of Use | Privacy Policy

Copyright © 2007 Apple Inc. All rights reserved.