xref: /third_party/openGLES/extensions/SGI/GLX_SGI_make_current_read.txt

Name

    SGI_make_current_read

Name Strings

    GLX_SGI_make_current_read

Version

    $Date: 1997/03/20 02:19:19 $ $$

Number

    42

Dependencies

    EXT_copy_texture is affected by this specification.
    EXT_convolution is affected by this specification.
    SGI_color_table is affected by this specification.
    
Overview

    The association of the current context with a drawable is extended to allow
    separate write and read drawables.  This paves the way for allowing
    preprocessing of image data in an "off screen" window which is then read
    into the visible window for final display.  Similarly it sets the
    frame-work for direct transfer of video to the GL, by treating the video
    as a special kind of read drawable (a.k.a, readable).


New Procedures and Functions

    Bool glXMakeCurrentReadSGI(Display* dpy,
			       GLXDrawable draw,
			       GLXDrawable read,
			       GLXContext ctx);

    GLXDrawable glXGetCurrentReadDrawableSGI(void);

New Tokens

    None

Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation)

    None

Additions to Chapter 3 of the 1.0 Specification (Rasterization)

    None

Additions to Chapter 4 of the 1.0 Specification (Per-Fragment Operations
and the Frame buffer)

    If glXMakeCurrentReadSGI is used to associate two glXDrawables with
    the current rendering context, glXDrawable <draw> is used for all
    OpenGL operations except:

    1.	Any pixel data that are sourced based on the value of READ_BUFFER.
        Note, that accumulation operations use the value of READ_BUFFER, but
	are not allowed when <draw> in not identical to <read>.

    2.	Any depth values that are retrieved by glReadPixels, glCopyPixels,
	or any OpenGL extension that sources depth images from the frame
	buffer in the manner of glReadPixels and glCopyPixels.

    3.	Any stencil values that are retrieved by glReadPixels, glCopyPixels,
	or any OpenGL extension that sources stencil images from the frame
	buffer in the manner of glReadPixels and glCopyPixels.

    These frame buffer values are taken from glXDrawable <read>.

    No error will be generated if the value of READ_BUFFER at the time the
    glXMakeCurrentReadSGI call is made does not correspond to a valid color
    buffer in <read>.  Also, no error due to READ_BUFFER mismatch will be
    generated by subsequent calls to any of the operations enumerated above,
    but the pixels values used will be undefined until READ_BUFFER is set to a
    color buffer that is valid in the <read>.  Operations that query the value
    of READ_BUFFER (i.e., glGet, glPushAttrib) use the value set last in the
    context, independent of whether it is a valid buffer in <read>.
    Subsequent to a glXMakeCurrentRead call, it is possible that the
    READ_BUFFER may be set to a color buffer that is not valid with respect to
    the visual of the context.  The preceding discussion also applies to
    glXMakeCurrent where <read> is replaced by the single drawable parameter
    to the call.

    Error conditions set by glDrawBuffer (even when called implicitly via
    glPopAttrib) and by the operations enumerated above are with respect to
    color and ancillary buffers available in <read> (i.e.,
    glReadBuffer(GL_BACK_BUFFER) will generate an error when <read> is single
    buffered, and so will an operation that tries to source stencil images
    when <read> does not have a stencil buffer).

    The following restriction is added to the end of the introductory
    paragraph of section 4.2.4 "The Accumulation Buffer": Accumulation
    operations are only allowed when the glXDrawbles <write> and <draw> are
    identical.

    The list of error conditions at the end of section 4.2.4 "The Accumulation
    Buffer" is modified to: If there is no accumulation buffer, the GL is in
    color index mode, or if the glXDrawbles <write> and <read> are not
    identical then Accum generates the error INVALID_OPERATION.

Additions to Chapter 5 of the 1.0 Specification (Special Functions)

    None

Additions to Chapter 6 of the 1.0 Specification (State and State Requests)

    None

Additions to the GLX Specification

    XXX - not complete yet

    Notes:

    *	glXMakeCurrentReadSGIX associates two GLXDrawables with a single
	GLXContext.  BadMatch is generated if <draw> was not created with
	the same X screen and visual as <ctx>.  BadMatch is also generated
	if <read> was not created with the same X screen as <ctx>.  The color,
	depth, stencil, and accumulation buffers of <read> need not match the
	resources of <draw>.

    *	glXMakeCurrentReadSGI returns True if it succeeds, and False if it
	fails.  It can fail for myriad reasons, including refusal to accept
	a window or a GLXPixmap as the <read> GLXDrawable, and refusal to
	accept as the <read> a GLXDrawable or a GLXPbuffer with color, depth,
	stencil, or accumulation storage facilities that differ from those
	of <draw>.  This laxness may not be acceptable in a final
	specification, but it will help allow early implementations to
	be completed.

    *   glXMakeCurrentReadSGI may return False if <draw> and <read> cannot 
        exist in framebuffer memory simultaneously.

    *	glXGetCurrentReadDrawableSGI returns the name of the GLXDrawable
	currently being used as a pixel query source.  If glXMakeCurrent
	specified the current rendering context, then
	glXGetCurrentReadDrawableSGI returns the drawable specified as
	<draw> by that glXMakeCurrent call.  If glXMakeCurrentReadSGI
	specified the current rendering context, then
	glXGetCurrentReadDrawableSGI returns the drawable specified as
	<read> by that glXMakeCurrentReadSGI call.  If there is no
	current read drawable, None is returned.

GLX Protocol

	One new GLX protocol command is added.

	MakeCurrentRead
	    1		CARD8		opcode (X assigned)
	    1		17		GLX opcode (glXVendorPrivateWithReply)
	    2		6		request length
	    4		65537		vendor specific opcode
	    4		GLX_CONTEXT_TAG	old context tag
	    4		GLX_DRAWABLE	drawable
	    4		GLX_DRAWABLE	read drawable
	    4		GLX_CONTEXT	context id
	   =>
	    1		1		Reply
	    1				unused
	    2		CARD16		sequence number
	    24				unused

Dependencies on EXT_copy_texture

    Texture image data are sourced from GLXDrawable <read> if the
    current OpenGL rendering context was specified by glXMakeCurrentReadSGIX.

Dependencies on EXT_convolution

    Convolution image data are sourced from GLXDrawable <read> if the
    current OpenGL rendering context was specified by glXMakeCurrentReadSGIX,
    and the transfer is specified by CopyConvolutionFilter1DEXT or
    CopyConvolutionFilter2DEXT.

Dependencies on SGI_color_table

    Color table data are sourced from GLXDrawable <read> if the current
    OpenGL rendering context was specified by glXMakeCurrentReadSGIX,
    and the transfer is specified by CopyColorTableSGI.

New State

    None

New Implementation Dependent State

   None