Added files with xextproto 1.7.2
This commit is contained in:
matthieu
parent
75031d569b
commit
b645239963
77
proto/xextproto/specs/Makefile.am
Normal file
77
proto/xextproto/specs/Makefile.am
Normal file
@ -0,0 +1,77 @@
|
||||
#
|
||||
# Copyright (c) 2010, Oracle and/or its affiliates. All rights reserved.
|
||||
#
|
||||
# Permission is hereby granted, free of charge, to any person obtaining a
|
||||
# copy of this software and associated documentation files (the "Software"),
|
||||
# to deal in the Software without restriction, including without limitation
|
||||
# the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||
# and/or sell copies of the Software, and to permit persons to whom the
|
||||
# Software is furnished to do so, subject to the following conditions:
|
||||
#
|
||||
# The above copyright notice and this permission notice (including the next
|
||||
# paragraph) shall be included in all copies or substantial portions of the
|
||||
# Software.
|
||||
#
|
||||
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||
# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
||||
# DEALINGS IN THE SOFTWARE.
|
||||
#
|
||||
|
||||
if ENABLE_SPECS
|
||||
doc_sources = \
|
||||
appgroup.xml \
|
||||
dbe.xml \
|
||||
dpms.xml \
|
||||
evi.xml \
|
||||
geproto.xml \
|
||||
multibuf.xml \
|
||||
security.xml \
|
||||
shape.xml \
|
||||
shm.xml \
|
||||
sync.xml \
|
||||
tog-cup.xml \
|
||||
xtest.xml
|
||||
|
||||
dist_doc_DATA = $(doc_sources)
|
||||
|
||||
if HAVE_XMLTO
|
||||
doc_DATA = $(doc_sources:.xml=.html)
|
||||
|
||||
if HAVE_FOP
|
||||
doc_DATA += $(doc_sources:.xml=.ps) $(doc_sources:.xml=.pdf)
|
||||
endif
|
||||
|
||||
if HAVE_XMLTO_TEXT
|
||||
doc_DATA += $(doc_sources:.xml=.txt)
|
||||
endif
|
||||
|
||||
if HAVE_STYLESHEETS
|
||||
XMLTO_FLAGS = -m $(XSL_STYLESHEET)
|
||||
|
||||
doc_DATA += xorg.css
|
||||
xorg.css: $(STYLESHEET_SRCDIR)/xorg.css
|
||||
$(AM_V_GEN)cp -pf $(STYLESHEET_SRCDIR)/xorg.css $@
|
||||
endif
|
||||
|
||||
CLEANFILES = $(doc_DATA)
|
||||
|
||||
SUFFIXES = .xml .ps .pdf .txt .html
|
||||
|
||||
.xml.txt:
|
||||
$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) txt $<
|
||||
|
||||
.xml.html:
|
||||
$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks $<
|
||||
|
||||
.xml.pdf:
|
||||
$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop pdf $<
|
||||
|
||||
.xml.ps:
|
||||
$(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop ps $<
|
||||
|
||||
endif HAVE_XMLTO
|
||||
endif ENABLE_SPECS
|
||||
248
proto/xextproto/specs/appgroup.xml
Normal file
248
proto/xextproto/specs/appgroup.xml
Normal file
@ -0,0 +1,248 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
|
||||
|
||||
|
||||
<book id="appgroup">
|
||||
|
||||
<bookinfo>
|
||||
<title>Description of the Application Group Extension</title>
|
||||
<subtitle>Implementation for the X11 Sample Server</subtitle>
|
||||
<releaseinfo>Version 1.0</releaseinfo>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Kaleb </firstname><surname>KEITHLEY</surname>
|
||||
<affiliation><orgname>FUJITSU Limited.</orgname></affiliation>
|
||||
<email>blah@blah.com</email>
|
||||
</author>
|
||||
</authorgroup>
|
||||
<corpname>X Consortium Standard</corpname>
|
||||
<copyright><year>1996</year><holder>X Consortium</holder></copyright>
|
||||
<affiliation><orgname>X Consortium</orgname></affiliation>
|
||||
<productnumber>X Version 11, Release 7</productnumber>
|
||||
|
||||
<abstract>
|
||||
<para>
|
||||
The following document explains the server side of the Application
|
||||
Group Extension.
|
||||
</para>
|
||||
</abstract>
|
||||
|
||||
<legalnotice>
|
||||
|
||||
|
||||
<para>
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The above copyright notice and this permission notice shall be included in
|
||||
all copies or substantial portions of the Software.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
|
||||
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
||||
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following document explains the server side of the Application
|
||||
Group Extension.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
WindowsNT is a trademark of Microsoft, Inc. Macintosh and Apple
|
||||
are trademarks of Apple Computer, Inc. X Window System is a
|
||||
trademark of X Consortium, Inc.
|
||||
</para>
|
||||
</legalnotice>
|
||||
</bookinfo>
|
||||
|
||||
<chapter>
|
||||
<title>TITLE</title>
|
||||
<para>
|
||||
To understand this document and the accompanying source code, you
|
||||
should know the C language, should be familiar with X server
|
||||
internals, and should also have a general knowledge of the X
|
||||
Window System.
|
||||
</para>
|
||||
|
||||
<sect1 id="AppGroup_Server_Public_Functions">
|
||||
<title>AppGroup Server Public Functions</title>
|
||||
<para>
|
||||
The AppGroup extension adds seven new functions that are called
|
||||
from elsewhere in the server. They are: XagExtensionInit,
|
||||
XagDefaultColormap, XagRootVisual, XagLeader, XagIsControlledRoot,
|
||||
XagConnectionInfo, XagCallClientStateChange.
|
||||
</para>
|
||||
<para>
|
||||
XagExtensionInit is the extension initialization function called
|
||||
from InitExtension in mi/miinitext.c. Note that an new resource
|
||||
type, RT_APPGROUP, is created, specifying the destructor function
|
||||
XagAppGroupFree.
|
||||
</para>
|
||||
<para>
|
||||
XagDefaultColormap returns the colormap ID that was specified in
|
||||
the creation of the AppGroup. Any time CopyFromParent is specified
|
||||
for a top-level window's colormap, i.e. in a CreateWindow or
|
||||
ChangeWindowAttributes request, this function is called to see
|
||||
if there is an AppGroup specific colormap to use. If there is
|
||||
one, its ID is returned, otherwise None is returned.
|
||||
</para>
|
||||
<para>
|
||||
XagRootVisual returns the visual ID that was specified in the
|
||||
creation of the Appgroup. Like XagDefaultColormap, when CopyFromParent
|
||||
is specified for a top-level window's visual in a CreateWindow
|
||||
request, this function is called to see if there is an AppGroup
|
||||
specific visual to use. If there is one, its ID is returned,
|
||||
otherwise 0 (zero) is returned.
|
||||
</para>
|
||||
<para>
|
||||
XagLeader returns the ClientPtr of the client that is the AppGroup
|
||||
Leader. Normally when an application maps or configures a top-level
|
||||
window a MapRequest or ConfigureRequest event is delivered to the
|
||||
client, e.g. a window manager, that has selected SubstructureRedirect
|
||||
on the root window. However, when the application is part of an
|
||||
AppGroup, the MapRequest and ConfigureRequest events are delivered
|
||||
to the AppGroup Leader instead.
|
||||
</para>
|
||||
<para>
|
||||
XagIsControlledRoot returns a boolean: True if the window is a
|
||||
top-level window of a client in an AppGroup, False otherwise.
|
||||
In a combined server, i.e. one that provides both UI and printing,
|
||||
the application may create and map windows on the "printing"
|
||||
screens; thus it becomes necessary to discriminate between the
|
||||
AppGroup's root window and other root windows. If an AppGroup
|
||||
member creates and maps a [top-level] window then the window's
|
||||
parent [the root window] is tested to determine whether to send
|
||||
MapRequest or ConfigureRequest events to the AppGroup Leader to
|
||||
to some other client.
|
||||
</para>
|
||||
<para>
|
||||
In the trivial case XagIsControlledRoot returns True if the parent
|
||||
window has no parent itself, i.e. it is a root window. In the case
|
||||
where the application is embedded, indicated by the singleScreen
|
||||
attribute being True, the parent's drawable ID is compared to the
|
||||
AppGroup's root window ID, and if it is the same, True is returned.
|
||||
If neither case is true, then False is returned.
|
||||
</para>
|
||||
<para>
|
||||
XagConnectionInfo returns an abreviated version of the connection
|
||||
setup information. When an embedded AppGroup is created the server
|
||||
returns only the information about the [UI] screen that the
|
||||
application is embedded within in the connection setup in order to
|
||||
prevent the application from creating windows on other screens;
|
||||
thus attempting to guarantee that any window that should be embedded
|
||||
can be reparented into the AppGroup Leader's window hierarchy.
|
||||
</para>
|
||||
<para>
|
||||
XagCallClientStateChange is called to invoke the extension's client
|
||||
state change callback additional times as necessary -- currently
|
||||
only once, after the auth data becomes available between
|
||||
ClientStateInitial and ClientStateConnected. Client state change
|
||||
callbacks were introduced in the Record extension, which specifies
|
||||
when the callbacks are invoked. Unfortunately the points at which
|
||||
they are called are not necessarily the best as far as the AppGroup
|
||||
Extension is concerned. Adding an additional state and calling all
|
||||
the callbacks works too, however this seemed unnecessary overkill.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="AppGroup_Server_Private_APIs">
|
||||
<title>AppGroup Server Private APIs</title>
|
||||
<para>
|
||||
The AppGroup extension adds the following functions which are
|
||||
private to the extension: ProcXagDispatch and SProcXagDispatch,
|
||||
ProcXagQueryVersion and SProcXagQueryVersion, ProcXagCreate and
|
||||
SProcXagCreate, ProcXagDestroy and SProcXagDestroy,
|
||||
ProcGetAttr and SProcGetAttr, ProcXagQuery and SProcXagQuery,
|
||||
ProcXagCreateAssoc and SProcXagCreateAssoc, ProcXagDestroyAssoc
|
||||
and SProcXagDestroyAssoc, XagResetProc, and XagAppGroupFree.
|
||||
</para>
|
||||
<para>
|
||||
The ProcXagDispatch, SProcXagDispatch, and XagResetProc functions
|
||||
should be familiar to anyone familiar with X server internals and
|
||||
I won't elaborate on them here. Similarly the wrapper functions:
|
||||
SProcXagQueryVersion, SProcXagCreate, SProcXagDestroy, SProcXagGetAttr,
|
||||
SProcXagQuery, SProcXagCreateAssoc, and SProcXagDestroyAssoc, as
|
||||
wrappers which handle swapping integer data into the host's byte
|
||||
order will not be explained in any detail.
|
||||
</para>
|
||||
<para>
|
||||
ProcXagQueryVersion returns the major and minor versions of the
|
||||
AppGroup extension supported by the server.
|
||||
</para>
|
||||
<para>
|
||||
ProcXagCreate creates an AppGroup. A new record in a linked list
|
||||
of AppGroups is allocated and initialized. The attributes from the
|
||||
request are validated and copied to the AppGroup record. If necessary
|
||||
an abbreviated version of the connection setup information is compiled
|
||||
and also stored in the AppGroup record. The first time an AppGroup
|
||||
is created a client-state-change callback is registered and a
|
||||
reference count is incremented.
|
||||
</para>
|
||||
<para>
|
||||
ProcXagDestroy destroys an AppGroup an AppGroup by calling
|
||||
FreeResource specifying the AppGroup ID. This will result in
|
||||
the destructor function XagAppGroupFree being called. The
|
||||
reference count is decremented and when it reaches zero the
|
||||
client-state-change callback is deleted.
|
||||
</para>
|
||||
<para>
|
||||
ProcXagGetAttr returns the AppGroup Attributes to the requesting
|
||||
client.
|
||||
</para>
|
||||
<para>
|
||||
ProcXagQuery returns the AppGroup ID of an arbitrary resource to
|
||||
the requesting client.
|
||||
</para>
|
||||
<para>
|
||||
ProcXagCreateAssoc creates an association between an X window ID
|
||||
and system-specific data. In native X this functionality is
|
||||
unnecessary but for various personal computers, e.g. Macintosh,
|
||||
OS/2, and MS-Windows it is necessary to associate an X window ID
|
||||
with the system's native window identifier so that when the
|
||||
AppGroup Leader issues a ReparentWindow request the personal
|
||||
computer X server can lookup the system-specific window ID and
|
||||
make the necessary function call(s) with it.
|
||||
</para>
|
||||
<para>
|
||||
ProcXagDestroyAssoc destroys the association created with
|
||||
ProcXagCreateAssoc.
|
||||
</para>
|
||||
<para>
|
||||
XagResetProc removes the client-state-change callback, sets the
|
||||
reference count to zero, and frees all the AppGroup records in
|
||||
the linked list by calling XagAppGroupFree.
|
||||
</para>
|
||||
<para>
|
||||
XagAppGroupFree calls CloseDownClient for each client in an
|
||||
AppGroup if the AppGroup has a leader, unlinks the AppGroup
|
||||
record from the linked list, frees allocated memory referenced
|
||||
by the record, and finally frees the record itself.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Known_Problems_in_this_release_">
|
||||
<title>Known Problems in this release.</title>
|
||||
<para>
|
||||
In a combined UI/Print server the connection setup returned to an
|
||||
embedded application will not have information about the print
|
||||
screens.
|
||||
</para>
|
||||
<para>
|
||||
The LBX proxy caches connection setup information and will return
|
||||
incorrect connection setup information to an embedded client.
|
||||
</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
</book>
|
||||
1061
proto/xextproto/specs/dbe.xml
Normal file
1061
proto/xextproto/specs/dbe.xml
Normal file
File diff suppressed because it is too large
Load Diff
563
proto/xextproto/specs/dpms.xml
Normal file
563
proto/xextproto/specs/dpms.xml
Normal file
@ -0,0 +1,563 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
|
||||
|
||||
<book id="dpms">
|
||||
|
||||
<bookinfo>
|
||||
<title>X Display Power Management Signaling (DPMS) Extension Protocol Specification</title>
|
||||
<subtitle>X Project Team Standard</subtitle>
|
||||
<releaseinfo>Version 1.0</releaseinfo>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Rob </firstname><surname>Lembree</surname>
|
||||
<affiliation><orgname>Digital Equipment Corporation</orgname></affiliation>
|
||||
<email>lembree@zk3.dec.com</email>
|
||||
</author>
|
||||
</authorgroup>
|
||||
<corpname>X Consortium Standard</corpname>
|
||||
<copyright><year>1996</year><holder>Digital Equipment Corporation</holder></copyright>
|
||||
<affiliation><orgname>X Consortium</orgname></affiliation>
|
||||
<productnumber>X Version 11, Release 6.8</productnumber>
|
||||
|
||||
<legalnotice>
|
||||
<para>
|
||||
Permission to use, copy, modify, distribute, and sell this
|
||||
documentation for any purpose is hereby granted without fee,
|
||||
provided that the above copyright notice and this permission
|
||||
notice appear in all copies. Digital Equipment Corporation
|
||||
makes no representations about the suitability for any purpose
|
||||
of the information in this document. This documentation is
|
||||
provided "as is" without express or implied warranty.
|
||||
</para>
|
||||
|
||||
</legalnotice>
|
||||
</bookinfo>
|
||||
|
||||
<chapter>
|
||||
<title>TITLE</title>
|
||||
<sect1 id="Overview">
|
||||
<title>Overview</title>
|
||||
<para>
|
||||
This extension provides X Protocol control over the VESA Display
|
||||
Power Management Signaling (DPMS) characteristics of video boards
|
||||
under control of the X Window System.<footnote>
|
||||
<para>
|
||||
<emphasis remap='I'>X Window System</emphasis> is a trademark of The Open Group.
|
||||
</para>
|
||||
</footnote>
|
||||
</para>
|
||||
|
||||
|
||||
<para>
|
||||
<!-- .LP -->
|
||||
Traditionally, the X Window System has provided for both blanking and
|
||||
non-blanking screen savers. Timeouts associated with these built-in
|
||||
screen saver mechanisms are limited to idle (dwell) time, and a change
|
||||
timeout that specifies the change interval for non-blanking screen savers.
|
||||
</para>
|
||||
<para>
|
||||
<!-- .LP -->
|
||||
The United States' Environmental Protection Agency (EPA) Energy Star program
|
||||
requires that monitors power down after some idle time by default.
|
||||
While it is possible to simply overload the existing screen saver timeouts,
|
||||
this solution leaves the non-privileged user little to no control over
|
||||
the DPMS characteristics of his or her system. For example, disabling
|
||||
DPMS would require some unintended side effect in the core screen saver,
|
||||
such as disabling the changing of a non-blanking screen saver. Providing
|
||||
clients with this control requires an extension to the core X Window System
|
||||
Protocol, and this extension seeks to fill this gap.
|
||||
</para>
|
||||
<para>
|
||||
<!-- .LP -->
|
||||
The design goal of the DPMS extension is to be a logical extension to
|
||||
the traditional screen saver. The protocol and sample implementation is
|
||||
designed to use the same date types and time units as the screen saver.
|
||||
The sample implementation works independently from the screen saver so that
|
||||
policy as it pertains to the interaction between screen saver and DPMS can
|
||||
be deferred to the user or screen saver application. The extension has
|
||||
been tested with and shown to work correctly with both the internal blanking
|
||||
and non-blanking screen savers, as well as with screen saver extension
|
||||
clients.
|
||||
</para>
|
||||
<para>
|
||||
The DPMS extension is designed to be simple, yet export sufficient
|
||||
VESA DPMS information to enable full function clients to be written.
|
||||
Included is the ability to sense DPMS capability, set and get DPMS timeouts,
|
||||
enable and disable individual DPMS modes, enable and disable DPMS (without
|
||||
destroying timeout values), and sense current DPMS on/off state and
|
||||
power level.
|
||||
</para>
|
||||
<para>
|
||||
There are four power levels specified by the Video Electronics Standards
|
||||
Association (VESA) Display Power Management Signaling (DPMS) standard.
|
||||
These are:
|
||||
</para>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>DPMS Extension Power Levels</function>
|
||||
0 DPMSModeOn In use
|
||||
1 DPMSModeStandby Blanked, low power
|
||||
2 DPMSModeSuspend Blanked, lower power
|
||||
3 DPMSModeOff Shut off, awaiting activity
|
||||
</literallayout>
|
||||
|
||||
<para>
|
||||
It is logical to assume that successive DPMS modes be chronologically
|
||||
at the same time or later than one another, and the protocol is designed
|
||||
to enforce this rule.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Note however that a concious decision is made to decouple the timeouts
|
||||
associated with screen saver from the DPMS timeouts. While it might be
|
||||
considered logical to require that the first non-zero DPMS timeout be
|
||||
greater than or equal to the screen saver timeout, this is intentionally
|
||||
omitted, leaving this policy decision to the user or the screen saver
|
||||
application. In the case of a laptop where power may be scarce, the
|
||||
importance of power savings should supersede the screen saver. If the
|
||||
laptop user plugs the unit in and power is no longer a scarce commodity,
|
||||
it may be decided to make DPMS less aggressive, or disable it completely.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Requests">
|
||||
<title>Requests</title>
|
||||
<para>
|
||||
<function>DPMSGetVersion</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>client_major_version</emphasis>: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>client_minor_version</emphasis>: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>=></entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>server_major_version</emphasis>: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>server_minor_version</emphasis>: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
If supplied, the <emphasis remap='I'>client_major_version</emphasis> and
|
||||
<emphasis remap='I'>client_minor_version</emphasis> indicate what version
|
||||
of the protocol the
|
||||
client wants the server to implement. The server version numbers
|
||||
returned indicate the protocol this extension actually supports. This
|
||||
might not equal the version sent by the client. An implementation can
|
||||
(but need not) support more than one version simultaneously. The
|
||||
<emphasis remap='I'>server_major_version</emphasis> and the
|
||||
<emphasis remap='I'>server_minor_version</emphasis> are a
|
||||
mechanism to support future revisions of the Display Power Management
|
||||
Signaling protocol which may be necessary. In general, the major version
|
||||
would increment for incompatible changes, and the minor version would
|
||||
increment for small, upward-compatible changes. Servers that support the
|
||||
protocol defined in this document will return a
|
||||
<emphasis remap='I'>server_major_version</emphasis>
|
||||
of one (1), and a <emphasis remap='I'>server_minor_version</emphasis>
|
||||
of one (1).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>DPMSCapable</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>=></entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>capable</emphasis>: BOOL
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
This request is used to determine whether or not the currently running
|
||||
server's devices are capable of DPMS operations. The truth value of this
|
||||
request is implementation defined, but is generally based on the capabilities
|
||||
of the graphic card and monitor combination. Also, the return value in the
|
||||
case of heterogeneous multi-head servers is implementation defined.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>DPMSGetTimeouts</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>=></entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>standby_timeout</emphasis>: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>suspend_timeout</emphasis>: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>off_timeout</emphasis>: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
This request returns the current values of the DPMS timeout values. All
|
||||
values are in units of seconds.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<emphasis remap='I'>standby_timeout</emphasis> is the amount of time
|
||||
of inactivity before standby
|
||||
mode is invoked. The actual effects of this mode are implementation defined,
|
||||
but in the case of DPMS compliant hardware, it is implemented by shutting off
|
||||
the horizontal sync signal, and pulsing the vertical sync signal. Standby
|
||||
mode provides the quickest monitor recovery time. Note also that many
|
||||
monitors implement this mode identically to suspend mode. A value of
|
||||
zero indicates that this mode is disabled.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<emphasis remap='I'>suspend_timeout</emphasis> is the amount of time
|
||||
of inactivity before the second
|
||||
level of power savings is invoked. Suspend mode's physical and electrical
|
||||
characteristics are implementation defined, but in DPMS compliant hardware,
|
||||
results in the pulsing of the horizontal sync signal, and shutting off of
|
||||
the vertical sync signal. Suspend mode recovery is considered to be slower
|
||||
than standby mode, but faster than off mode, however this is monitor
|
||||
dependent. As noted above, many monitors implement this mode identically to
|
||||
standby mode. A value of zero indicates that this mode is disabled.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<emphasis remap='I'>off_timeout</emphasis> is the amount of time of
|
||||
inactivity before the third and
|
||||
final level of power savings is invoked. Off mode's physical and electrical
|
||||
characteristics are implementation defined, but in DPMS compliant hardware,
|
||||
is implemented by shutting off both horizontal and vertical sync signals,
|
||||
resulting in the power-down of the monitor. Recovery time is implementation
|
||||
dependant, but frequently is similar to the power-up time of the monitor. A
|
||||
value of zero indicates that this mode is disabled.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>DPMSSetTimeouts</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>standby_timeout</emphasis>: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>suspend_timeout</emphasis>: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>off_timeout</emphasis>: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>=></entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
|
||||
<para>
|
||||
All values are in units of seconds.
|
||||
<emphasis remap='I'>standby_timeout</emphasis> is the amount of
|
||||
time of inactivity before standby mode will be invoked. This is the
|
||||
lightest level of power savings, and the monitor is generally immediately
|
||||
ready upon detection of user activity. This is most often implemented by
|
||||
shutting off the horizontal sync signal to the monitor.
|
||||
A value of zero disables this mode.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <emphasis remap='I'>suspend_timeout</emphasis> specifies the amount
|
||||
of time of inactivity
|
||||
before the screen is placed into suspend mode. Suspend mode is the
|
||||
middle level of power savings, resulting in a slightly longer recovery
|
||||
upon detection of activity. Suspend mode is most often implemented by
|
||||
pulsing the horizontal sync signal, and removing the vertical sync
|
||||
signal. A value of zero disables this mode.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <emphasis remap='I'>off_timeout</emphasis> specifies the amount of
|
||||
time of inactivity before
|
||||
the monitor is shut off. Off mode is the deepest level of power management,
|
||||
resulting in the greatest power savings and the longest recovery time.
|
||||
Off mode is most often implemented by removing both the horizontal and
|
||||
vertical signals. A value of zero disables this mode.
|
||||
</para>
|
||||
<para>
|
||||
The values of successive power levels must be greater than or equal
|
||||
to the value of the previous (non-zero) level. A BadValue error is generated
|
||||
if an illegal combination is detected.
|
||||
</para>
|
||||
<para>
|
||||
<function>DPMSEnable</function>
|
||||
</para>
|
||||
<para>
|
||||
=>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This request enables the DPMS characteristics of the server, using the
|
||||
server's currently stored timeouts. If DPMS is already enabled, no change is
|
||||
effected.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>DPMSDisable</function>
|
||||
</para>
|
||||
<para>
|
||||
=>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This request disables the DPMS characteristics of the server. It does
|
||||
not affect the core or extension screen savers. If DPMS is already
|
||||
disabled, no change is effected. This request is provided so that DPMS
|
||||
may be disabled without damaging the server's stored timeout values.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>DPMSForceLevel</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>power_level</emphasis>: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>=></entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
This request forces a specific DPMS level on the server. If DPMS is
|
||||
disabled, a BadMatch error is generated. If an erroneous power level
|
||||
is specified, a BadValue error is returned, and the error value contains
|
||||
the bad value. If the power level specified is already in effect, no
|
||||
changes occur. Power Level must be one of DPMSModeOn, DPMSModeStandby,
|
||||
DPMSModeSuspend or DPMSModeOff.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>DPMSInfo</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>=></entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>power_level</emphasis>: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>state</emphasis>: BOOL
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
This request returns information about the current DPMS state of the
|
||||
display. <emphasis remap='I'>state</emphasis> is one of DPMSEnabled
|
||||
or DPMSDisabled.
|
||||
If <emphasis remap='I'>state</emphasis> is DPMSEnabled,
|
||||
<emphasis remap='I'>power_level</emphasis> is returned as one
|
||||
of DPMSModeOn, DPMSModeStandby, DPMSModeSuspend or DPMSModeOff, otherwise
|
||||
it is undefined.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Events_and_Errors">
|
||||
<title>Events and Errors</title>
|
||||
<para>
|
||||
No new events or errors are defined by this extension.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Encoding">
|
||||
<title>Encoding</title>
|
||||
<para>
|
||||
Please refer to the X11 Protocol Encoding document as this document uses
|
||||
conventions established there.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The name of this extension is "DPMS".
|
||||
</para>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>DPMSGetVersion</function>
|
||||
1 CARD8 opcode
|
||||
1 0 DPMS opcode
|
||||
2 2 request length
|
||||
2 CARD16 client_major_version
|
||||
2 CARD16 client_minor_version
|
||||
=>
|
||||
1 1 Reply
|
||||
1 unused
|
||||
2 CARD16 sequence number
|
||||
4 0 length
|
||||
2 CARD16 server_major_version
|
||||
2 CARD16 server_minor_version
|
||||
20 unused
|
||||
</literallayout>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>DPMSCapable</function>
|
||||
1 CARD8 opcode
|
||||
1 1 DPMS opcode
|
||||
2 1 request length
|
||||
=>
|
||||
1 1 Reply
|
||||
1 unused
|
||||
2 CARD16 sequence number
|
||||
4 0 length
|
||||
1 BOOL capable
|
||||
23 unused
|
||||
</literallayout>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>DPMSGetTimeouts</function>
|
||||
1 CARD8 opcode
|
||||
1 2 DPMS opcode
|
||||
2 1 request length
|
||||
=>
|
||||
1 1 Reply
|
||||
1 unused
|
||||
2 CARD16 sequence number
|
||||
4 0 length
|
||||
2 CARD16 standby_timeout
|
||||
2 CARD16 suspend_timeout
|
||||
2 CARD16 off_timeout
|
||||
18 unused
|
||||
</literallayout>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>DPMSSetTimeouts</function>
|
||||
1 CARD8 opcode
|
||||
1 3 DPMS opcode
|
||||
2 3 request length
|
||||
2 CARD16 standby_timeout
|
||||
2 CARD16 suspend_timeout
|
||||
2 CARD16 off_timeout
|
||||
2 unused
|
||||
=>
|
||||
</literallayout>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>DPMSEnable</function>
|
||||
1 CARD8 opcode
|
||||
1 4 DPMS opcode
|
||||
2 1 request length
|
||||
=>
|
||||
</literallayout>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>DPMSDisable</function>
|
||||
1 CARD8 opcode
|
||||
1 5 DPMS opcode
|
||||
2 1 request length
|
||||
=>
|
||||
</literallayout>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>DPMSForceLevel</function>
|
||||
1 CARD8 opcode
|
||||
1 6 DPMS opcode
|
||||
2 2 request length
|
||||
2 power_level
|
||||
0 DPMSModeOn
|
||||
1 DPMSModeStandby
|
||||
2 DPMSModeSuspend
|
||||
3 DPMSModeOff
|
||||
2 unused
|
||||
=>
|
||||
</literallayout>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>DPMSInfo</function>
|
||||
1 CARD8 opcode
|
||||
1 7 DPMS opcode
|
||||
2 1 request length
|
||||
=>
|
||||
1 1 Reply
|
||||
1 unused
|
||||
2 CARD16 sequence number
|
||||
4 0 length
|
||||
2 power_level
|
||||
0 DPMSModeOn
|
||||
1 DPMSModeStandby
|
||||
2 DPMSModeSuspend
|
||||
3 DPMSModeOff
|
||||
1 BOOL state
|
||||
21 unused
|
||||
|
||||
</literallayout>
|
||||
</sect1>
|
||||
</chapter>
|
||||
</book>
|
||||
518
proto/xextproto/specs/evi.xml
Normal file
518
proto/xextproto/specs/evi.xml
Normal file
@ -0,0 +1,518 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
|
||||
|
||||
|
||||
<book id="evi">
|
||||
|
||||
<bookinfo>
|
||||
<title>Extended Visual Information Extension</title>
|
||||
<subtitle>X Project Team Standard</subtitle>
|
||||
<releaseinfo>Version 1.0</releaseinfo>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Peter</firstname><surname>Daifuku</surname>
|
||||
<affiliation><orgname>Silicon Graphics, Inc.</orgname></affiliation>
|
||||
</author>
|
||||
</authorgroup>
|
||||
<corpname>X Consortium Standard</corpname>
|
||||
<copyright><year>1986-97</year><holder>The Open Group</holder></copyright>
|
||||
<affiliation><orgname>X Consortium</orgname></affiliation>
|
||||
<productnumber>X Version 11, Release 6.8</productnumber>
|
||||
|
||||
<legalnotice>
|
||||
|
||||
<para>
|
||||
Permission is hereby granted, free of charge, to any person obtaining a
|
||||
copy of this
|
||||
software and associated documentation files (the Software), to use the
|
||||
Software without restriction, including, without limitation, the rights to
|
||||
copy, modify, merge, publish, distribute and sublicense the Software,
|
||||
to make, have made, license and distribute derivative works thereof, and
|
||||
to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The above copyright notice and the following permission notice shall be
|
||||
included in all copies of the Software:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE WARRANTIES
|
||||
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-
|
||||
INFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY
|
||||
CLAIM, DAMAGES OR OTHER USEABILITIY, WHETHER IN AN ACTION OF
|
||||
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF, OR IN
|
||||
CONNNECTION WITH THE SOFTWARE OR THE USE OF OTHER DEALINGS IN
|
||||
THE SOFTWARE.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Except as contained in this notice, the name of The Open Group shall not
|
||||
be used in advertising or otherwise to promote the use or other dealings
|
||||
in this Software without prior written authorization from The Open Group.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
X Window System is a trademark of The Open Group.
|
||||
</para>
|
||||
|
||||
</legalnotice>
|
||||
</bookinfo>
|
||||
|
||||
<chapter>
|
||||
<title>TITLE</title>
|
||||
<sect1 id="Introduction">
|
||||
<title>Introduction</title>
|
||||
<para>
|
||||
EVI (Extended Visual Information extension) allows a client to determine
|
||||
information about core X visuals beyond what the core protocol provides.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Goals">
|
||||
<title>Goals</title>
|
||||
<para>
|
||||
As the X Window System has evolved, it has become clear that the information
|
||||
returned by the core X protocol regarding Visuals is often insufficient for a
|
||||
client to determine which is the most appropriate visual for its needs. This
|
||||
extension allows clients to query the X server for additional visual
|
||||
information, specifically as regards colormaps and framebuffer levels.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This extension is meant to address the needs of pure X clients only. It is
|
||||
specifically and purposefully not designed to address the needs of X
|
||||
extensions. Extensions that have an impact on visual information should provide
|
||||
their own mechanisms for delivering that information. For example, the Double
|
||||
Buffering Extension (DBE) provides its own mechanism for determining which
|
||||
visuals support double-buffering.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Requests">
|
||||
<title>Requests</title>
|
||||
<para>
|
||||
<function>GetVersion</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>client_major_version</emphasis>: CARD8
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>client_minor_version</emphasis>: CARD8
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
=>
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>server_major_version</emphasis>: CARD8
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>server_minor_version</emphasis>: CARD8
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
|
||||
|
||||
<para>
|
||||
If supplied, the client_major_version and client_minor_version indicate
|
||||
what version of the protocol the client wants the server to implement.
|
||||
The server version numbers returned indicate the protocol this extension
|
||||
actually supports. This might not equal the version sent by the client.
|
||||
An implementation can (but need not) support more than one version
|
||||
simultaneously. The server_major_version and the server_minor_version
|
||||
are a mechanism to support future revisions of the EVI protocol that
|
||||
may be necessary. In general, the major version would increment for
|
||||
incompatible changes, and the minor version would increment for small
|
||||
upward-compatible changes. Servers that support the protocol defined in
|
||||
this document will return a server_major_version of one (1), and a
|
||||
server_minor_version of zero (0).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function> GetVisualInfo</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>visual_list</emphasis>: LISTofVISUALID
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
=>
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>per_visual_info</emphasis>: LISTofVISUALINFO
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
where:
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
VISUALINFO: [core_visual_id: VISUALID
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
screen: CARD8
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
level: INT8
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
transparency_type: CARD8
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
unused: CARD8
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
transparency_value: CARD32
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
min_hw_colormaps: CARD8
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
max_hw_colormaps: CARD8
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
num_colormap_conflicts: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
colormap_conflicts: LISTofVISUALID]
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
level is 0 for normal planes, > 0 for overlays, < 0 for underlays.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
transparency_type is 0 for none, 1 for transparent pixel, 2 for
|
||||
transparent mask.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
transparency_value: value to get transparent pixel if transparency
|
||||
supported.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
min_hw_colormaps: minimum number of hardware colormaps backing up the
|
||||
visual.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
max_hw_colormaps: maximum number of hardware colormaps backing up the
|
||||
visual.
|
||||
</para>
|
||||
<para>
|
||||
(architectures with static colormap allocation/reallocation would have min
|
||||
= max)
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
num_colormap_conflicts: number of elements in colormap_conflicts.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
colormap_conflicts: list of visuals that may conflict with this one. For
|
||||
example, if a 12-bit colormap is overloaded to support 8-bit visuals, the
|
||||
8-bit visuals would conflict with the 12-bit visuals.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</sect1>
|
||||
<sect1 id="Events_and_Errors">
|
||||
<title>Events and Errors</title>
|
||||
<para>
|
||||
No new events or errors are defined by this extension.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Changes_to_existing_protocol_">
|
||||
<title>Changes to existing protocol.</title>
|
||||
<para>
|
||||
None.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Encoding">
|
||||
<title>Encoding</title>
|
||||
<para>
|
||||
The name of this extension is "Extended-Visual-Information".
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The conventions used here are the same as those for the core X11
|
||||
Protocol Encoding.
|
||||
</para>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>GetVersion</function>
|
||||
1 CARD8 opcode
|
||||
1 0 EVI opcode
|
||||
2 2 request length
|
||||
2 CARD16 client_major_version
|
||||
2 CARD16 client_minor_version
|
||||
=>
|
||||
1 1 reply
|
||||
1 unused
|
||||
2 CARD16 sequence number
|
||||
4 0 length
|
||||
2 CARD16 server_major_version
|
||||
2 CARD16 server_minor_version
|
||||
20 unused
|
||||
</literallayout>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>GetVisualInfo</function>
|
||||
1 CARD8 opcode
|
||||
1 1 EVI opcode
|
||||
2 2+n request length
|
||||
4 CARD32 n_visual
|
||||
4n CARD32 visual_ids
|
||||
=>
|
||||
1 1 reply
|
||||
1 unused
|
||||
2 CARD16 sequence number
|
||||
4 n length
|
||||
4 CARD32 n_info
|
||||
4 CARD32 n_conflicts
|
||||
16 unused
|
||||
16n LISTofVISUALINFO items
|
||||
</literallayout>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
VISUALINFO
|
||||
4 VisualID core_visual_id
|
||||
1 INT8 screen
|
||||
1 INT8 level
|
||||
1 CARD8 transparency_type
|
||||
1 CARD8 unused
|
||||
4 CARD32 transparency_value
|
||||
1 CARD8 min_hw_colormaps
|
||||
1 CARD8 max_hw_colormaps
|
||||
2 CARD16 num_colormap_conflicts
|
||||
</literallayout>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="C_Language_Binding">
|
||||
<title>C Language Binding</title>
|
||||
<para>
|
||||
<!-- .LP -->
|
||||
The C functions provide direct access to the protocol and add no additional
|
||||
semantics. For complete details on the effects of these functions, refer
|
||||
to the appropriate protocol request, which can be derived by deleting Xevi
|
||||
at the start of the function. All functions that have return type Status
|
||||
will return nonzero for success and zero for failure.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The include file for this extension is:
|
||||
<function>< X11/extensions/XEVI.h></function>.
|
||||
</para>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>Bool <function> XeviQueryVersion</function></funcdef>
|
||||
<paramdef>Display<parameter> *display</parameter></paramdef>
|
||||
<paramdef>int<parameter> *major_version_return</parameter></paramdef>
|
||||
<paramdef>int<parameter> *minor_version_return</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>display</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Specifies the connection to the X server.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>major_version_return</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns the major version supported by the server.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>minor_version_return</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns the minor version supported by the server.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>
|
||||
XeviQueryVersion sets major_version_return and minor_version_return to
|
||||
the major and minor EVI protocol version supported by the server. If
|
||||
the EVI library is compatible with the version returned by the server,
|
||||
it returns nonzero. If dpy does not support the EVI extension, or if
|
||||
there was an error during communication with the server, or if the server
|
||||
and library protocol versions are incompatible, it returns zero. No other
|
||||
Xevi functions may be called before this function. If a client violates
|
||||
this rule, the effects of all subsequent Xevi calls that it makes are
|
||||
undefined.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To get the extended information for any subset of visuals use
|
||||
XeviGetVisualInfo.
|
||||
</para>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>int <function> XeviGetVisualInfo</function></funcdef>
|
||||
<paramdef>Display<parameter> *display</parameter></paramdef>
|
||||
<paramdef>VisualID<parameter> *visual</parameter></paramdef>
|
||||
<paramdef>int<parameter> n_visual</parameter></paramdef>
|
||||
<paramdef>ExtendedVisualInfo<parameter> **evi_return</parameter></paramdef>
|
||||
<paramdef>int<parameter> *n_info_return</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>display</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Specifies the connection to the X server.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>visual</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
If NULL, then information for all visuals of all
|
||||
screens is returned. Otherwise, a pointer to a list of visuals for which
|
||||
extended visual information is desired.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>n_visual</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
If 0, then information for all visuals of all screens is returned. Otherwise,
|
||||
the number of elements in the array <emphasis remap='I'>visual</emphasis>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>evi_return</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns a pointer to a list of <emphasis remap='I'>ExtendedVisualInfo</emphasis>. When done, the client
|
||||
should free the list using <emphasis remap='I'>XFree</emphasis>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>n_info_return</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns the number of elements in the list of
|
||||
<emphasis remap='I'>ExtendedVisualInfo</emphasis>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>
|
||||
XeviGetVisualInfo returns a list of ExtendedVisualInfo structures that describe
|
||||
visual information beyond that supported by the core protocol. This includes
|
||||
layer information relevant for systems supporting overlays and/or underlay
|
||||
planes, and information that allows applications better to determine the level
|
||||
of hardware support for multiple colormaps. XeviGetVisualInfo returns Success
|
||||
if successful, or an X error otherwise.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
</chapter>
|
||||
</book>
|
||||
97
proto/xextproto/specs/geproto.xml
Normal file
97
proto/xextproto/specs/geproto.xml
Normal file
@ -0,0 +1,97 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
||||
<book>
|
||||
<bookinfo>
|
||||
<title>X Generic Event Extension</title>
|
||||
|
||||
<author>
|
||||
<firstname>Peter</firstname>
|
||||
|
||||
<surname>Hutterer</surname>
|
||||
|
||||
<affiliation>
|
||||
<orgname>peter.hutterer@who-t.net</orgname>
|
||||
</affiliation>
|
||||
</author>
|
||||
</bookinfo>
|
||||
|
||||
<chapter>
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>X was designed to provide 64 event opcodes for all extensions. These
|
||||
events are limited to 32 bytes.</para>
|
||||
|
||||
<para>The Generic Event Extension provides a template event for extensions
|
||||
to re-use a single event opcode. GE only provide headers and the most
|
||||
basic functionality, leaving the extensions to interpret the events in
|
||||
their specific context.</para>
|
||||
|
||||
<para>GenericEvents may be longer than 32 bytes. If so, the number of 4
|
||||
byte units following the initial 32 bytes must be specified in the length
|
||||
field of the event.</para>
|
||||
</chapter>
|
||||
|
||||
<chapter>
|
||||
<title>Extension Initialization</title>
|
||||
|
||||
<para>The name of this extension is "Generic Event Extension"</para>
|
||||
|
||||
<programlisting>GEQueryVersion
|
||||
client-major-version: CARD16
|
||||
client-minor-version: CARD16
|
||||
==>
|
||||
major-version: CARD16
|
||||
minor-version: CARD16</programlisting>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>As of version 1.0, no other requests are provided by this extension.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter>
|
||||
<title>Events</title>
|
||||
|
||||
<para>GE defines a single event, to be used by all extensions. The event's
|
||||
structure is similar to a reply. This is a core protocol event, ID 35, and
|
||||
is not itself an extension event.</para>
|
||||
|
||||
<programlisting>GenericEvent
|
||||
type: BYTE always GenericEvent (35)
|
||||
extension: CARD8 extension offset
|
||||
sequenceNumber: CARD16 low 16 bits of request seq. number
|
||||
length: CARD32 length
|
||||
evtype: CARD16 event type</programlisting>
|
||||
|
||||
<para>The field 'extension' is to be set to the major opcode of the
|
||||
extension. The 'evtype' field is the actual opcode of the event. The
|
||||
length field specifies the number of 4-byte blocks after the initial 32
|
||||
bytes. If length is 0, the event is 32 bytes long.</para>
|
||||
</chapter>
|
||||
|
||||
<chapter>
|
||||
<title>Notes</title>
|
||||
|
||||
<para>Although the wire event is of arbitrary length, the actual size of
|
||||
an XEvent is restricted to sizeof(XEvent) [96 bytes, see Xlib.h]. If an
|
||||
extension converts a wire event to an XEvent > 96 bytes, it will
|
||||
overwrite the space allocated for the event. See struct _XSQEvent in
|
||||
Xlibint.h for details.</para>
|
||||
|
||||
<para>Extensions need to malloc additional data and fill the XEvent
|
||||
structure with pointers to the malloc'd data. The client then needs to
|
||||
free the data, only the XEvent structure will be released by Xlib.</para>
|
||||
|
||||
<para>The server must not send GenericEvents longer than 32 bytes until it
|
||||
has verified that the client is able to interpret these events. If a long
|
||||
event is sent to a client unable to process GenericEvents, future
|
||||
interpretation of replies and events by this client will fail.</para>
|
||||
</chapter>
|
||||
</book>
|
||||
1628
proto/xextproto/specs/multibuf.xml
Normal file
1628
proto/xextproto/specs/multibuf.xml
Normal file
File diff suppressed because it is too large
Load Diff
1532
proto/xextproto/specs/security.xml
Normal file
1532
proto/xextproto/specs/security.xml
Normal file
File diff suppressed because it is too large
Load Diff
1236
proto/xextproto/specs/shape.xml
Normal file
1236
proto/xextproto/specs/shape.xml
Normal file
File diff suppressed because it is too large
Load Diff
474
proto/xextproto/specs/shm.xml
Normal file
474
proto/xextproto/specs/shm.xml
Normal file
@ -0,0 +1,474 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
|
||||
|
||||
|
||||
<!-- lifted from troff+ms+XMan by doclifter -->
|
||||
<book id="mit-shm">
|
||||
|
||||
<bookinfo>
|
||||
<title>MIT-SHM(The MIT Shared Memory Extension)</title>
|
||||
<subtitle>How the shared memory extension works</subtitle>
|
||||
<releaseinfo>Version 1.0</releaseinfo>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Jonathan</firstname><surname>Corbet</surname>
|
||||
<affiliation><orgname>Atmospheric Technology Division National Center for Atmospheric Research</orgname></affiliation>
|
||||
<email>corbet@ncar.ucar.edu</email>
|
||||
</author>
|
||||
<othercredit>
|
||||
<contrib>Formatted and edited for release 5 by</contrib>
|
||||
<firstname>Keith</firstname><surname>Packard</surname>
|
||||
<affiliation><orgname>MIT X Consortium</orgname></affiliation>
|
||||
</othercredit>
|
||||
</authorgroup>
|
||||
<corpname>X Consortium Standard</corpname>
|
||||
<copyright><year>1991</year><holder>X Consortium</holder></copyright>
|
||||
<affiliation><orgname>X Consortium</orgname></affiliation>
|
||||
<productnumber>X Version 11, Release 7</productnumber>
|
||||
|
||||
<abstract>
|
||||
<para>
|
||||
This document briefly describes how to use the MIT-SHM shared memory
|
||||
extension. I have tried to make it accurate, but it would not surprise me
|
||||
if some errors remained. If you find anything wrong, do let me know and I
|
||||
will incorporate the corrections. Meanwhile, please take this document "as
|
||||
is" (eman improvement over what was there before, but certainly not the
|
||||
definitive word.)
|
||||
</para>
|
||||
</abstract>
|
||||
|
||||
<legalnotice>
|
||||
<para>
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
</para>
|
||||
<para>
|
||||
The above copyright notice and this permission notice shall be included in
|
||||
all copies or substantial portions of the Software.
|
||||
</para>
|
||||
<para>
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
|
||||
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
||||
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
</para>
|
||||
<para>
|
||||
Except as contained in this notice, the name of the X Consortium shall not be
|
||||
used in advertising or otherwise to promote the sale, use or other dealings
|
||||
in this Software without prior written authorization from the X Consortium.
|
||||
</para>
|
||||
</legalnotice>
|
||||
</bookinfo>
|
||||
|
||||
<chapter>
|
||||
<title>TITLE</title>
|
||||
<sect1 id="REQUIREMENTS">
|
||||
<title>REQUIREMENTS</title>
|
||||
<para>
|
||||
The shared memory extension is provided only by some X servers. To find out
|
||||
if your server supports the extension, use xdpyinfo(1). In particular, to
|
||||
be able to use this extension, your system must provide the SYSV shared
|
||||
memory primitives. There is not an mmap-based version of this extension.
|
||||
To use shared memory on Sun systems, you must have built your kernel with
|
||||
SYSV shared memory enabled -- which is not the default configuration.
|
||||
Additionally, the shared memeory maximum size will need to be increased on
|
||||
both Sun and Digital systems; the defaults are far too small for any useful
|
||||
work.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="WHAT_IS_PROVIDED">
|
||||
<title>WHAT IS PROVIDED</title>
|
||||
|
||||
<para>
|
||||
The basic capability provided is that of shared memory XImages. This is
|
||||
essentially a version of the ximage interface where the actual image data
|
||||
is stored in a shared memory segment, and thus need not be moved through
|
||||
the Xlib interprocess communication channel. For large images, use of this
|
||||
facility can result in some real performance increases.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Additionally, some implementations provided shared memory pixmaps. These
|
||||
are 2 dimensional arrays of pixels in a format specified by the X server,
|
||||
where the image data is stored in the shared memory segment. Through use of
|
||||
shared memory pixmaps, it is possible to change the contents of these
|
||||
pixmaps without using any Xlib routines at all. Shared memory pixmaps can
|
||||
only be supported when the X server can use regular virtual memory for
|
||||
pixmap data; if the pixmaps are stored in some magic graphics hardware, your
|
||||
application will not be able to share them with the server. Xdpyinfo(1)
|
||||
doesn't print this particular nugget of information.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="HOW_TO_USE_THE_SHARED_MEMORY_EXTENSION">
|
||||
<title>HOW TO USE THE SHARED MEMORY EXTENSION</title>
|
||||
<para>
|
||||
Code which uses the shared memory extension must include a number of header
|
||||
files:
|
||||
</para>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
#include <X11/Xlib.h> /* of course */
|
||||
#include <sys/ipc.h>
|
||||
#include <sys/shm.h>
|
||||
#include <X11/extensions/XShm.h>
|
||||
</literallayout>
|
||||
|
||||
<para>
|
||||
Of course, if the system you are building on does not support shared
|
||||
memory, the file XShm.h may not be present. You may want to make
|
||||
liberal use of #ifdefs.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Any code which uses the shared memory extension should first check to see
|
||||
that the server provides the extension. You could always be running over
|
||||
the net, or in some other environment where the extension will not work.
|
||||
To perform this check, call either
|
||||
</para>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>Status <function>XShmQueryExtension</function></funcdef>
|
||||
<paramdef>Display <parameter>*display</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
<para>
|
||||
or
|
||||
</para>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>Status <function>XShmQueryVersion</function></funcdef>
|
||||
<paramdef>Display <parameter>*display</parameter></paramdef>
|
||||
<paramdef>int <parameter>*major</parameter></paramdef>
|
||||
<paramdef>int <parameter>*minor</parameter></paramdef>
|
||||
<paramdef>Bool <parameter>*pixmaps</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
<para>
|
||||
Where "display" is, of course, the display on which you are running. If
|
||||
the shared memory extension may be used, the return value from either
|
||||
function will be True; otherwise your program should operate using
|
||||
conventional Xlib calls. When the extension is available,
|
||||
\fCXShmQueryVersion\fP also returns "major" and "minor" which are the
|
||||
version numbers of the extension implementation, and "pixmaps" which is
|
||||
True iff shared memory pixmaps are supported.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="USE_OF_SHARED_MEMORY_XIMAGES">
|
||||
<title>USE OF SHARED MEMORY XIMAGES</title>
|
||||
<para>
|
||||
The basic sequence of operations for shared memory XImages is as follows:
|
||||
</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Create the shared memory XImage structure
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Create a shared memory segment to store the image data
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Inform the server about the shared memory segment
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Use the shared memory XImage, much like a normal one.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<para>
|
||||
To create a shared memory XImage, use:
|
||||
</para>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>XImage <function>*XShmCreateImage</function></funcdef>
|
||||
<paramdef>Display <parameter>*display</parameter></paramdef>
|
||||
<paramdef>Visual <parameter>*visual</parameter></paramdef>
|
||||
<paramdef>unsigned int <parameter>depth</parameter></paramdef>
|
||||
<paramdef>int <parameter>format</parameter></paramdef>
|
||||
<paramdef>char <parameter>*data</parameter></paramdef>
|
||||
<paramdef>XShmSegmentInfo <parameter>*shminfo</parameter></paramdef>
|
||||
<paramdef>unsigned int <parameter>width</parameter></paramdef>
|
||||
<paramdef>unsigned int <parameter>height</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
<para>
|
||||
Most of the arguments are the same as for XCreateImage; I will not go
|
||||
through them here. Note, however, that there are no "offset", "bitmap_pad",
|
||||
or "bytes_per_line" arguments. These quantities will be defined by the
|
||||
server itself, and your code needs to abide by them. Unless you have already
|
||||
allocated the shared memory segment (see below), you should pass in NULL for
|
||||
the "data" pointer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
There is one additional argument: "shminfo", which is a pointer to a
|
||||
structure of type XShmSegmentInfo. You must allocate one of these
|
||||
structures such that it will have a lifetime at least as long as that of
|
||||
the shared memory XImage. There is no need to initialize this structure
|
||||
before the call to XShmCreateImage.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The return value, if all goes well, will be an XImage structure, which you
|
||||
can use for the subsequent steps.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The next step is to create the shared memory segment. This is
|
||||
best done after the creation of the XImage, since you need to make use of
|
||||
the information in that XImage to know how much memory to allocate. To
|
||||
create the segment, you need a call like:
|
||||
</para>
|
||||
|
||||
|
||||
<literallayout class="monospaced">
|
||||
shminfo.shmid = shmget (IPC_PRIVATE,
|
||||
image->bytes_per_line * image->height, IPC_CREAT|0777);
|
||||
</literallayout>
|
||||
|
||||
<para>
|
||||
(assuming that you have called your shared memory XImage "image"). You
|
||||
should, of course, follow the Rules and do error checking on all of these
|
||||
system calls. Also, be sure to use the bytes_per_line field, not the width
|
||||
you used to create the XImage as they may well be different.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Note that the shared memory ID returned by the system is stored in the
|
||||
shminfo structure. The server will need that ID to attach itself to the
|
||||
segment.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Also note that, on many systems for security reasons, the X server
|
||||
will only accept to attach to the shared memory segment if it's
|
||||
readable and writeable by "other". On systems where the X server is
|
||||
able to determine the uid of the X client over a local transport, the
|
||||
shared memory segment can be readable and writeable only by the uid of
|
||||
the client.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Next, attach this shared memory segment to your process:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
shminfo.shmaddr = image->data = shmat (shminfo.shmid, 0, 0);
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The address returned by shmat should be stored in *both* the XImage
|
||||
structure and the shminfo structure.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To finish filling in the shminfo structure, you need to decide how you want
|
||||
the server to attach to the shared memory segment, and set the "readOnly"
|
||||
field as follows. Normally, you would code:
|
||||
</para>
|
||||
<para>
|
||||
shminfo.readOnly = False;
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you set it to True, the server will not be able to write to this
|
||||
segment, and thus XShmGetImage calls will fail.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Finally, tell the server to attach to your shared memory segment with:
|
||||
</para>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
Status XShmAttach (display, shminfo);
|
||||
</literallayout>
|
||||
|
||||
<para>
|
||||
If all goes well, you will get a non-zero status back, and your XImage is
|
||||
ready for use.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To write a shared memory XImage into an X drawable, use XShmPutImage:
|
||||
</para>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>Status <function>XShmPutImage </function></funcdef>
|
||||
<paramdef>Display <parameter>*display</parameter></paramdef>
|
||||
<paramdef>Drawable <parameter>d</parameter></paramdef>
|
||||
<paramdef>GC <parameter>gc</parameter></paramdef>
|
||||
<paramdef>XImage <parameter>*image</parameter></paramdef>
|
||||
<paramdef>int <parameter>src_x</parameter></paramdef>
|
||||
<paramdef>int <parameter>src_y</parameter></paramdef>
|
||||
<paramdef>int <parameter>dest_x</parameter></paramdef>
|
||||
<paramdef>int <parameter>dest_y</parameter></paramdef>
|
||||
<paramdef>unsigned int <parameter>width</parameter></paramdef>
|
||||
<paramdef>unsigned int <parameter>height</parameter></paramdef>
|
||||
<paramdef>bool <parameter>send_event</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
<para>
|
||||
The interface is identical to that of XPutImage, so I will spare my fingers
|
||||
and not repeat that documentation here. There is one additional parameter,
|
||||
however, called "send_event". If this parameter is passed as True, the
|
||||
server will generate a "completion" event when the image write is complete;
|
||||
thus your program can know when it is safe to begin manipulating the shared
|
||||
memory segment again.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The completion event has type XShmCompletionEvent, which is defined as the
|
||||
following:
|
||||
</para>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
typedef struct {
|
||||
int type; /* of event */
|
||||
unsigned long serial; /* # of last request processed */
|
||||
Bool send_event; /* true if came from a SendEvent request */
|
||||
Display *display; /* Display the event was read from */
|
||||
Drawable drawable; /* drawable of request */
|
||||
int major_code; /* ShmReqCode */
|
||||
int minor_code; /* X_ShmPutImage */
|
||||
ShmSeg shmseg; /* the ShmSeg used in the request */
|
||||
unsigned long offset; /* the offset into ShmSeg used */
|
||||
} XShmCompletionEvent;
|
||||
</literallayout>
|
||||
|
||||
<para>
|
||||
The event type value that will be used can be determined at run time with a
|
||||
line of the form:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
int CompletionType = XShmGetEventBase (display) + ShmCompletion;
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you modify the shared memory segment before the arrival of the
|
||||
completion event, the results you see on the screen may be inconsistent.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To read image data into a shared memory XImage, use the following:
|
||||
</para>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>Status <function>XShmGetImage </function></funcdef>
|
||||
<paramdef>Display <parameter>*display</parameter></paramdef>
|
||||
<paramdef>Drawable <parameter>d</parameter></paramdef>
|
||||
<paramdef>XImage <parameter>*image</parameter></paramdef>
|
||||
<paramdef>int <parameter>x</parameter></paramdef>
|
||||
<paramdef>int <parameter>y</parameter></paramdef>
|
||||
<paramdef>unsigned long <parameter>plane_mask</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
<para>
|
||||
Where "display" is the display of interest, "d" is the source drawable,
|
||||
"image" is the destination XImage, "x" and "y" are the offsets within
|
||||
"d", and "plane_mask" defines which planes are to be read.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To destroy a shared memory XImage, you should first instruct the server to
|
||||
detach from it, then destroy the segment itself, as follows:
|
||||
</para>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
XShmDetach (display, shminfo);
|
||||
XDestroyImage (image);
|
||||
shmdt (shminfo.shmaddr);
|
||||
shmctl (shminfo.shmid, IPC_RMID, 0);
|
||||
</literallayout>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="USE_OF_SHARED_MEMORY_PIXMAPS">
|
||||
<title>USE OF SHARED MEMORY PIXMAPS</title>
|
||||
<para>
|
||||
Unlike X images, for which any image format is usable, the shared memory
|
||||
extension supports only a single format (i.e. XYPixmap or ZPixmap) for the
|
||||
data stored in a shared memory pixmap. This format is independent of the
|
||||
depth of the image (for 1-bit pixmaps it doesn't really matter what this
|
||||
format is) and independent of the screen. Use XShmPixmapFormat to get the
|
||||
format for the server:
|
||||
</para>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>int <function>XShmPixmapFormat</function></funcdef>
|
||||
<paramdef>Display <parameter>*display</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
<para>
|
||||
If your application can deal with the server pixmap data format (including
|
||||
bits-per-pixel et al.), create a shared memory segment and "shminfo"
|
||||
structure in exactly the same way as is listed above for shared memory
|
||||
XImages. While it is, not strictly necessary to create an XImage first,
|
||||
doing so incurs little overhead and will give you an appropriate
|
||||
bytes_per_line value to use.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Once you have your shminfo structure filled in, simply call:
|
||||
</para>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>Pixmap <function>XShmCreatePixmap</function></funcdef>
|
||||
<paramdef>Display <parameter>*display</parameter></paramdef>
|
||||
<paramdef>Drawable <parameter>d</parameter></paramdef>
|
||||
<paramdef>char <parameter>*data</parameter></paramdef>
|
||||
<paramdef>XShmSegmentInfo <parameter>*shminfo</parameter></paramdef>
|
||||
<paramdef>unsigned int <parameter>width</parameter></paramdef>
|
||||
<paramdef>unsigned int <parameter>height</parameter></paramdef>
|
||||
<paramdef>unsigned int <parameter>depth</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
<para>
|
||||
The arguments are all the same as for XCreatePixmap, with two additions:
|
||||
"data" and "shminfo". The second of the two is the same old shminfo
|
||||
structure that has been used before. The first is the pointer to the shared
|
||||
memory segment, and should be the same as the shminfo.shmaddr field. I am
|
||||
not sure why this is a separate parameter.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If everything works, you will get back a pixmap, which you can manipulate in
|
||||
all of the usual ways, with the added bonus of being able to tweak its
|
||||
contents directly through the shared memory segment. Shared memory pixmaps
|
||||
are destroyed in the usual manner with XFreePixmap, though you should detach
|
||||
and destroy the shared memory segment itself as shown above.
|
||||
</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
</book>
|
||||
1062
proto/xextproto/specs/sync.xml
Normal file
1062
proto/xextproto/specs/sync.xml
Normal file
File diff suppressed because it is too large
Load Diff
562
proto/xextproto/specs/tog-cup.xml
Normal file
562
proto/xextproto/specs/tog-cup.xml
Normal file
@ -0,0 +1,562 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
|
||||
|
||||
|
||||
<book id="tog-cup">
|
||||
|
||||
<bookinfo>
|
||||
<title>Colormap Utilization Policy and Extension</title>
|
||||
<subtitle>X Project Team Standard</subtitle>
|
||||
<releaseinfo>Version 1.0</releaseinfo>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Kaleb</firstname>
|
||||
<othername>S.</othername>
|
||||
<surname>Keithley</surname>
|
||||
<affiliation><orgname>The Open Group</orgname></affiliation>
|
||||
</author>
|
||||
</authorgroup>
|
||||
<corpname>X Consortium Standard</corpname>
|
||||
<copyright><year>1986-1997</year><holder>The Open Group</holder></copyright>
|
||||
<affiliation><orgname>X Consortium</orgname></affiliation>
|
||||
<productnumber>X Version 11, Release 6.8</productnumber>
|
||||
|
||||
<legalnotice>
|
||||
|
||||
<para>
|
||||
Permission is hereby granted, free of charge, to any person obtaining a
|
||||
copy of this
|
||||
software and associated documentation files (the Software), to use the
|
||||
Software
|
||||
without restriction, including, without limitation, the rights to copy,
|
||||
modify, merge,
|
||||
publish, distribute and sublicense the Software, to make, have made,
|
||||
license and
|
||||
distribute derivative works thereof, and to permit persons to whom the
|
||||
Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
</para>
|
||||
<para>
|
||||
The above copyright notice and the following permission notice shall be
|
||||
included in all copies of the Software:
|
||||
</para>
|
||||
<para>
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE WARRANTIES
|
||||
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-
|
||||
INFRINGEMENT. IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY
|
||||
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
|
||||
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF, OR IN
|
||||
CONNNECTION WITH THE SOFTWARE OR THE USE OF OTHER DEALINGS IN
|
||||
THE SOFTWARE.
|
||||
</para>
|
||||
<para>
|
||||
Except as contained in this notice, the name of The Open Group shall not be
|
||||
used in
|
||||
advertising or otherwise to promote the use or other dealings in this
|
||||
Software without prior written authorization from The Open Group.
|
||||
</para>
|
||||
<para>
|
||||
X Window System is a trademark of The Open Group.
|
||||
</para>
|
||||
|
||||
</legalnotice>
|
||||
</bookinfo>
|
||||
|
||||
<chapter>
|
||||
<title>TITLE</title>
|
||||
<sect1 id="Overview">
|
||||
<title>Overview</title>
|
||||
<para>
|
||||
This extension has three purposes: a) to provide mechanism for a special
|
||||
application (a colormap manager) to discover any special colormap
|
||||
requirements, e.g. the colormap entries that are nominally reserved for
|
||||
desktop colors in the MS-Windows environment and initialize the default
|
||||
colormap so that it can be more easily shared; and b) to encourage colormap
|
||||
sharing and reduce colormap flashing on low-end 8-bit frame buffers by
|
||||
providing a policy for sharing; and c) when colormaps aren't shared,
|
||||
define a behavior in the X server color allocation scheme to reduce
|
||||
colormap flashing.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To encourage colormap sharing and accomodate special colormap requirements
|
||||
two new protocols are defined: the first provides a way to query the
|
||||
server for a list of reserved colormap entries, and the second is a way
|
||||
to initialize read-only (shareable) colormap entries at specific locations
|
||||
in a colormap.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To minimize colormap flashing when the root window's default visual is one
|
||||
of GrayScale, PseudoColor, or DirectColor, and a private colormap for the
|
||||
default visual is being used, a minor (but compatible) change to the
|
||||
server implementation of the AllocColor and AllocNamedColor requests is
|
||||
required. Where the core protocol says nothing about the pixel values
|
||||
returned, when this extension is in effect, the AllocColor and AllocNamedColor
|
||||
requests will first look for a matching color in the default colormap, and,
|
||||
if a match is found and the same cell in the private colormap has not
|
||||
already been allocated, the color will be allocated in the private colormap
|
||||
at the same locaton as in the default colormap (instead of in the first
|
||||
available location.)
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Requests">
|
||||
<title>Requests</title>
|
||||
<para>
|
||||
<function>QueryVersion</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
client_major_version: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
client_minor_version: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
=>
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
server_major_version: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
server_minor_version: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
If supplied, the client_major_version and client_minor_version indicate
|
||||
what version of the protocol the client wants the server to implement.
|
||||
The server version numbers returned indicate the protocol this extension
|
||||
actually supports. This might not equal the version sent by the client.
|
||||
An implementation can (but need not) support more than one version
|
||||
simultaneously. The server_major_version and the server_minor_version
|
||||
are a mechanism to support future revisions of the TOG-CUP protocol that
|
||||
may be necessary. In general, the major version would increment for
|
||||
incompatible changes, and the minor version would increment for small
|
||||
upward-compatible changes. Servers that support the protocol defined in
|
||||
this document will return a server_major_version of one (1), and a
|
||||
server_minor_version of zero (0).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>GetReservedColormapEntries</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
screen: CARD32
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
=>
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
entries: LISTofCOLORITEM
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
This request returns a list of colormap entries (pixels) that are reserved
|
||||
by the system, e.g. MS-Windows reserved desktop colors. This list will, at a
|
||||
minimum, contain entries for the BlackPixel and WhitePixel of the specified
|
||||
screen. The do-red, do-green, and do-blue elements of the COLORITEMs are
|
||||
unused in this reply.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Rationale: There are colormap entries (pixels) that, e.g., MS-Windows
|
||||
desktop reserves as desktop colors, that should not be altered. If they
|
||||
are altered then X programs will cause colormap flashing between X and
|
||||
MS-Windows applications running/displaying on the same desktop.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>StoreColors</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
cmap: COLORMAP
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
items: LISTofCOLORITEM
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
=>
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
items: LISTofCOLORITEM
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
This request changes the colormap entries of the specified pixels. The
|
||||
colormap entries are allocated as if by an AllocColor request. The do-red,
|
||||
do-green, and do-blue elements of the COLORITEMs are unused in this request.
|
||||
A boolean alloc-ok element (a bit) is returned indicating whether the
|
||||
particular pixel was successfully allocated or not. If successfully
|
||||
allocated the RGB and pixel are returned.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A Value error is generated if a pixel is not a valid index into cmap. A
|
||||
BadMatch error is generated if if cmap does not belong to a GrayScale,
|
||||
PseudoColor, or DirectColor visual.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Events_and_Errors">
|
||||
<title>Events and Errors</title>
|
||||
<para>
|
||||
No new events or errors are defined by this extension.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
<sect1 id="Changes_to_existing_protocol_">
|
||||
<title>Changes to existing protocol.</title>
|
||||
<para>
|
||||
None.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Encoding">
|
||||
<title>Encoding</title>
|
||||
<para>
|
||||
The name of this extension is "TOG-CUP".
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The conventions used here are the same as those for the core X11
|
||||
Protocol Encoding.
|
||||
</para>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>QueryVersion</function>
|
||||
1 CARD8 opcode
|
||||
1 0 TOG-CUP opcode
|
||||
2 2 request length
|
||||
2 CARD16 client_major_version
|
||||
2 CARD16 client_minor_version
|
||||
=>
|
||||
1 1 reply
|
||||
1 unused
|
||||
2 CARD16 sequence number
|
||||
4 0 length
|
||||
2 CARD16 server_major_version
|
||||
2 CARD16 server_minor_number
|
||||
20 unused
|
||||
</literallayout>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>GetReservedColormapEntries</function>
|
||||
1 CARD8 opcode
|
||||
1 1 TOG-CUP opcode
|
||||
2 2 request length
|
||||
4 CARD32 screen
|
||||
=>
|
||||
1 1 reply
|
||||
1 unused
|
||||
2 CARD16 sequence number
|
||||
4 3n length
|
||||
24 unused
|
||||
12n LISTofCOLORITEM items
|
||||
</literallayout>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>StoreColors</function>
|
||||
1 CARD8 opcode
|
||||
1 2 TOG-CUP opcode
|
||||
2 2+3n request length
|
||||
4 COLORMAP cmap
|
||||
12n LISTofCOLORITEM items
|
||||
=>
|
||||
1 1 reply
|
||||
1 unused
|
||||
2 CARD16 sequence number
|
||||
4 3n length
|
||||
24 unused
|
||||
12n LISTofCOLORITEM items
|
||||
</literallayout>
|
||||
|
||||
<para>
|
||||
(The definition of COLORITEM here is only for the purpose of defining the
|
||||
additional alloc-ok member in the CUPStoreColors reply.)
|
||||
</para>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
COLORITEM
|
||||
4 CARD32 pixel
|
||||
2 CARD16 red
|
||||
2 CARD16 green
|
||||
2 CARD16 blue
|
||||
1 alloc-ok
|
||||
#x07 unused
|
||||
#x08 alloc-ok (1 is True, 0 is False)
|
||||
#xF0 unused
|
||||
1 unused
|
||||
</literallayout>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="C_Language_Binding">
|
||||
<title>C Language Binding</title>
|
||||
|
||||
<para>
|
||||
The C functions provide direct access to the protocol and add no additional
|
||||
semantics. For complete details on the effects of these functions, refer
|
||||
to the appropriate protocol request, which can be derived by deleting XCup
|
||||
at the start of the function. All functions that have return type Status
|
||||
will return nonzero for success and zero for failure.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The include file for this extension is
|
||||
<function><X11/extensions/Xcup.h></function>.
|
||||
</para>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>Status <function> XCupQueryVersion</function></funcdef>
|
||||
<paramdef>Display*<parameter> display</parameter></paramdef>
|
||||
<paramdef>int*<parameter> major_version_return</parameter></paramdef>
|
||||
<paramdef>int*<parameter> minor_version_return</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>display</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Specifies the connection to the X server.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>major_version_return</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns the major version supported by the server.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>minor_version_return</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns the minor version supported by the server.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
|
||||
<para>
|
||||
XCupQueryVersions sets major_version_return and minor_version_return to
|
||||
the major and minor TOG-CUP protocol version supported by the server. If
|
||||
the TOG-CUP library is compatible with the version returned by the server,
|
||||
it returns nonzero. If dpy does not support the TOG-CUP extension, or if
|
||||
there was an error during communication with the server, or if the server
|
||||
and library protocol versions are incompatible, it returns zero. No other
|
||||
XCup functions may be called before this function. If a client violates
|
||||
this rule, the effects of all subsequent XCup calls that it makes are
|
||||
undefined.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To get the list of reserved colormap entries, use
|
||||
XCupGetReservedColormapEntries.
|
||||
</para>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>Status <function> XCupGetReservedColormapEntries</function></funcdef>
|
||||
<paramdef>Display*<parameter> display</parameter></paramdef>
|
||||
<paramdef>int<parameter> screen</parameter></paramdef>
|
||||
<paramdef>XColor**<parameter> colors_out</parameter></paramdef>
|
||||
<paramdef>int*<parameter> ncolors</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>display</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Specifies the connection to the X server.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>colors_out</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns the values reserved by the server.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>ncolors</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Returns the number of items in colors_out.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>
|
||||
The XCupGetReservedColormapEntries function gets system specific colormap
|
||||
entries. E.g. the MS-Windows desktop uses N colormap entries at the beginning
|
||||
(0..N) and end (256-N..255) of the colormap. Use XFree to free colors_out.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To allocate one or more read-only color cells with RGB values, use
|
||||
XCupStoreColors.
|
||||
</para>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>Status <function> XCupStoreColors</function></funcdef>
|
||||
<paramdef>Display*<parameter> display</parameter></paramdef>
|
||||
<paramdef>Colormap<parameter> colormap</parameter></paramdef>
|
||||
<paramdef>XColor*<parameter> colors_in_out</parameter></paramdef>
|
||||
<paramdef>int<parameter> ncolors</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>display</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Specifies the connection to the X server.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>colormap</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Specifies the colormap.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>colors_in_out</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Specifies and returns the values actually used in the colormap.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>ncolors</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Specifies the number of items in colors_in_out.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>
|
||||
The XCupStoreColors function changes the colormap entries of the pixel
|
||||
values specified in the pixel members of the XColor structures. The colormap
|
||||
entries are allocated as if an AllocColor had been used instead, i.e. the
|
||||
colors are read-only (shareable). XCupStoreColors returns the number of
|
||||
colors that were successfully allocated in the colormap.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Using_the_TOG_CUP_extension_and_Colormap_Utilization_Policy">
|
||||
<title>Using the TOG-CUP extension and Colormap Utilization Policy</title>
|
||||
<para>
|
||||
The X server preallocates any hardware or desktop special colors in the
|
||||
default colormap; e.g. UNIX X servers preallocate Black and White pixels.
|
||||
PC X servers should also preallocate the MS-Windows desktop colors. (Note
|
||||
to implementors: in the Sample Implementation special colors are allocated
|
||||
in the default colormap in cfbCreateDefColormap for dumb memory framebuffers.)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To minimize colormap flash an application which installs its own private
|
||||
colormap should query the special colors by calling
|
||||
XCupGetReservedColormapEntries, and can then store those entries (in the
|
||||
proper location) in its private colormap using XCupStoreColors.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Applications which allocate many colors in a screen's default colormap, e.g.
|
||||
a color-cube or a gray-ramp, should allocate them with XCupStoreColors. By
|
||||
using XCupStoreColors the colors will be allocated sharable (read-only) and
|
||||
any other application which allocates the same color will share that color
|
||||
cell.
|
||||
</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
</book>
|
||||
722
proto/xextproto/specs/xtest.xml
Normal file
722
proto/xextproto/specs/xtest.xml
Normal file
@ -0,0 +1,722 @@
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
|
||||
|
||||
<book id="xtest">
|
||||
|
||||
<bookinfo>
|
||||
<title>XTEST Extension Protocol</title>
|
||||
<subtitle>X Consortium Standard</subtitle>
|
||||
<releaseinfo>Version 2.2</releaseinfo>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Kieron</firstname><surname>Drake</surname>
|
||||
<affiliation><orgname>UniSoft Ltd.</orgname></affiliation>
|
||||
</author>
|
||||
</authorgroup>
|
||||
<copyright><year>1992</year><holder>UniSoft Group Ltd.</holder></copyright>
|
||||
<copyright><year>1992,1994</year><holder>X Consortium</holder></copyright>
|
||||
|
||||
<legalnotice>
|
||||
<para>
|
||||
Permission to use, copy, modify, and distribute this documentation for any
|
||||
purpose and without fee is hereby granted, provided that the above copyright
|
||||
notice and this permission notice appear in all copies. UniSoft makes no
|
||||
representations about the suitability for any purpose of the information in
|
||||
this document. This documentation is provided "as is" without express or
|
||||
implied warranty.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The above copyright notice and this permission notice shall be included in
|
||||
all copies or substantial portions of the Software.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
|
||||
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
||||
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Except as contained in this notice, the name of the X Consortium shall not be
|
||||
used in advertising or otherwise to promote the sale, use or other dealings
|
||||
in this Software without prior written authorization from the X Consortium.
|
||||
</para>
|
||||
</legalnotice>
|
||||
</bookinfo>
|
||||
|
||||
|
||||
<chapter>
|
||||
<title>TITLE</title>
|
||||
|
||||
<sect1 id="Overview">
|
||||
<title>Overview</title>
|
||||
<para>
|
||||
This extension is a minimal set of client and server extensions
|
||||
required to completely test the X11 server with no user intervention.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This extension is not intended to support general journaling and
|
||||
playback of user actions. This is a difficult area [XTrap, 89] as it attempts
|
||||
to synchronize synthetic user interactions with their effects; it is at the
|
||||
higher level of dialogue recording/playback rather than at the strictly lexical
|
||||
level. We are interested only in the latter, simpler, case. A more detailed
|
||||
discussion and justification of the extension functionality is given in
|
||||
[Drake, 91].
|
||||
</para>
|
||||
|
||||
<para>
|
||||
We are aiming only to provide a minimum set of facilities that
|
||||
solve immediate testing and validation problems. The testing extension
|
||||
itself needs testing, where possible, and so should be as simple as possible.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
We have also tried to:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Confine the extension to an appropriate high level within the server
|
||||
to minimize portability problems. In practice this means that the extension
|
||||
should be at the DIX level or use the DIX/DDX interface, or both. This
|
||||
has effects, in particular, on the level at which "input synthesis"
|
||||
can occur.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Minimize the changes required in the rest of the server.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Minimize performance penalties on normal server operation.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Description">
|
||||
<title>Description</title>
|
||||
<para>
|
||||
The functions provided by this extension fall into two groups:
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>Client Operations</term>
|
||||
<listitem>
|
||||
<para>
|
||||
These routines manipulate otherwise hidden client-side behavior. The
|
||||
actual implementation will depend on the details of the actual language
|
||||
binding and what degree of request buffering, GContext caching, and so on, is
|
||||
provided.
|
||||
In the C binding, defined in "XTEST Extension Library", routines are
|
||||
provided to access the internals of two opaque data structures
|
||||
-- <function>GC</function>s
|
||||
and
|
||||
<function>Visual</function>s --
|
||||
and to discard any requests pending within the
|
||||
output buffer of a connection. The exact details can be expected to differ for
|
||||
other language bindings.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>Server Requests</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The first of these requests is similar to that provided in most
|
||||
extensions: it allows a client to specify a major and minor version
|
||||
number to the server and for the server to respond with major and minor
|
||||
versions of its own. The remaining two requests allow the following:
|
||||
<!-- .RS -->
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Access to an otherwise "write-only" server resource: the cursor
|
||||
associated with a given window
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Perhaps most importantly, limited synthesis of input device events,
|
||||
almost as if a cooperative user had moved the pointing device
|
||||
or pressed a key or button.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Types">
|
||||
<title>Types</title>
|
||||
<para>
|
||||
The following types are used in the request and event definitions in
|
||||
subsequent sections:
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='2' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<colspec colname='c2' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry namest="c1" nameend="c2">
|
||||
FAKE_EVENT_TYPE
|
||||
{ <function>KeyPress</function>,
|
||||
<function>KeyRelease</function>,
|
||||
<function>MotionNotify</function>,
|
||||
<function>ButtonPress</function>,
|
||||
<function>ButtonRelease</function> }
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>FAKE_EVENT</entry>
|
||||
<entry>[type: FAKE_EVENT_TYPE,</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry></entry>
|
||||
<entry>detail: BYTE,</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry></entry>
|
||||
<entry>time: TIME,</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry></entry>
|
||||
<entry>root: WINDOW,</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry></entry>
|
||||
<entry>rootX, rootY: INT16]</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
CURSOR { <function>CurrentCursor</function>, <function> None</function> }
|
||||
or a cursor as defined by the X11 Protocol.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Client_Operations">
|
||||
<title>Client Operations</title>
|
||||
|
||||
<para>
|
||||
These are abstract definitions of functionality. They refer to client-side
|
||||
objects such as "GC" and "VISUAL" that are quoted to
|
||||
denote their abstract nature. Concrete versions of these functions are
|
||||
defined only for particular language bindings. In some circumstances
|
||||
a particular language binding may not implement the relevant abstract
|
||||
type or may provide it as a transparent, rather than opaque, type, with
|
||||
the result that the corresponding function does not make sense or is
|
||||
not required, respectively.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>XTestSetGContextOfGC</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>gc</emphasis>: "GC"
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>gid</emphasis>: GCONTEXT
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
Sets the GCONTEXT within the "GC" gc to have
|
||||
the value specified by gid.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>XTestSetVisualIDOfVisual</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>visual</emphasis>: "VISUAL"
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>visualid</emphasis>: VISUALID
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
Sets the VISUALID within the "VISUAL" visual to have
|
||||
the value specified by visualid.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>XTestDiscard</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>dpy</emphasis>: "CONNECTION"
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
=>
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
status: BOOL
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
Discards any requests that are present in the request buffer associated with
|
||||
the "CONNECTION" dpy.
|
||||
The status returned is
|
||||
<function>True</function>
|
||||
if there were one or more requests
|
||||
in the buffer and
|
||||
<function>False</function>
|
||||
otherwise.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Server_Requests">
|
||||
<title>Server Requests</title>
|
||||
<para>
|
||||
<function>XTestGetVersion</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>clientMajorVersion</emphasis>: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>clientMinorVersion</emphasis>: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
=>
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
serverMajorVersion: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
serverMinorVersion: CARD16
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
Errors: <function>Length</function>
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
|
||||
<para>
|
||||
This request can be used to ensure that the server version of the XTEST
|
||||
extension is usable by the client. This document defines major version two
|
||||
(2), minor version one (1).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>XTestCompareCursor</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>window</emphasis>: WINDOW
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>cursor-id</emphasis>: CURSOR or
|
||||
<function>CurrentCursor</function>
|
||||
or
|
||||
<function>None</function>
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
=>
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
same: BOOL
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
Errors:
|
||||
<function>Window</function>,
|
||||
<function>Length</function>,
|
||||
<function>Cursor</function>
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
This request looks up the cursor associated with the window and
|
||||
compares it with either the null cursor if cursor-id is
|
||||
<function>None ,</function>
|
||||
or the current cursor (that is, the one being displayed),
|
||||
or the cursor whose ID is cursor-id, and returns
|
||||
the result of the comparison in same.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>XTestFakeInput</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>events</emphasis>: LISTofFAKE_EVENT
|
||||
</entry>
|
||||
</row>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
Errors:
|
||||
<function>Window</function>,
|
||||
<function>Length</function>,
|
||||
<function>Alloc</function>,
|
||||
<function>Value</function>
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
This request simulates the limited set of core protocol
|
||||
events within the set FAKE_EVENT_TYPE. Only the following event fields,
|
||||
defined in FAKE_EVENT, are interpreted:
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>type</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This must be one of
|
||||
<function>KeyPress</function>,
|
||||
<function>KeyRelease</function>,
|
||||
<function>MotionNotify</function>,
|
||||
<function>ButtonPress</function>,
|
||||
or
|
||||
<function>ButtonRelease</function>,
|
||||
or else a
|
||||
<function>Value</function>
|
||||
error occurs.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>detail</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
For key events, this field is interpreted as the physical keycode.
|
||||
If the keycode is less than min-keycode or greater than max-keycode,
|
||||
as returned in the connection setup, then a
|
||||
<function>Value</function>
|
||||
error occurs.
|
||||
For button events, this field is interpreted as the physical (or core) button,
|
||||
meaning it will be mapped to the corresponding logical button according to
|
||||
the most recent
|
||||
<function>SetPointerMapping</function>
|
||||
request.
|
||||
If the button number is less than one or greater than the number of physical
|
||||
buttons, then a
|
||||
<function>Value</function>
|
||||
error occurs.
|
||||
For motion events, if this field is
|
||||
<function>True ,</function>
|
||||
then rootX and rootY
|
||||
are relative distances from the current pointer location; if this field is
|
||||
<function>False,</function>
|
||||
then they are absolute positions.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>time</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This is either
|
||||
<function>CurrentTime</function>
|
||||
(meaning no delay)
|
||||
or the delay in milliseconds that the server should wait before
|
||||
simulating this event. No other requests from this client will be
|
||||
processed until this delay, if any, has expired and subsequent processing
|
||||
of the simulated event has been completed.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>root</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
In the case of motion events this field is the ID of the root window on
|
||||
which the new motion is to take place. If
|
||||
<function>None</function>
|
||||
is specified, the root window of the screen the pointer is currently on
|
||||
is used instead.
|
||||
If this field is not a valid window, then a
|
||||
<function>Window</function>
|
||||
error occurs.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<emphasis remap='I'>rootX</emphasis> &
|
||||
<emphasis remap='I'>rootY</emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
In the case of motion events these fields indicate relative distance or
|
||||
absolute pointer coordinates, according to the setting of detail.
|
||||
If the specified coordinates are off-screen, the closest on-screen
|
||||
coordinates will be substituted.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>
|
||||
When the simulated event(s) are processed, they cause event propagation,
|
||||
passive grab activation, and so on, just as if the corresponding input device
|
||||
action had occurred. However, motion events might not be recorded in the
|
||||
motion history buffer.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For the currently supported event types, the event list must have length one,
|
||||
otherwise a
|
||||
<function>BadLength</function>
|
||||
error occurs.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>XTestGrabControl</function>
|
||||
</para>
|
||||
|
||||
<informaltable frame="none">
|
||||
<tgroup cols='1' align='left'>
|
||||
<colspec colname='c1' colsep="0" colwidth="1*"/>
|
||||
<tbody>
|
||||
<row rowsep="0">
|
||||
<entry>
|
||||
<emphasis remap='I'>impervious</emphasis>: BOOL
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
If impervious is
|
||||
<function>True</function>,
|
||||
then the executing client becomes impervious to server grabs;
|
||||
that is, it can continue executing requests even if another client
|
||||
grabs the server.
|
||||
If impervious is
|
||||
<function>False</function>,
|
||||
then the executing client returns to the normal state of being
|
||||
susceptible to server grabs.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Encoding">
|
||||
<title>Encoding</title>
|
||||
<para>
|
||||
Please refer to the X11 Protocol Encoding document as this document uses
|
||||
conventions established there.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The name of this extension is "XTEST".
|
||||
</para>
|
||||
|
||||
<sect2 id="New_Types">
|
||||
<title>New Types</title>
|
||||
<literallayout class="monospaced">
|
||||
FAKE_EVENT_TYPE
|
||||
2 KeyPress
|
||||
3 KeyRelease
|
||||
4 ButtonPress
|
||||
5 ButtonRelease
|
||||
6 MotionNotify
|
||||
</literallayout>
|
||||
|
||||
<para>
|
||||
NOTE that the above values are defined to be the same as those for
|
||||
the corresponding core protocol event types.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="Requests">
|
||||
<title>Requests</title>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>XTestGetVersion</function>
|
||||
1 CARD8 opcode
|
||||
1 0 xtest opcode
|
||||
2 2 request length
|
||||
1 CARD8 client major version
|
||||
1 unused
|
||||
2 CARD16 client minor version
|
||||
=>
|
||||
1 1 Reply
|
||||
1 CARD8 server major version
|
||||
2 CARD16 sequence number
|
||||
4 0 reply length
|
||||
2 CARD16 server minor version
|
||||
22 unused
|
||||
</literallayout>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>XTestCompareCursor</function>
|
||||
1 CARD8 opcode
|
||||
1 1 xtest opcode
|
||||
2 3 request length
|
||||
4 WINDOW window
|
||||
4 CURSOR cursor-id
|
||||
0 None
|
||||
1 CurrentCursor
|
||||
=>
|
||||
1 1 Reply
|
||||
1 BOOL cursors are the same
|
||||
2 CARD16 sequence number
|
||||
4 0 reply length
|
||||
24 unused
|
||||
</literallayout>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>XTestFakeInput</function>
|
||||
1 CARD8 opcode
|
||||
1 2 xtest opcode
|
||||
2 1+(1*8) request length
|
||||
1 FAKE_EVENT_TYPE fake device event type
|
||||
1 BYTE detail: button or keycode
|
||||
2 unused
|
||||
4 TIME delay (milliseconds)
|
||||
0 CurrentTime
|
||||
4 WINDOW root window for MotionNotify
|
||||
0 None
|
||||
8 unused
|
||||
2 INT16 x position for MotionNotify
|
||||
2 INT16 y position for MotionNotify
|
||||
8 unused
|
||||
</literallayout>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
<function>XTestGrabControl</function>
|
||||
1 CARD8 opcode
|
||||
1 3 xtest opcode
|
||||
2 2 request length
|
||||
1 BOOL impervious
|
||||
3 unused
|
||||
</literallayout>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="References">
|
||||
<title>References</title>
|
||||
<para>
|
||||
Annicchiarico, D., et al.,
|
||||
<emphasis remap='I'>XTrap: The XTrap Architecture</emphasis>.
|
||||
Digital Equipment Corporation, July 1991.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Drake, K. J.,
|
||||
<emphasis remap='I'>Some Proposals for a
|
||||
Minimum X11 Testing Extension</emphasis>.
|
||||
UniSoft Ltd., June 1991.
|
||||
</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
</book>
|
||||
Loading…
Reference in New Issue
Block a user