# HG changeset patch # User John Tsiombikas # Date 1454055788 -7200 # Node ID 3f908f812ec79f061619d45c08d8fc9329d09a34 # Parent 86e57e56a4545fc0cf6b056b71d77cde6b5aaafb added docs diff -r 86e57e56a454 -r 3f908f812ec7 doc/compositeproto.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/compositeproto.txt Fri Jan 29 10:23:08 2016 +0200 @@ -0,0 +1,339 @@ + Composite Extension + Version 0.4 + 2007-7-3 + Keith Packard + keithp@keithp.com + Deron Johnson + deron.johnson@sun.com + +1. Introduction + +Many user interface operations would benefit from having pixel contents of +window hierarchies available without respect to sibling and antecedent +clipping. In addition, placing control over the composition of these pixel +contents into a final screen image in an external application will enable +a flexible system for dynamic application content presentation. + +2. Acknowledgements + +This small extension has been brewing for several years, contributors to +both early prototypes and the final design include: + + + Bill Haneman for motivating the ability to magnify occluded windows + with his work on accessibility + + + Carsten Haitzler for Enlightenment, the original eye-candy window + manager which demonstrated that clever hacks are an awfully + close substitute for changes in the underlying system. + + + Jim Gettys for key insights into the relationship between damage + events and per-window pixmap usage + + + Mike Harris and Owen Taylor for figuring out what to call it. + + + Deron Johnson for the Looking Glass implementation and + a prototype of the coordinate transformation mechanism. + + + Ryan Lortie for helping figure out reasonable parent clipping + semantics in the presense of manual redirected children. + +3. Architecture + +The composite extension provides three related mechanisms: + + 1. Per-hierarchy storage. The rendering of an entire hierarchy of windows + is redirected to off-screen storage. The pixels of that hierarchy + are available whenever it is viewable. Storage is automatically + reallocated when the top level window changes size. Contents beyond + the geometry of the top window are not preserved. + + 2. Automatic shadow update. When a hierarchy is rendered off-screen, + the X server provides an automatic mechanism for presenting those + contents within the parent window. The implementation is free to + make this update lag behind actual rendering operations by an + unspecified amount of time. This automatic update mechanism may + be disabled so that the parent window contents can be completely + determined by an external application. + + 3. External parent - child pointer coordinate transformation. + When a hierarchy is under manual compositing, the relationship + of coordinates within the parent to those in the child may + not be known within the X server. This mechanism provides + for redirection of these transformations through a client. + +Per-hierarchy storage may be created for individual windows or for all +children of a window. Manual shadow update may be selected by only a single +application for each window; manual update may also be selected on a +per-window basis or for each child of a window. Detecting when to update +may be done with the Damage extension. + +The off-screen storage includes the window contents, its borders and the +contents of all descendants. + +3.1 NameWindowPixmap + +Version 0.2 of the protocol introduces a mechanism for associating an XID +with the off-screen pixmap used to store these contents. This can be used +to hold onto window contents after the window is unmapped (and hence animate +it's disappearance), and also to access the border of the window, which is +not reachable through the Window ID itself. A new pixmap is created each +time the window is mapped or resized; as these events are nicely signalled +with existing events, no additional notification is needed. The old pixmap +will remain allocated as long as the Pixmap ID is left valid, it is +important that the client use the FreePixmap request when it is done with +the contents and to create a new name for the newly allocated pixmap. + +In automatic update mode, the X server is itself responsible for presenting +the child window contents within the parent. It seems reasonable, then, for +rendering to the parent window to be clipped so as not to interfere with any +child window content. In an environment with a mixure of manual and +automatic updating windows, rendering to the parent in the area nominally +occupied by a manual update window should be able to affect parent pixel +values in those areas, but such rendering should be clipped to automatic +update windows, and presumably to other manual update windows managed by +other applications. In any of these cases, it should be easy to ensure that +rendering has no effect on any non-redirected windows. + +Instead of attempting to define new clipping modes for rendering, the +Composite extension instead defines ClipByChildren rendering to the parent +to exclude regions occupied by redirected windows (either automatic or +manual). The CreateRegionFromBorderClip request can be used along with +IncludeInferiors clipping modes to restrict manual shadow updates to the +apporpriate region of the screen. Bracketing operations with +GrabServer/UngrabServer will permit atomic sequences that can update the +screen without artifact. As all of these operations are asynchronous, +network latency should not adversely affect update latency. + +3.2 Composite Overlay Window + +Version 0.3 of the protocol adds the Composite Overlay Window, which +provides compositing managers with a surface on which to draw without +interference. This window is always above normal windows and is always +below the screen saver window. It is an InputOutput window whose width +and height are the screen dimensions. Its visual is the root visual +and its border width is zero. Attempts to redirect it using the +composite extension are ignored. This window does not appear in the +reply of the QueryTree request. It is also an override redirect window. +These last two features make it invisible to window managers and other X11 +clients. The only way to access the XID of this window is via the +CompositeGetOverlayWindow request. Initially, the Composite Overlay +Window is unmapped. + +CompositeGetOverlayWindow returns the XID of the Composite Overlay +Window. If the window has not yet been mapped, it is mapped by this +request. When all clients who have called this request have terminated +their X11 connections the window is unmapped. + +Composite managers may render directly to the Composite Overlay +Window, or they may reparent other windows to be children of this +window and render to these. Multiple clients may render to the +Composite Overlay Window, create child windows of it, reshape it, and +redefine its input region, but the specific arbitration rules followed +by these clients is not defined by this specification; these policies +should be defined by the clients themselves. + +3.3 Clipping semantics redefined + +Version 0.4 of the protocol changes the semantics of clipping in the +presense of manual redirect children. In version 0.3, a parent was always +clipped to child windows, independent of the kind of redirection going on. +With version 0.4, the parent is no longer clipped to child windows which are +manually redirected. This means the parent can draw in the child region without using +IncludeInferiors mode, and (perhaps more importantly), it will receive +expose events in those regions caused by other actions. This new behaviour +is not selectable. + +4. Errors + +The composite extension does not define any new errors. + +5. Types + + UPDATETYPE { Automatic, Manual } + + CompositeCoordinate + child: Window + x, y: CARD16 + +7. Extension Initialization + +The client must negotiate the version of the extension before executing +extension requests. Otherwise, the server will return BadRequest for any +operations other than QueryVersion. + + QueryVersion + + client-major-version: CARD32 + client-minor-version: CARD32 + + -> + + major-version: CARD32 + minor-version: CARD32 + + The client sends the highest supported version to the server and + the server sends the highest version it supports, but no higher than + the requested version. Major versions changes can introduce + incompatibilities in existing functionality, minor version + changes introduce only backward compatible changes. It is + the client's responsibility to ensure that the server supports + a version which is compatible with its expectations. Servers + are encouraged to support multiple versions of the extension. + +8. Hierarchy Redirection + + RedirectWindow + + window: Window + update: UPDATETYPE + + errors: Window, Access, Match + + The hierarchy starting at 'window' is directed to off-screen + storage. 'update' specifies whether the contents are mirrored to + the parent window automatically or not. Only one client may specify + an update type of Manual, another attempt will result in an + Access error. When all clients enabling redirection terminate, + the redirection will automatically be disabled. + + The root window may not be redirected. Doing so results in a Match + error. + + RedirectSubwindows + + window: Window + update UPDATETYPE + + errors: Window, Access + + Hierarchies starting at all current and future children of window + will be redirected as in RedirectWindow. If update is Manual, + then painting of the window background during window manipulation + and ClearArea requests is inhibited. + + UnredirectWindow: + + window: Window + + errors: Window, Value + + Redirection of the specified window will be terminated. If + the specified window was not selected for redirection by the + current client, a 'Value' error results. + + UnredirectWindows: + + window: Window + + errors: Window, Value + + Redirection of all children of window will be terminated. If + the specified window was not selected for sub-redirection by the + current client, a 'Value' error results. + +9. Clip lists + + CreateRegionFromBorderClip + + region: Region + window: Window + + errors: Window, IDChoice + + This request creates a region containing the "usual" border clip + value; that is the area of the window clipped against siblings and + the parent. This region can be used to restrict rendering to + suitable areas while updating only a single window. The region + is copied at the moment the request is executed; future changes + to the window hierarchy will not be reflected in this region. + +10. Associating a Pixmap ID with the off-screen storage (0.2 and later) + + NameWindowPixmap + + window: Window + pixmap: Pixmap + + errors: Window, Match, IDChoice + + This request makes 'pixmap' a reference to the off-screen storage + for 'window'. This pixmap will remain allocated until freed, even + if 'window' is unmapped, reconfigured or destroyed. However, + 'window' will get a new pixmap allocated each time it is + mapped or resized, so this request will need to be reinvoked for + the client to continue to refer to the storage holding the current + window contents. Generates a 'Match' error if 'window' is not + redirected or is not visible. + +11. Composite Overlay Window (0.3 and later) + + CompositeGetOverlayWindow + + window: Window + + -> + + overlayWin: Window + + This request returns the XID of the Composite Overlay Window for + the screen specified by the argument 'window'. This request + indicates that the client wishes to use the Composite Overlay + Window of this screen. If this Composite Overlay Window has not + yet been mapped, it is mapped by this request. + + The Composite Overlay Window for a particular screen will be + unmapped when all clients who have invoked this request have + also invoked CompositeReleaseOverlayWindow for that screen. Also, + CompositeReleaseOverlayWindow for a screen will be implicitly + called when a client using the Composite Overlay Window on that + screen terminates its X11 connection. + + + CompositeReleaseOverlayWindow + + window: Window + + This request specifies that the client is no longer using the + Composite Overlay Window on the screen specified by the + argument 'window'. A screen's Composite Overlay Window is + unmapped when there are no longer any clients using it. + +12. External coordinate transformation (0.4 and later) + + RedirectCoordinate + + window: Window + redirect: BOOL + + errors: Window, Access + + If 'redirect' is TRUE, the requesting client is placed in charge of + coordinate transformations between 'window' and its children. If + 'redirect' is FALSE, any such redirection is disabled. Any + transformations needed by the server will be delivered to the + requesting client in TransformCoordinateNotify events and the + requesting client must reply with matching TransformCoordinate + requests for the server to continue with the operation. + + Generates an 'Access' error if another client has + redirected coordinates for 'window'. + + TransformCoordinate + + window: Window + serialNumber: CARD32 + x, y: INT16 + coordinates: LISTofCompositeCoordinate + + This provides the transformation data needed by the server for a + single TransformCoordinateNotify event. 'serialNumber' must match + the serial number delivered in the event. 'x' and 'y' represent the + coordinate from the event relative to the 'window'. 'coordinates' + represent the coordinate from the event relative to each child + listed. Any children not listed in 'coordinates' are given the + default transformation using the child window position within the + parent as a simple translation. + + The result of this is that any pointer data seen by means of + the protocol will appear to reflect the transformation + performed by this request. diff -r 86e57e56a454 -r 3f908f812ec7 doc/damageproto.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/damageproto.txt Fri Jan 29 10:23:08 2016 +0200 @@ -0,0 +1,222 @@ + The DAMAGE Extension + Protocol Version 1.1 + Document Revision 1 + 2007-01-08 + + Keith Packard + keithp@keithp.com + + Eric Anholt + eric@anholt.net + Open Source Technology Center + Intel Corporation +1. Introduction + +Monitoring the regions affected by rendering has wide-spread use, from +VNC-like systems scraping the screen to screen magnifying applications +designed to aid users with limited visual acuity. The DAMAGE extension is +designed to make such applications reasonably efficient in the face of +server-client latency. + +2. Acknolwedgements + +As usual, the author had significant input from many people, in particular: + + + Havoc Pennington who designed and implemented a Damage extension + last year which was then lost to the mists of time. + + + Bill Haneman whose work on accessibility in the Gnome environment + is legendary. + + + Jim Gettys who found a way to avoid streaming damage rectangles + to the client in many cases. + + + Owen Taylor who suggested that streaming damage rectangles may + be warranted in some cases after all. + +3. Damage Model + +We call changes made to pixel contents of windows and pixmaps 'damage' +throughout this extension. Another notion of 'damage' are drawable regions +which are in need of redisplay to repair the effects of window manipulation +or other data loss. This extension doesn't deal with this second notion at +all; suggestions on a better term which isn't easily conflated with existing +notions are eagerly solicited. + +Damage accumulates as drawing occurs in the drawable. Each drawing operation +'damages' one or more rectangular areas within the drawable. The rectangles +are guaranteed to include the set of pixels modified by each operation, but +may include significantly more than just those pixels. The desire is for +the damage to strike a balance between the number of rectangles reported and +the extraneous area included. A reasonable goal is for each primitive +object drawn (line, string, rectangle) to be represented as a single +rectangle and for the damage area of the operation to be the union of these +rectangles. + +The DAMAGE extension allows applications to either receive the raw +rectangles as a stream of events, or to have them partially processed within +the X server to reduce the amount of data transmitted as well as reduce the +processing latency once the repaint operation has started. + +Damage to a window reflects both drawing within the window itself as well as +drawing within any inferior window that affects pixels seen by +IncludeInferiors rendering operations. To reduce the computational +complexity of this, the DAMAGE extension allows the server to monitor all +rendering operations within the physical target pixel storage that fall +within the bounds of the window. In a system with a single frame buffer +holding all windows, this means that damage will accumulate for all +rendering operations that lie within the visible part of the window. + +The precise reason for this architecture is to enable the Composite +extension which provides multiple pixel storage areas for the screen +contents. + +3.1 Additions in the 1.1 version of the protocol + +Damage is automatically computed by the X Server for X rendering operations, +but direct rendering extensions have allowed clients to perform rendering +outside of the control of the X Server. The 1.1 version of the protocol +added a request to allow direct rendering clients to report damage to a +drawable. Some direct rendering clients, due to architectural limitations, +always perform rendering to the root window, even in when it should be +performed to the backing pixmap in the Composite case. To provide +less-incorrect rendering in this cases, the direct rendering client should +translate its damage region to screen coordinates and report the damage against +the root window rather than the drawable. + +4. Data types + +The "Damage" object holds any accumulated damage region and reflects the +relationship between the drawable selected for damage notification and the +drawable for which damage is tracked. + +5. Errors + +Damage + A value for a DAMAGE argument does not name a defined DAMAGE. + +6. Types + + DAMAGE 32-bit value (top three bits guaranteed to be zero) + + DamageReportLevel { DamageReportRawRectangles, + DamageReportDeltaRectangles, + DamageReportBoundingBox, + DamageReportNonEmpty } + + DamageReportRawRectangles + + Delivers DamageNotify events each time the screen + is modified with rectangular bounds that circumscribe + the damaged area. No attempt to compress out overlapping + rectangles is made. + + DamageReportDeltaRectangles + + Delivers DamageNotify events each time damage occurs + which is not included in the damage region. The + reported rectangles include only the changes to that + area, not the raw damage data. + + DamageReportBoundingBox + + Delivers DamageNotify events each time the bounding + box enclosing the damage region increases in size. + The reported rectangle encloses the entire damage region, + not just the changes to that size. + + DamageReportNonEmpty + + Delivers a single DamageNotify event each time the + damage rectangle changes from empty to non-empty, and + also whenever the result of a DamageSubtract request + results in a non-empty region. + +7. Events + +DamageNotify + + level: DamageReportLevel + drawable: Drawable + damage: DAMAGE + more: Bool + timestamp: Timestamp + area: Rectangle + drawable-geometry: Rectangle + + 'more' indicates whether there are subsequent damage events + being delivered immediately as part of a larger damage region + +8. Extension Initialization + +The client must negotiate the version of the extension before executing +extension requests. Otherwise, the server will return BadRequest for any +operations other than QueryVersion. + +QueryVersion + + client-major-version: CARD32 + client-minor-version: CARD32 + + -> + + major-version: CARD32 + minor-version: CARD32 + + The client sends the highest supported version to the server and + the server sends the highest version it supports, but no higher than + the requested version. Major versions changes can introduce + incompatibilities in existing functionality, minor version + changes introduce only backward compatible changes. It is + the clients responsibility to ensure that the server supports + a version which is compatible with its expectations. Servers + are encouraged to support multiple versions of the extension. + +9. Enable Monitoring + +DamageCreate + + damage: DAMAGE + drawable: Drawable + level: DamageReportLevel + + Creates a damage object to monitor changes to Drawable + +DamageDestroy + damage: DAMAGE + + Destroys damage. + +DamageSubtract + + damage: DAMAGE + repair: Region or None + parts: Region or None + + Synchronously modifies the regions in the following manner: + + If repair is None: + + 1) if parts is not None, parts = damage + 2) damage = + + Otherwise: + + 1) tmp = damage INTERSECT repair + 2) damage = damage - tmp + 3) if parts is not None, parts = tmp + 4) Generate DamageNotify for remaining damage areas + +DamageAdd + + drawable: Drawable + region: Region + + Reports damage of the region within the given drawable. This may be + used by direct rendering clients to report damage that the server would + otherwise be unaware of. The damage region is relative to the origin + of the drawable. + + Damage posted in this way will appear in DamageNotify events as normal, + and also in server internal damage tracking (for shadow framebuffer + updates, pixmap damage, and other uses). diff -r 86e57e56a454 -r 3f908f812ec7 doc/fixesproto.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/fixesproto.txt Fri Jan 29 10:23:08 2016 +0200 @@ -0,0 +1,577 @@ + The XFIXES Extension + Version 4.0 + Document Revision 2 + 2006-12-14 + Keith Packard + keithp@keithp.com + +1. Introduction + +X applications have often needed to work around various shortcomings in the +core X window system. This extension is designed to provide the minimal +server-side support necessary to eliminate problems caused by these +workarounds. + +2. Acknowledgements + +This extension is a direct result of requests made by application +developers, in particular, + + + Owen Taylor for describing the issues raised with the XEMBED + mechanisms and SaveSet processing and his initial extension + to handle this issue. + + + Bill Haneman for the design for cursor image tracking. + + + Havoc Pennington + + + Fredrik Höglund for cursor names + + + Deron Johnson for cursor visibility + +3. Basic Premise + +Requests in this extension may seem to wander all over the map of X server +capabilities, but they are tied by a simple rule -- resolving issues raised +by application interaction with core protocol mechanisms that cannot be +adequately worked around on the client side of the wire. + +4. Extension initialization + +The client must negotiate the version of the extension before executing +extension requests. Behavior of the server is undefined otherwise. + +QueryVersion + + client-major-version: CARD32 + client-minor-version: CARD32 + + -> + + major-version: CARD32 + minor-version: CARD32 + + The client sends the highest supported version to the server and + the server sends the highest version it supports, but no higher than + the requested version. Major versions changes can introduce + new requests, minor version changes introduce only adjustments to + existing requests or backward compatible changes. It is + the clients responsibility to ensure that the server supports + a version which is compatible with its expectations. + +************* XFIXES VERSION 1 OR BETTER *********** + +5. Save Set processing changes + +Embedding one application within another provides a way of unifying +disparate documents and views within a single framework. From the X +protocol perspective, this appears similar to nested window managers; the +embedding application "manages" the embedded windows much as a window +manager does for top-level windows. To protect the embedded application +from embedding application failure, it is reasonable to use the core SaveSet +mechanism so that embedding application failure causes embedded windows to +be preserved instead of destroyed. + +The core save set mechanism defines the target for each save set member +window as the nearest enclosing window not owned by the terminating client. +For embedding applications, this nearest window is usually the window +manager frame. The problem here is that the window manager will not +generally expect to receive and correctly manage new windows appearing within +that window by the save set mechanism, and will instead destroy the frame +window in response to the client window destruction. This causes the +embedded window to be destroyed. + +An easy fix for this problem is to change the target of the save set member +to a window which won't be affected by the underlying window destruction. +XFIXES chooses the root window as the target. + +Having embedded windows suddenly appear at the top level can confuse users, +so XFIXES also lets the client select whether the window should end up +unmapped after the save set processing instead of unconditionally making +them be mapped. + +5.1 Requests + +ChangeSaveSet + + window: Window + mode: { Insert, Delete } + target: { Nearest, Root } + map: { Map, Unmap } + + ChangeSaveSet is an extension of the core protocol ChangeSaveSet + request. As in that request, mode specifies whether the indicated + window is inserted or deleted from the save-set. Target specifies + whether the window is reparented to the nearest non-client window as + in the core protocol, or reparented to the root window. Map + specifies whether the window is mapped as in the core protocol or + unmapped. + +6. Selection Tracking + +Applications wishing to monitor the contents of current selections must +poll for selection changes. XFIXES improves this by providing an event +delivered whenever the selection ownership changes. + +6.1 Types + + SELECTIONEVENT { SetSelectionOwner, + SelectionWindowDestroy, + SelectionClientClose } + +6.1 Events + +SelectionNotify + + subtype: SELECTIONEVENT + window: Window + owner: Window + selection: Atom + timestamp: Timestamp + selection-timestamp: Timestamp + +6.2 Requests + +SelectSelectionInput + + window: Window + selection: Atom + event-mask: SETofSELECTIONEVENT + + Selects for events to be delivered to window when various causes of + ownership of selection occur. Subtype indicates the cause of the + selection ownership change. Owner is set to the current selection + owner, or None. Timestamp indicates the time the event was + generated while selection-timestamp indicates the timestamp used to + own the selection. + +7. Cursor Image Monitoring + +Mirroring the screen contents is easily done with the core protocol or VNC +addons, except for the current cursor image. There is no way using the core +protocol to discover which cursor image is currently displayed. The +cursor image often contains significant semantic content about the user +interface. XFIXES provides a simple mechanism to discover when the cursor +image changes and to fetch the current cursor image. + +As the current cursor may or may not have any XID associated with it, there +is no stable name available. Instead, XFIXES returns only the image of the +current cursor and provides a way to identify cursor images to avoid +refetching the image each time it changes to a previously seen cursor. + +7.1 Types + CURSOREVENT { DisplayCursor } + +7.2 Events + +CursorNotify + + subtype: CURSOREVENT + window: Window + cursor-serial: CARD32 + timestamp: Timestamp + name: Atom (Version 2 only) + +7.3 Requests + +SelectCursorInput + + window: Window + event-mask: SETofCURSOREVENT + + This request directs cursor change events to the named window. + Events will be delivered irrespective of the screen on which they + occur. Subtype indicates the cause of the cursor image change + (there is only one subtype at present). Cursor-serial is a number + assigned to the cursor image which identifies the image. Cursors + with different serial numbers may have different images. Timestamp + is the time of the cursor change. + + Servers supporting the X Input Extension Version 2.0 or higher only + notify the clients of cursor change events for the ClientPointer, not + of any other master pointer (see Section 4.4. in the XI2 protocol + specificiation). + +GetCursorImage + + -> + + x: INT16 + y: INT16 + width: CARD16 + height: CARD16 + x-hot: CARD16 + y-hot: CARD16 + cursor-serial: CARD32 + cursor-image: LISTofCARD32 + + GetCursorImage returns the image of the current cursor. X and y are + the current cursor position. Width and height are the size of the + cursor image. X-hot and y-hot mark the hotspot within the cursor + image. Cursor-serial provides the number assigned to this cursor + image, this same serial number will be reported in a CursorNotify + event if this cursor image is redisplayed in the future. + + The cursor image itself is returned as a single image at 32 bits per + pixel with 8 bits of alpha in the most significant 8 bits of the + pixel followed by 8 bits each of red, green and finally 8 bits of + blue in the least significant 8 bits. The color components are + pre-multiplied with the alpha component. + +************* XFIXES VERSION 2 OR BETTER *********** + +8. Region Objects + +The core protocol doesn't expose regions as a primitive object and this +makes many operations more complicated than they really need to be. Adding +region objects simplifies expose handling, the Shape extension and other +operations. These operations are also designed to support a separate +extension, the X Damage Extension. + +8.1 Types + + Region: XID + WINDOW_REGION_KIND: { Bounding, Clip } + +8.2 Errors + + Region The specified region is invalid + +8.3 Requests + +CreateRegion + + region: REGION + rects: LISTofRECTANGLE + + Creates a region initialized to the specified list of rectangles. + The rectangles may be specified in any order, their union becomes + the region. The core protocol allows applications to specify an + order for the rectangles, but it turns out to be just as hard to + verify the rectangles are actually in that order as it is to simply + ignore the ordering information and union them together. Hence, + this request dispenses with the ordering information. + + Errors: IDChoice + +CreateRegionFromBitmap + + region: REGION + bitmap: PIXMAP + + Creates a region initialized to the set of 'one' pixels in bitmap + (which must be depth 1, else Match error). + + Errors: Pixmap, IDChoice, Match + +CreateRegionFromWindow + + window: Window + kind: WINDOW_REGION_KIND + region: Region + + Creates a region initialized to the specified window region. See the + Shape extension for the definition of Bounding and Clip regions. + + Errors: Window, IDChoice, Value + +CreateRegionFromGC + + gc: GContext + region: Region + + Creates a region initialized from the clip list of the specified + GContext. + + Errors: GContext, IDChoice + +CreateRegionFromPicture + + picture: Picture + region: Region + + + Creates a region initialized from the clip list of the specified + Picture. + + Errors: Picture, IDChoice + +DestroyRegion + + region: Region + + Destroys the specified region. + + Errors: Region + +SetRegion + + region: Region + rects: LISTofRECTANGLE + + This replaces the current contents of region with the region formed + by the union of rects. + +CopyRegion + source: Region + destination: Region + + This replaces the contents of destination with the contents of + source. + +UnionRegion +IntersectRegion +SubtractRegion + + source1: Region + source2: Region + destination: Region + + Combines source1 and source2, placing the result in destination. + Destination may be the same as either source1 or source2. + + Errors: Region, Value + +InvertRegion + + source: Region + bounds: RECTANGLE + destination: Region + + The source region is subtracted from the region specified by + bounds. The result is placed in destination, replacing its contents. + + Errors: Region + +TranslateRegion + + region: Region + dx, dy: INT16 + + The region is translated by dx, dy in place. + + Errors: Region + +RegionExtents + + source: Region + destination: Region + + The extents of the source region are placed in the destination + +FetchRegion + + region: Region + -> + extents: RECTANGLE + rectangles: LISTofRECTANGLE + + The region is returned as a list of rectangles in YX-banded order. + + Errors: Region + +SetGCClipRegion + + gc: GCONTEXT + clip-x-origin, clip-y-origin: INT16 + region: Region or None + + This request changes clip-mask in gc to the specified region and + sets the clip origin. Output will be clipped to remain contained + within the region. The clip origin is interpreted relative to the + origin of whatever destination drawable is specified in a graphics + request. The region is interpreted relative to the clip origin. + Future changes to region have no effect on the gc clip-mask. + + Errors: GContext, Region + +SetWindowShapeRegion + + dest: Window + destKind: SHAPE_KIND + xOff, yOff: INT16 + region: Region or None + + This request sets the specified (by destKind) Shape extension region + of the window to region, offset by xOff and yOff. Future changes to + region have no effect on the window shape. + + Errors: Window, Value, Region + +SetPictureClipRegion + + picture: Picture + clip-x-origin, clip-y-origin: INT16 + region: Region or None + + This request changes clip-mask in picture to the specified region + and sets the clip origin. Input and output will be clipped to + remain contained within the region. The clip origin is interpreted + relative to the origin of the drawable associated with picture. The + region is interpreted relative to the clip origin. Future changes + to region have no effect on the picture clip-mask. + + Errors: Picture, Region + +9. Cursor Names + +Attaching names to cursors permits some abstract semantic content to be +associated with specific cursor images. Reflecting those names back to +applications allows that semantic content to be related to the user through +non-visual means. + +9.1 Events + +CursorNotify + + subtype: CURSOREVENT + window: Window + cursor-serial: CARD32 + timestamp: Timestamp + name: Atom or None + + In Version 2 of the XFIXES protocol, this event adds the atom + of any name associated with the current cursor (else None). + +9.2 Requests + +SetCursorName + + cursor: CURSOR + name: LISTofCARD8 + + This request interns name as an atom and sets that atom as the name + of cursor. + + Errors: Cursor + +GetCursorName + + cursor: CURSOR + -> + atom: ATOM or None + name: LISTofCARD8 + + This request returns the name and atom of cursor. If no name is + set, atom is None and name is empty. + + Errors: Cursor + +GetCursorImageAndName + + -> + + x: INT16 + y: INT16 + width: CARD16 + height: CARD16 + x-hot: CARD16 + y-hot: CARD16 + cursor-serial: CARD32 + cursor-atom: ATOM + cursor-name: LISTofCARD8 + cursor-image: LISTofCARD32 + + This is similar to GetCursorImage except for including both + the atom and name of the current cursor. + +ChangeCursor + + source, destination: CURSOR + + This request replaces all references to the destination with a + reference to source. Any existing uses of the destination cursor + object will now show the source cursor image. + +ChangeCursorByName + + src: CURSOR + name: LISTofCARD8 + + This request replaces the contents of all cursors with the specified + name with the src cursor. + +************* XFIXES VERSION 3 OR BETTER *********** + +10. Region Expansion + +This update provides another operation on the region objects defined in +Section 8 of this document. + +10.1 Requests + +ExpandRegion + source: REGION + destination: REGION + left, right, top, bottom: CARD16 + + Creates destination region containing the area specified by + expanding each rectangle in the source region by the specified + number of pixels to the left, right, top and bottom. + +************* XFIXES VERSION 4 OR BETTER *********** + +11. Cursor Visibility + +Composite managers may want to render the cursor themselves instead of +relying on the X server sprite drawing, this provides a way for them to +do so without getting a double cursor image. + +11.1 Requests + +HideCursor + + window: WINDOW + + A client sends this request to indicate that it wants the + cursor image to be hidden (i.e. to not be displayed) when + the sprite is inside the specified window, or one of its + subwindows. If the sprite is inside a window for which one + or more active clients have requested cursor hiding then the + cursor image will not be displayed. + + Note that even though cursor hiding causes the cursor image + to be invisible, CursorNotify events will still be sent + normally, as if the cursor image were visible. + + If, during a grab, one or more active clients have requested + cursor hiding for grab window, or one of its ancestors, the + cursor image of the grab cursor will not be displayed during + the lifetime of that grab. + + When a client with outstanding cursor hiding requests + terminates its connection these requests will be deleted. + + Servers supporting the X Input Extension Version 2.0 or higher hide + all visible cursors in response to a HideCursor request. If a master + pointer is created while the cursors are hidden, this master pointer's + cursor will be hidden as well. + +ShowCursor + + window: WINDOW + + A client sends this request to indicate that it wants the + cursor image to be displayed when the sprite is inside the + specified window, or one of its subwindows. If the sprite + is inside a window for which no active clients have requested + cursor hiding then the cursor image for that window will be + displayed. In other words, if a client calls HideCursor for + a specified window, or window subtree, this request reverses + the effects of the HideCursor request. + + If the client has made no outstanding HideCursor requests + a BadMatch error is generated. + + Servers supporting the X Input Extension Version 2.0 or higher show + all visible cursors in response to a ShowCursor request. + +99. Future compatibility + +This extension is not expected to remain fixed. Future changes will +strive to remain compatible if at all possible. The X server will always +support version 1 of the extension protocol if requested by a client. + +Additions to the protocol will always by marked by minor version number +changes so that applications will be able to detect what requests are +supported. diff -r 86e57e56a454 -r 3f908f812ec7 doc/texture_from_pixmap.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/texture_from_pixmap.txt Fri Jan 29 10:23:08 2016 +0200 @@ -0,0 +1,792 @@ +Name + + EXT_texture_from_pixmap + +Name Strings + + GLX_EXT_texture_from_pixmap + +Contributors + + James Jones, NVIDIA + Aaron Plattner, NVIDIA + Andy Ritger, NVIDIA + +Contact + + David Reveman, Novell, Inc. (davidr 'at' novell.com) + +Status + + Complete + +Version + + 17 (10 Feb 2009) + +Number + + 344 + +Dependencies + + OpenGL 1.1 is required. + GLX 1.3 is required. + GL_EXT_framebuffer_object affects the definition of this extension. + GL_ARB_texture_rectangle affects the definition of this extension. + GL_ARB_texture_non_power_of_two affects the definition of this extension. + GL_SGIS_generate_mipmap affects the definition of this extension. + +Overview + + This extension allows a color buffer to be used for both rendering and + texturing. + + Only color buffers of pixmaps can be used for texturing by this extension + but other types of drawables can be supported by future extensions layered + on top of this extension. + + The functionality of this extension is similar to WGL_ARB_render_texture. + However, the purpose of this extension is not to provide + "render to texture" like functionality but rather the ability to bind + an existing X drawable to a texture. Though, there is nothing that + prohibits it from being used for "render to texture". + + - Windows are problematic as they can change size and therefore are not + supported by this extension. + + - Only a color buffer of a GLX pixmap created using an FBConfig with + attribute GLX_BIND_TO_TEXTURE_RGB_EXT or GLX_BIND_TO_TEXTURE_RGBA_EXT + set to TRUE can be bound as a texture. + + - The texture internal format is determined when the color buffer + is associated with the texture, guaranteeing that the color + buffer format is equivalent to the texture internal format. + + - A client can create a complete set of mipmap images if + EXT_framebuffer_object is supported. + + +IP Status + + There are no known IP issues. + +Issues + + 1. What should this extension be called? + + Even though it is very similar to WGL_ARB_render_texture that name is + not appropriate as the intention of this extension is not + "render to texture" like functionality. + + EXT_texture_from_pixmap seams most appropriate. Layering of future + extensions on top of this extension for using other type of drawables + as textures follows the same conventions as vertex/pixel buffer objects + and vertex/fragment programs. + + + 2. Should we allow applications to render to different mipmap levels and + cube map faces? + + In order to discourage the use of this extension as a render to texture + mechanism, cube maps and rendering directly to mip-map levels > 0 will + not be supported. A new FBConfig attribute is introduced that specifies + whether or not drawables created with that config will support multiple + mipmap levels when bound to a texture. The other mipmap levels can be + filled in by the EXT_framebuffer_object GenerateMipmapEXT function. + + Specifying which level of a pixmap was being rendered to on a per-drawable + basis, as was done in the WGL_ARB_render_texture extension, also + introduces concurrency issues. The state of the drawable when it was + being rendered two by two separate threads of execution and both were + changing the mipmap level was difficult to define. + + It is also desireable to keep this extension as simple as possible. + Adding functionality that complicates the implementation and that is not + directly relevenat to the goal of exposing a mechanism for texturing from + arbitrary X pixmaps is not productive. If the ability to render directly + to all levels of a texture is needed, EXT_framebuffer_object is the + extension that should be used. + + + 3. Should 1D textures be supported? + + X servers layered on top of an OpenGL implementation might not be able + to support this. A new FBConfig attribute is introduced specifying + which texture targets a drawable created with the given FBConfig can + be bound to. + + + 4. What should the default value for GLX_TEXTURE_TARGET_EXT be? Should + users be required to set this value if GLX_TEXTURE_FORMAT_EXT is not + GLX_TEXTURE_FORMAT_NONE_EXT? + + The implementation is capable of choosing a reasonable default, we simply + need to specify the correct way to do so. We can base the ordering on + the properties of the pixmap and the texturing capabilities of the + pixmap's FBConfig and the implementation. + + The order is: + + - If GL_ARB_texture_non_power_of_two is supported GL_TEXTURE_2D will + be used for all pixmap sizes. + + - If only GL_ARB_texture_rectangle is supported GL_TEXTURE_2D will + be used for all power of two pixmap sizes and GL_TEXTURE_RECTANGLE_ARB + will be used for all non power of two pixmap sizes. + + + 5. Should users be required to re-bind the drawable to a texture after + the drawable has been rendered to? + + It is difficult to define what the contents of the texture would be if + we don't require this. Also, requiring this would allow implementations + to perform an implicit copy at this point if they could not support + texturing directly out of renderable memory. + + The problem with defining the contents of the texture after rendering + has occured to the associated drawable is that there is no way to + synchronize the use of the buffer as a source and as a destination. + Direct OpenGL rendering is not necessarily done in the same command + stream as X rendering. At the time the pixmap is used as the source + for a texturing operation, it could be in a state halfway through a + copyarea operation in which half of it is say, white, and half is the + result of the copyarea operation. How is this defined? Worse, some + other OpenGL application could be halfway through a frame of rendering + when the composite manager sources from it. The buffer might just + contain the results of a "glClear" operation at that point. + + To gurantee tear-free rendering, a composite manager would run as follows: + + -receive request for compositing: + XGrabServer() + glXWaitX() or XSync() + glXBindTexImageEXT() + + + + glXReleaseTexImageEXT() + XUngrabServer() + + Apps that don't synchronize like this would get what's available, + and that may or may not be what they expect. + + + 6. What is the result of calling GenerateMipmapEXT on a drawable that + was not created with mipmap levels? + + The results are undefined. + + + 7. Rendering done by the window system may be y-inverted compared + to the standard OpenGL texture representation. More specifically: + the X Window system uses a coordinate system where the origin is in + the upper left; however, the GL uses a coordinate system where the + origin is in the lower left. Should we define the contents of the + texture as the y-inverted contents of the drawable? + + X implementations may represent their drawables differently internally, + so y-inversion should be exposed as an FBConfig attribute. + Applications will need to query this attribute and adjust their rendering + appropriately. + + If a drawables is y-inverted and is bound to a texture, the contents of the + texture will be y-inverted with respect to the standard GL memory layout. + This means the contents of a pixmap of size (width, height) at pixmap + coordinate (x, y) will be at location (x, height-y-1) in the texture. + Applications will need to adjust their texture coordinates accordingly to + avoid drawing the texture contents upside down. + + + 8. Why wasn't this extension based on FBO instead of ARB_render_texture? + Isn't the render_texture extension deprecated? + + At first glance, FBO may seem like the perfect framework to base a spec + for texturing from pixmap surfaces on. It replaced the + WGL_ARB_render_texture specification, which provided a mechanism to + texture from pbuffer surfaces. However, this train of thought is another + side effect of the unfortunate naming of the WGL_ARB_render_texture + specification. FBO and the orginal render_texture specification were + two different solutions to the problem of how to render to and texture + from the same surface. WGL_ARB_render_texture provided a method to bind + a texture to a drawable surface, as this extension does. FBO provides the + opposite solution, allowing rendering to arbitrary surfaces including + textures. In the case of FBO, the application doing the rendering knows + that it needs to render to an alternate surface. In our usage case, the + application doing the rendering is arbitrary, and has no knowledge that another + application wants to use the surface it is rendering to as a texture. The + only application able to name the surface is the one texturing from it. + Therefore, it makes sense to provide a mechanism for binding a texture to + an arbitrary surface in general, and a pixmap in this particular case. + + + 9. Why not allow binding directly to an X pixmap without creating an + intermediate GLX pixmap? + + Architecturally, GLX has moved away from operating directly on X + drawables. This allows GLX specific attributes to be associated with the + GLX drawables. In this case, it is important to associate an FBConfig + with the drawable. The FBConfig contains attributes specifying the + internal format the GL will use when utilizing the drawable's framebuffer + as a texture. + + +New Procedures and Functions + + void glXBindTexImageEXT (Display *display, + GLXDrawable drawable, + int buffer, + const int *attrib_list) + + void glXReleaseTexImageEXT (Display *display, + GLXDrawable drawable, + int buffer) + + +New Tokens + + Accepted by the parameter of glXGetFBConfigAttrib and + the parameter of glXChooseFBConfig: + + GLX_BIND_TO_TEXTURE_RGB_EXT 0x20D0 + GLX_BIND_TO_TEXTURE_RGBA_EXT 0x20D1 + GLX_BIND_TO_MIPMAP_TEXTURE_EXT 0x20D2 + GLX_BIND_TO_TEXTURE_TARGETS_EXT 0x20D3 + GLX_Y_INVERTED_EXT 0x20D4 + + Accepted as an attribute in the parameter of + glXCreatePixmap, and by the parameter of glXQueryDrawable: + + GLX_TEXTURE_FORMAT_EXT 0x20D5 + GLX_TEXTURE_TARGET_EXT 0x20D6 + GLX_MIPMAP_TEXTURE_EXT 0x20D7 + + Accepted as a value in the parameter of glXCreatePixmap + and returned in the parameter of glXQueryDrawable when + is GLX_TEXTURE_FORMAT_EXT: + + GLX_TEXTURE_FORMAT_NONE_EXT 0x20D8 + GLX_TEXTURE_FORMAT_RGB_EXT 0x20D9 + GLX_TEXTURE_FORMAT_RGBA_EXT 0x20DA + + Accepted as bits in the GLX_BIND_TO_TEXTURE_TARGETS_EXT variable: + + GLX_TEXTURE_1D_BIT_EXT 0x00000001 + GLX_TEXTURE_2D_BIT_EXT 0x00000002 + GLX_TEXTURE_RECTANGLE_BIT_EXT 0x00000004 + + Accepted as a value in the parameter of glXCreatePixmap + and returned in the parameter of glXQueryDrawable when + is GLX_TEXTURE_TARGET_EXT: + + GLX_TEXTURE_1D_EXT 0x20DB + GLX_TEXTURE_2D_EXT 0x20DC + GLX_TEXTURE_RECTANGLE_EXT 0x20DD + + Accepted by the parameter of glXBindTexImageEXT and + glXReleaseTexImageEXT: + + GLX_FRONT_LEFT_EXT 0x20DE + GLX_FRONT_RIGHT_EXT 0x20DF + GLX_BACK_LEFT_EXT 0x20E0 + GLX_BACK_RIGHT_EXT 0x20E1 + GLX_FRONT_EXT GLX_FRONT_LEFT_EXT + GLX_BACK_EXT GLX_BACK_LEFT_EXT + GLX_AUX0_EXT 0x20E2 + GLX_AUX1_EXT 0x20E3 + GLX_AUX2_EXT 0x20E4 + GLX_AUX3_EXT 0x20E5 + GLX_AUX4_EXT 0x20E6 + GLX_AUX5_EXT 0x20E7 + GLX_AUX6_EXT 0x20E8 + GLX_AUX7_EXT 0x20E9 + GLX_AUX8_EXT 0x20EA + GLX_AUX9_EXT 0x20EB + + +GLX Protocol + + Two new GLX protocol commands are added. + + BindTexImageEXT + 1 CARD8 opcode (X assigned) + 1 16 GLX opcode (glXVendorPrivate) + 2 6+n request length + 4 1330 vendor specific opcode + 4 CARD32 context tag + 4 GLX_DRAWABLE drawable + 4 INT32 buffer + 4 CARD32 num_attributes + 4*n LISTofATTRIBUTE_PAIR attribute, value pairs. + + ReleaseTexImageEXT + 1 CARD8 opcode (X assigned) + 1 16 GLX opcode (glXVendorPrivate) + 2 5 request length + 4 1331 vendor specific opcode + 4 CARD32 context tag + 4 GLX_DRAWABLE drawable + 4 INT32 buffer + + +Errors + +Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) + + None. + +Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization) + + None. + +Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment +Operations and the Frame Buffer) + + None. + +Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) + + None. + +Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and State +Requests) + + None. + +Additions to the GLX Specification + + Add to table 3.1, GLXFBConfig Attributes: + + Attribute Type Notes + ------------------------------- ------- ------------------------------------------------------------------- + GLX_BIND_TO_TEXTURE_RGB_EXT boolean True if color buffers can be bound to RGB texture + GLX_BIND_TO_TEXTURE_RGBA_EXT boolean True if color buffers can be bound to RGBA texture + GLX_BIND_TO_MIPMAP_TEXTURE_EXT boolean True if color buffers can be bound to textures with multiple levels + GLX_BIND_TO_TEXTURE_TARGETS_EXT bitmask Bitmask of texture targets color buffers can be bound to + GLX_Y_INVERTED_EXT boolean True if the drawable's framebuffer is y-inverted. This can be used to determine if y-inverted texture coordinates need to be used when texturing from this drawable when it is bound to a texture target. + + Additions to table 3.4, Default Match Criteria for GLXFBConfig attributes: + + Attribute Default Selection Criteria Priority + ------------------------------- -------------------- ------------------ --------- + GLX_BIND_TO_TEXTURE_RGB_EXT GLX_DONT_CARE Exact + GLX_BIND_TO_TEXTURE_RGBA_EXT GLX_DONT_CARE Exact + GLX_BIND_TO_MIPMAP_TEXTURE_EXT GLX_DONT_CARE Exact + GLX_BIND_TO_TEXTURE_TARGETS_EXT - Mask + GLX_Y_INVERTED_EXT GLX_DONT_CARE Exact + + Modifications to 3.3.3, "Configuration Management" + + Add after paragraph 17 in the description of FBConfigs: + + GLX_Y_INVERTED_EXT is a boolean describing the memory layout used for + drawables created with the GLXFBConfig. The attribute is True if the + drawable's framebuffer will be y-inverted. This can be used to determine + if y-inverted texture coordinates need to be used when texturing from this + drawable when it is bound to a texture target. + + Modifications to 3.3.5, "Offscreen Rendering" + + Modify paragraph 3 of the description of glXCreatePixmap: + + specifies a list of attributes for the pixmap. The list has + the same structure as described for glXChooseFBConfig. Currently the + following attributes can be specified in attrib_list: + GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_TARGET_EXT, GLX_MIPMAP_TEXTURE_EXT, + attrib_list may be NULL or empty (first attribute of None), in which case + all attributes assume their default values as described below. + + GLX_TEXTURE_FORMAT_EXT describes the texture format this pixmap can be + bound to. Valid values are GLX_TEXTURE_FORMAT_RGB_EXT, + GLX_TEXTURE_FORMAT_RGBA_EXT, and GLX_TEXTURE_FORMAT_NONE_EXT. + + GLX_TEXTURE_TARGET_EXT can be set to GLX_TEXTURE_1D_EXT, + GLX_TEXTURE_2D_EXT, or GLX_TEXTURE_RECTANGLE_EXT; it indicates the type + of texture that will be created when GLX_TEXTURE_FORMAT_EXT is not + GLX_TEXTURE_FORMAT_NONE_EXT. The default value of GLX_TEXTURE_TARGET_EXT + depends on the capabilities in and the dimensions of the pixmap. + If has GLX_TEXTURE_2D_BIT set and one or more of the following is + true: + + * GLX_TEXTURE_RECTANGLE_BIT_EXT is not set in + + * GL_ARB_texture_non_power_of_two is supported + + * the pixmap's width and height are powers of 2 + + the default value for GLX_TEXTURE_TARGET_EXT is GLX_TEXTURE_2D_EXT. + + Otherwise, the first supported target is chosen in this order: + GLX_TEXTURE_RECTANGLE_EXT, GLX_TEXTURE_1D_EXT. + + GLX_MIPMAP_TEXTURE_EXT indicates that storage for mipmaps should be + allocated. Space for mipmaps will be set aside if GLX_TEXTURE_FORMAT_EXT + is not GLX_TEXTURE_FORMAT_NONE_EXT and GLX_MIPMAP_TEXTURE_EXT is TRUE. + The default value is FALSE. + + Modify paragraph 5 of the description of glXCreatePixmap: + + ...If is not a valid Pixmap XID, then a BadPixmap error is + generated. A BadConfig error is generated if any of the following + conditions are true: + + * GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_RGB_EXT and + does not have GLX_BIND_TO_TEXTURE_RGB set to TRUE. + + * GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_RGBA_EXT and + does not have GLX_BIND_TO_TEXTURE_RGBA set to TRUE. + + * GLX_MIPMAP_TEXTURE_EXT is set to TRUE and does not + have GLX_BIND_TO_MIPMAP_EXT set to TRUE. + + * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_1D_EXT + and does not have GLX_TEXTURE_1D_BIT_EXT set. + + * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_2D_EXT + and does not have GLX_TEXTURE_2D_BIT_EXT set. + + * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_RECTANGLE_EXT + and does not have GLX_TEXTURE_RECTANGLE_BIT_EXT set. + + A BadValue error is generated if GLX_TEXTURE_FORMAT_EXT is not + GLX_TEXTURE_FORMAT_NONE_EXT and the width or height of are + incompatible with the specified value of GLX_TEXTURE_TARGET_EXT on this + implementation. (e.g., the pixmap size is not a power of 2 and + GL_ARB_texture_rectangle is not supported). + + Modify paragraph 1 of the description of glXDestroyPixmap: + + ...The storage for the GLX pixmap will be freed when it is not current + to any client and all color buffers that are bound to a texture object + have been released. + + + Modifications to seciton 3.3.6, "Querying Attributes" + + Modify paragraph 1 of the description of glXQueryDrawable: + + ... must be set to one of GLX_WIDTH, GLX_HEIGHT, + GLX_PRESERVED_CONTENTS, GLX_LARGEST_PBUFFER, GLX_FBCONFIG_ID, + GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_TARGET_EXT or GLX_MIPMAP_TEXTURE_EXT + or a BadValue error is generated. + + Modify paragraph 3 of the description of glXQueryDrawable: + + ...If is a GLXWindow or GLXPixmap and is set to + GLX_PRESERVED_CONTENTS or GLX_LARGEST_PBUFFER, or if is a + GLXWindow or GLXPbuffer and is set to GLX_TEXTURE_FORMAT_EXT, + GLX_TEXTURE_TARGET_EXT, or GLX_MIPMAP_TEXTURE_EXT, the contents of + are undefined. + + Add a new section 3.3.6.1, "Texturing From Drawables" + + The command + + void glXBindTexImageEXT (Display *dpy, + GLXDrawable draw, + int buffer, + int *attrib_list); + + defines a one- or two-dimensional texture image. The texture image is taken + from and need not be copied. The texture target, the texture + format, and the size of the texture components are derived from attributes + of . + + The drawable attribute GLX_TEXTURE_FORMAT_EXT determines the base internal + format of the texture. The component sizes are also determined by drawable + attributes as shown in table 3.4a. + + Add new table 3.4a: Size of texture components: + + Texture component Size + ----------------- -------------- + R GLX_RED_SIZE + G GLX_GREEN_SIZE + B GLX_BLUE_SIZE + A GLX_ALPHA_SIZE + + The texture target is derived from the GLX_TEXTURE_TARGET_EXT attribute of + . If the texture target for the drawable is GLX_TEXTURE_2D_EXT or + GLX_TEXTURE_RECTANGLE_EXT, then buffer defines a 2D texture for the current + 2D or rectangle texture object respectively; if the texture target is + GLX_TEXTURE_1D_EXT, then buffer defines a 1D texture for the current 1D + texture object. + + If is not one of GLX_FRONT_LEFT_EXT, GLX_FRONT_RIGHT_EXT, + GLX_BACK_LEFT_EXT, GLX_BACK_RIGHT_EXT, or GLX_AUX0_EXT through + GLX_AUXn_EXT, where n is one less than the number of AUX buffers supported + by the FBConfig used to create , or if the requested buffer is + missing, a BadValue error is generated. + + specifies a list of attributes for the texture. The list has + the same structure as described for glXChooseFBConfig. If is + NULL or empty (first attribute of None), then all attributes assume their + default values. must be NULL or empty. + + If and are the display and drawable for the calling thread's + current context, glXBindTexImageEXT performs an implicit glFlush. + + The contents of the texture after the drawable has been bound are defined + as the result of all rendering that has completed before the call to + glXBindTexImageEXT. In other words, the results of any operation which + has caused damage on the drawable prior to the glXBindTexImageEXT call + will be represented in the texture. + + Rendering to the drawable while it is bound to a texture will leave the + contents of the texture in an undefined state. However, no + synchronization between rendering and texturing is done by GLX. It is + the application's responsibility to implement any synchronization + required. + + If a texture object is deleted before glXReleaseTexImageEXT is called, + the color buffer is released. + + It is not an error to call TexImage2D, TexImage1D, CopyTexImage1D, or + CopyTexImage2D to replace an image of a texture object that has a color + buffer bound to it. However, these calls will cause the color buffer to be + released and new memory to be allocated for the texture. Note that the + color buffer is released even if the image that is being defined is a mipmap + level that was not defined by the color buffer. GenerateMipmapEXT is an + exception. GenerateMipmapEXT can be used to define mipmap levels for + drawables that have been created with GLX_MIPMAP_TEXTURE_EXT set. Calling + GenerateMipmapEXT on a drawable that was created without + GLX_MIPMAP_TEXTURE_EXT is undefined. + + The results of calling glXBindTexImageEXT when GENERATE_MIPMAP_SGIS is TRUE + are undefined. + + If glXBindTexImageEXT is called and the drawable attribute + GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_NONE_EXT, then a BadMatch + error is generated. + + Currently, only pixmaps can be bound to textures. If is not a + valid GLXPixmap, then a GLXBadPixmap error is generated. + + glXBindTexImageEXT is ignored if there is no current GLX rendering context. + + To release a color buffer that is being used as a texture, call + + void glXReleaseTexImageEXT (Dislpay *dpy, GLXDrawable draw, int buffer); + + must be one of GLX_FRONT_LEFT_EXT, GLX_FRONT_RIGHT_EXT, + GLX_BACK_LEFT_EXT, GLX_BACK_RIGHT_EXT, and GLX_AUX0_EXT through + GLX_AUXn_EXT, where n is one less than the number of AUX buffers + supported by the FBConfig used to create or a BadValue error + is generated. + + The contents of the color buffer are unaffected by glXReleaseTexImageEXT. + + If the specified color buffer is no longer bound to a texture (e.g., + because the texture object was deleted), then glXReleaseTexImageEXT has no effect; + no error is generated. + + When a color buffer is released (e.g., by calling glXReleaseTexImageEXT or + implicitly by calling a routine such as TexImage2D), all textures that were + defined by the color buffer become NULL. + + If glXReleaseTexImageEXT is called and the drawable attribute + GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_NONE_EXT, then a BadMatch + error is generated. + + Currently, only pixmaps can be bound to textures. If is not a + valid GLXPixmap, then a GLXBadPixmap error is generated. + + +Usage Examples + + Example 1: Bind redirected window to texture: + + XGetWindowAttributes (display, window, &attrib); + + visualid = XVisualIDFromVisual (attrib.visual); + + fbconfigs = glXGetFBConfigs (display, screen, &nfbconfigs); + for (i = 0; i < nfbconfigs; i++) + { + visinfo = glXGetVisualFromFBConfig (display, fbconfigs[i]); + if (!visinfo || visinfo->visualid != visualid) + continue; + + glXGetFBConfigAttrib (display, fbconfigs[i], GLX_DRAWABLE_TYPE, &value); + if (!(value & GLX_PIXMAP_BIT)) + continue; + + glXGetFBConfigAttrib (display, fbconfigs[i], + GLX_BIND_TO_TEXTURE_TARGETS_EXT, + &value); + if (!(value & GLX_TEXTURE_2D_BIT_EXT)) + continue; + + glXGetFBConfigAttrib (display, fbconfigs[i], + GLX_BIND_TO_TEXTURE_RGBA_EXT, + &value); + if (value == FALSE) + { + glXGetFBConfigAttrib (display, fbconfigs[i], + GLX_BIND_TO_TEXTURE_RGB_EXT, + &value); + if (value == FALSE) + continue; + } + + glXGetFBConfigAttrib (display, fbconfigs[i], + GLX_Y_INVERTED_EXT, + &value); + if (value == TRUE) + { + top = 0.0f; + bottom = 1.0f; + } + else + { + top = 1.0f; + bottom = 0.0f; + } + + break; + } + + if (i == nfbconfigs) + /* error 1 */ + + pixmap = XCompositeNameWindowPixmap (display, window); + pixmapAttribs = { GLX_TEXTURE_TARGET_EXT, GLX_TEXTURE_2D_EXT, + GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_FORMAT_RGBA_EXT, + None }; + glxpixmap = glXCreatePixmap (display, fbconfigs[i], pixmap, pixmapAttribs); + + glGenTextures (1, &texture); + glBindTexture (GL_TEXTURE_2D, texture); + + glXBindTexImageEXT (display, glxpixmap, GLX_FRONT_LEFT_EXT, NULL); + + glTexParameteri (GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR); + glTexParameteri (GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR); + + /* draw using pixmap as texture */ + glBegin (GL_QUADS); + + glTexCoord2d (0.0f, bottom); + glVertex2d (0.0f, 0.0f); + + glTexCoord2d (0.0f, top); + glVertex2d (0.0f, 1.0f); + + glTexCoord2d (1.0f, top); + glVertex2d (1.0f, 1.0f); + + glTexCoord2d (1.0f, bottom); + glVertex2d (1.0f, 0.0f); + + glEnd (); + + glXReleaseTexImageEXT (display, glxpixmap, GLX_FRONT_LEFT_EXT); + + +Version History + + 1. 26 Nov 2005 - DavidR + Initial version + 2. 01 Dec 2005 - JamesJ + -Adapted spec language from draft version of GLX_ARB_render_texture. + -Added glXDrawableAttribute to set attributes. + -Modified glXBindTexImageEXT to take an attrib_list parameter. + -Added support for cubemap and 1D texture targets. + -Added attribute to set the texture target when creating the + drawable. + -Updated the issues section. + -Added mipmap support. Support is not required. + -Specified results of texturing from a drawable when it has been + rendered to while bound to a texture as undefined until + glXReleaseTexImageEXT has been called. Allows implementations + that need to perform an implicit copy after rendering occurs + to be compatible with this specification. + 3. 04 Dec 2005 - DavidR + -Changed name to GLX_EXT_texture_from_pixmap. + -Changed spec regarding what happens when a pixmap that is bound + to a texture is rendered to. Having textures be undefined once + they are rendered to makes it useless for a compositing manager, + which is a major use case for this extension. + -Added support for not specifying texture target when creating a + pixmap. Allows implementations to select whatever target it + finds most suitable. + 4. 05 Dec 2005 - JamesJ + -Changed the default value of GLX_TEXTURE_TARGET_EXT from + GLX_NO_TEXTURE_EXT to something usable. Eliminated + GLX_NO_TEXTURE_EXT. + -Eliminated GLX_TEXTURE_NONE_EXT. + -Removed language referring to sharing of color buffers when + pixmaps are bound to textures. + -Updated issues. + + 5. 13 Dec 2005 - JamesJ + -Removed cube map support and rendering to multiple mipmap + levels support. + + 6. 20 Jan 2006 - JamesJ + -Specified textures are y-inverted. + + 7. 23 Jan 2006 - AaronP + -Fix typos, make some things clearer. Replace ocurrences of "released + back to the drawable" with "released". + + 8. 01 Feb 2006 - AndyR + -Fix minor typos. + + 9. 03 Feb 2006 - JamesJ + -Added some new issues and their resolutions. + -Finalized some issues that had been in discussion. + -Made drawable y-inversion a queryable attribute of the drawable. + -Moved detailed explanation of y-inverted addressing to the issues + section + -Updated example to demonstrate proper use of the y-inverted + attribute. + + 10. 06 Feb 2006 - DavidR + -Made GLX_Y_INVERTED_EXT an FBConfig attribute instead of a drawable + attribute. + -Removed GLX_TEXTURE_CUBE_MAP_EXT. + -Fix minor typo. + + 11. 07 Feb 2006 - JamesJ + -Added description of GLX_Y_INVERTED_EXT GLXFBConfig attribute, based + on description of the drawable attribute of the same name from + and earlier version of the specification. + -Removed language requiring applications to re-bind a pixmap to a + texture to gurantee contents of the texture are updated after a + pixmap has been rendered to. + -Added Aaron Plattner and Andy Ritger to contributors section. + + 12. 14 Feb 2006 - JamesJ + -Disallowed rendering to a drawable while it is bound as a texture + and defined the exact contents of a texture after a drawable has + been bound to it. + + 13. 09 Mar 2006 - JamesJ + -Add a context tag member to the vendor private requests. This field + is part of the vendor private header, and is needed to specify which + context the BindTexImageEXT and ReleaseTexImageEXT requests correspond + to. + -Changed texture target bitfield values to not skip numbers removed in + earlier updates. + + 14. 13 Mar 2006 - JamesJ + -Only require GLX_SGIX_fbconfig + GLX 1.2. + -Clarify language regarding the result of rendering to drawables bound + to textures. + -Added GLX_FRONT_EXT and GLX_BACK_EXT tokens. + + 15. 18 Apr 2006 - JamesJ + -Allocated enum values and opcodes. + -Require GLX 1.3. GLX_SGIX_fbconfig doesn't allow creating pixmaps + with attributes. + -Added more arguments for not supporting rendering to multiple levels + of a texture with this extension. + -Fixed the inconsistencies in the return type of glXBindTexImageEXT + and glXReleaseTexImageEXT. It is now listed as void throughout. + + 16. 12 Sep 2006 - JamesJ + -Fix ordering of GLX protocol + + 17. 10 Feb 2009 - Jon Leech + -Fix typo reported by Jonathan Knispel.