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 (pt4)

Preliminary PBuffer Documentation (Pt4):

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

CGLError CGLTexImagePBuffer
(CGLContextObj ctx, CGLPBufferObj pbuffer, unsigned long source);

Parameter Descriptions
ctx
A pointer to an opaque CGLPContextObj struct.
pbuffer
A pointer to the opaque CGLPBufferObj struct returned by
CGLCreatePBuffer.
source
The source OpenGL buffer to texture from. This must be a valid buffer
defined in the pixel buffers pixel format.
function result
An error code; returns 0 if successful.

Description
Equivalent to glTexImage2D for a PBuffer drawable. Clients should
issue this command with ctx being the TARGET context for the texture
operation, which is normally not the PBuffer's context. In other
words, this command should be issued using the context that a client is
drawing into and which will use the PBuffer data as the source of for
the texture data. CGLTexImagePBuffer is only valid for non-default
texture objects, thus a texture name compatible with the PBuffer's
texture target will need to be generated and bound, using standard
OpenGL texturing method, prior to issuing this command. Additionally,
the texture object should not have been used previously for other
non-PBuffer texturing operation unless a glDeleteTextures was issued
and the texture name regenerated. The source parameter should be a
valid OpenGL buffer such as GL_FRONT or GL_BACK and should be
compatible with the pixel format attributes used to create the OpenGL
context associated with the PBuffer. To be clear, this means the
PBuffer must possess the buffer in question for texturing to succeed.
For example, if the pixel format used with the PBuffer is only single
buffered then one should expect texturing from the GL_BACK buffer to
fail. Again, this is the PBuffer's context and pixel format not the
drawing context that the client is texturing into.

When clients modify PBuffer content for PBuffers that contain mipmap
levels, they will need to re-issue this command prior to drawing with
the PBuffer to ensure the content is synchronized with OpenGL. For
PBuffers without mipmaps simply re-binding to the texture object will
pick up changes thus clients do not have to re-issue
CGLTexImagePBuffer.

No OpenGL texturing commands which modify a PBuffer texture content are
permitted, such as glTexSubImage2D, glCopyTexImage2D, with the PBuffer
texture as the destination. It IS permitted to use texturing commands
to read data from a PBuffer texture, such as glCopyTexImage2D, with the
PBuffer texture as the source. It is also legal to use OpenGL commands
to directly read the contents of a PBuffer via the PBuffer context,
such as glReadPixels.

Clients should note texturing with this command can fail to produce
intended results without error in the same way other OpenGL texturing
commands can normally fail to produce intended results without error,
such as clients failure to enable the proper texture target, setting an
incompatible filter mode or other conditions outlined in the OpenGL
specification.

Lastly, context resource sharing is not required for texturing from a
PBuffer. A client can have independent pixel formats and OpenGL
Contexts for both the PBuffer and the target drawable without sharing
resources and still texture using a PBuffer in the target context.


Errors
kCGLBadAddress: NULL passed in for pbuffer.

kCGLBadContext: Invalid context provided for ctx.

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

CGLError CGLSetPBuffer
(CGLContextObj ctx, CGLPBufferObj pbuffer, unsigned long face, long
level, long screen);

Parameter Descriptions
ctx
A pointer to an opaque CGLPContextObj struct.
pbuffer
A pointer to the opaque CGLPBufferObj struct returned by
CGLCreatePBuffer.
face
The cube map face to draw if the pBuffer's texture target is
GL_TEXTURE_CUBE_MAP, otherwise set to 0.
level
The mipmap level to draw. This must not exceed the maximum mipmap
level set on PBuffer creation.
screen
The virtual screen which determines the renderer used to draw to the
PBuffer.
function result
An error code; returns 0 if successful.

Description
Sets pbuffer as the target drawable for a context in a manner similar
to CGLSetFullscreen, aglSetDrawable or NOpenGLContext's setView:
method. Additionally, this command sets specific buffers as the
rendering target and controls what renderer to use via the screen
parameter. The face parameter controls which cube map face to draw and
is specified as the standard OpenGL cube map face enumerate. For
PBuffers not using GL_TEXTURE_CUBE_MAP as their texture target this
parameter should always be zero. The level parameter affects the
specific target mipmap level for rendering and should always be less
than or equal the maximum levels specified in CGLCreatePBuffer, thus
for a PBuffer not using mipmaps level should always be zero.

Screen should be set to the desired virtual screen to use when
rendering (see virtual discussion on page XX). The recommended method
for PBuffers used as a texture source is to choose the same renderer
which is used by the context that will be the texturing target by
getting the virtual screen from that context directly. The virtual
screen controls the specific renderer, hardware or otherwise, having
different virtual screens between the source PBuffer and context that
is the target of texturing may result in copying texture data from one
renderer's local storage to another, thus may not result in optimum
performance. It should be noted that this condition could be desirable
to take advantage of capabilities that may not exist on the target
renderer when drawing to the source PBuffer.

Finally, the first time this command is called the needed buffers will
be created (according to both the OpenGL context's pixel format
attributes and the parameters passed when calling CGLCreatePBuffer).
Clients should understand the storage requirements for PBuffers, which
can be quite large, are very similar to windows or views with OpenGL
contexts attached and thus compete for the same scarce resources.
Failure when setting the PBuffer as the drawable can occur, for
example, when not enough contiguous VRAM exists for each buffer needed.
Clients should take this into account and ensure they code defensively
with a scheme to reduce resource consumption without complete failure
(unless failure is the only viable alternative of course).

Errors
kCGLBadAddress: NULL passed in for pbuffer.

kCGLBadContext: Invalid context provided for ctx.

kCGLBadDrawable: Failure to successfully attach to pbuffer.

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

CGLError CGLGetPBuffer
(CGLContextObj ctx, CGLPBufferObj *pbuffer, unsigned long *face,
long *level, long *screen);

Parameter Descriptions
ctx
A pointer to an opaque CGLPContextObj struct.
pbuffer
On return, a handle to the opaque CGLPBufferObj object which is set to
the drawable for the CGLPContextObj struct passed in ctx.
face
On return, the memory pointed to contains the cube map face that is
set if the pBuffer's texture target is
GL_TEXTURE_CUBE_MAP, or 0 for all other texture targets.
level
On return, the memory pointed to contains the current mipmap level for
drawing.
screen
On return, the memory pointed to contains the current virtual screen.
function result
An error code; returns 0 if successful.

Description
Gets the current cube map face, mipmap level and virtual screen and
pbuffer for the target context (ctx). If the texture target for the
PBuffer is not GL_TEXTURE_CUBE_MAP zero will be written at the face
pointer provided, otherwise the current OpenGL cube face enumerate will
be written . Level will be the current mipmap level in which drawing
will occur, thus will be zero if mipmaps are not being used. Screen
will be the current virtual screen as set by the last valid call to
CGLSetPBuffer (see virtual discussion on page XX for more information).

Errors
kCGLBadContext: Invalid context provided for ctx.
---
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.