Name

    INTEL_swap_event

Name Strings

    GLX_INTEL_swap_event

Contact

    Jesse Barnes, Intel Corporation (jesse.barnes 'at' intel.com)

Contributors

    Kristian Høgsberg (kristian.h.kristensen 'at' intel.com)
    Ian Romanick (ian.d.romanick 'at' intel.com)

Status

    Proof of concept implementation available for the Intel stack.

Version

    Last Modified Date: May 3, 2011

Number

    384

Dependencies

    GLX 1.3 is required.
    OML_sync_control affects the definition of this extension.

Overview

    This extension adds a new event type, GLX_BUFFER_SWAP_COMPLETE_INTEL,
    which is sent to the client via the X11 event stream and
    selected/consumed by the normal GLX event mask mechanisms, to indicate
    when a previously queued swap has completed.

New Procedures and Functions

    None

New Tokens

    Accepted by the <mask> parameter of glXSelectEvent and returned
    in the <mask> parameter of glXGetSelectedEvent:

	GLX_BUFFER_SWAP_COMPLETE_INTEL_MASK	0x04000000

    Returned in the <event_type> field of a "swap complete" event:

	GLX_EXCHANGE_COMPLETE_INTEL		0x8180
	GLX_COPY_COMPLETE_INTEL			0x8181
	GLX_FLIP_COMPLETE_INTEL			0x8182

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

    None

Additions to Chapter 3 of the 1.4 Specification (Rasterization)

    None

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

    None

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

    None

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

    None

Additions to the GLX Specification

    [Add to section 3.3.8, Events]

    A client can ask to receive swap complete GLX events on a window.

    A swap buffer event has the following format:

      typdef struct {
	int event_type;	      /* GLX_EXCHANGE_COMPLETE_INTEL,
				 GLX_COPY_COMPLETE, GLX_FLIP_COMPLETE */
	unsigned long serial; /* # of last request processed by server */
	Bool send_event;      /* event was generated by a SendEvent request */
        Display *display;     /* display the event was read from */
        GLXDrawable drawable; /* i.d. of Drawable */
	CARD64 ust;           /* UST from when the swap occurred */
	CARD64 msc;           /* MSC from when the swap occurred */
	CARD64 sbc;           /* SBC from when the swap occurred */
      } GLXBufferSwapEventINTEL;

    When an event is received, the caller can determine what kind of swap
    occurred by checking the event_type field.  Simple pixmap exchanges are
    reported with the GLX_EXCHANGE_COMPLETE_INTEL event type.  If the swap
    caused was performed with a blit from back to front, the event type will
    be GLX_COPY_COMPLETE_INTEL.  Finally, if the implementation was able to
    perform a full screen page flip, GLX_FLIP_COMPLETE_INTEL is returned.

    The mask field indicates which of the buffers in the drawable were swapped.

    The MSC, SBC and UST are the OML triple indicating information about
    when the swap occurred.

GLX Protocol

    One new event is added:

	BEC is the base event code for the extension, as returned by
	QueryExtension.

	GLX_BUFFER_SWAP_COMPLETE_INTEL_INTEL
	    1		BEC+15		code
	    1				unused
	    2		CARD16		sequence number
	    2		CARD16		event_type
			0x8180		GLX_EXCHANGE_COMPLETE_INTEL
			0x8181		GLX_COPY_COMPLETE_INTEL
			0x8182		GLX_FLIP_COMPLETE_INTEL
	    2		CARD16		unused
	    4		GLX_DRAWABLE    drawable
            8           CARD64		UST
            8           CARD64		MSC
            4           CARD32		SBC

Errors

    None

New State

    None

New Implementation Dependent State

    None

Issues

    1.  Should the event return the frame and swap count for the last swap?

        RESOLVED: YES. Also return a timestamp from when the swap occurred.

    2.  What is the difference between GLX_EXCHANGE_COMPLETE_INTEL,
        GLX_COPY_COMPLETE_INTEL and GLX_FLIP_COMPLETE_INTEL from an app
        perspective?

        RESOLVED: Semantically, none.  The fbconfig should describe whether
        back buffer contents is preserved or not.  These completion types are
        purely informational and can be used in debugging new event based
        code.

Revision History

    Version 1, 2009/11/10 - Initial spec
    
    Version 2, 2009/11/16 - Fix reply size (should be 32 bytes to match X
    replies), move issue list to end, change BLIT to COPY, return enum values

    Version 3, 2010/1/6 - Fix reply to include padding to 32 bytes.  Correct
    replies to include _INTEL suffix to match extension name.  Fix 'code'
    portion of reply to be BEC+15.  Remove open issue regarding mask and types.
    Leave sbc in GLXBufferSwapEventINTEL as 64 bits to make interoperability
    easier.

    Version 4, 2010/1/11 - Number issues.  Added issue #2 from James
    Jones (Nvidia).

    Version 5, 2010/1/14 - Word-wrap to 80-colums.  Fix enum values and
    mask value. (idr)

    Version 6, 2010/1/20 - Update extension number and publish to the
    Registry.

    Version 7, 2011/5/3 - Update GLX protocol with correct enums and correct
    location of padding.  GLX protocol requires that CARD32 (and larger) be
    4-byte aligned.  Previously the drawable (and all later fields) were only
    2-byte aligned.  Most compilers would generally add padding in the correct
    place anyway. (idr)
