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: January 6, 2010

Number

    382

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	0x10000000

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

	GLX_EXCHANGE_COMPLETE_INTEL		0x8024
	GLX_COPY_COMPLETE_INTEL			0x8025
	GLX_FLIP_COMPLETE_INTEL			0x8026

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
			0x8024		GLX_EXCHANGE_COMPLETE_INTEL
			0x8025		GLX_COPY_COMPLETE_INTEL
			0x8026		GLX_FLIP_COMPLETE_INTEL
	    4		GLX_DRAWABLE    drawable
            8           CARD64		UST
            8           CARD64		MSC
            4           CARD32		SBC
	    2		CARD16		unused

Errors

    None

New State

    None

New Implementation Dependent State

    None

Issues

    * Should the event return the frame and swap count for the last swap?

    JB Yes, along with a timestamp from when the swap occurred.

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

    JB 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.