frederik
/
xserver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Convert LinuxDoc documents to DocBook/XML 

Only the markup/formatting is changed - the contents should still
be wildly out of date for now.

Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>
Reviewed-by: Rémi Cardona <remi@gentoo.org>
Tested-by: Gaetan Nadon <memsize@videotron.ca>
This commit is contained in:
Alan Coopersmith 2010-05-14 14:56:09 -07:00
parent ebd745ced8
commit fc6ebe1e1d
8 changed files with 11353 additions and 8697 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
configure.ac
View File

@ -716,10 +716,9 @@ fi
dnl Handle building documentation dnl Handle building documentation
AM_CONDITIONAL(BUILDDOCS, test "x$BUILDDOCS" = xyes) AM_CONDITIONAL(BUILDDOCS, test "x$BUILDDOCS" = xyes)
XORG_ENABLE_DEVEL_DOCS
dnl Only build sgml docs when linuxdoc is available and XORG_WITH_XMLTO(0.0.20)
dnl def.ents has been installed XORG_WITH_FOP
XORG_CHECK_LINUXDOC
dnl Handle installing libxf86config dnl Handle installing libxf86config
AM_CONDITIONAL(INSTALL_LIBXF86CONFIG, [test "x$INSTALL_LIBXF86CONFIG" = xyes]) AM_CONDITIONAL(INSTALL_LIBXF86CONFIG, [test "x$INSTALL_LIBXF86CONFIG" = xyes])

59
doc/xml/xmlrules.in Normal file
View File

@ -0,0 +1,59 @@
#
# 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.
#
# This file is included by Makefile.am in subdirectories that have
# DocBook XML documentation files.
#
# No files are automatically distributed or installed by this subset of rules
# Any files to be distributed or installed would be listed in the including
# Makefile.am
TXT_FILES = $(XML_FILES:%.xml=%.txt)
HTML_FILES = $(XML_FILES:%.xml=%.html)
PDF_FILES = $(XML_FILES:%.xml=%.pdf)
BUILT_DOC_FILES =
SUFFIXES = .xml .txt .html .pdf
if HAVE_XMLTO
BUILT_DOC_FILES += $(TXT_FILES)
.xml.txt:
@rm -f $@
$(AM_V_GEN)$(XMLTO) txt $<
BUILT_DOC_FILES += $(HTML_FILES)
.xml.html:
@rm -f $@
$(AM_V_GEN)$(XMLTO) xhtml-nochunks $<
if HAVE_FOP
BUILT_DOC_FILES += $(PDF_FILES)
.xml.pdf:
@rm -f $@
$(AM_V_GEN)$(XMLTO) --with-fop pdf $<
endif
endif
CLEAN_DOC_FILES = $(TXT_FILES) $(HTML_FILES) $(PDF_FILES)

37
hw/dmx/doc/Makefile.am
View File

@ -19,37 +19,14 @@
# NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN # NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. # CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
SGML_FILES = dmx.sgml scaled.sgml XML_FILES = dmx.xml scaled.xml
if BUILD_LINUXDOC include ../../../doc/xml/xmlrules.in
TXT_FILES = $(SGML_FILES:%.sgml=%.txt)
PS_FILES = $(SGML_FILES:%.sgml=%.ps) if ENABLE_DEVEL_DOCS
if BUILD_PDFDOC noinst_DATA = $(BUILT_DOC_FILES)
PDF_FILES = $(SGML_FILES:%.sgml=%.pdf)
endif
HTML_FILES = $(SGML_FILES:%.sgml=%.html)
SUFFIXES = .sgml .txt .html .ps .pdf
.sgml.txt:
@rm -f $@
$(AM_V_GEN)$(MAKE_TEXT) $<
.sgml.ps:
@rm -f $@
$(AM_V_GEN)$(MAKE_PS) $<
.ps.pdf:
@rm -f $@
$(AM_V_GEN)$(MAKE_PDF) $<
.sgml.html:
@rm -f $@
$(AM_V_GEN)$(MAKE_HTML) $<
noinst_DATA = $(TXT_FILES) $(PS_FILES) $(PDF_FILES) $(HTML_FILES)
CLEANFILES = $(TXT_FILES) $(PS_FILES) $(PDF_FILES) $(HTML_FILES)
endif endif
CLEANFILES = $(CLEAN_DOC_FILES)
if HAVE_DOXYGEN if HAVE_DOXYGEN
@ -67,7 +44,7 @@ maintainer-clean-local:
endif endif
EXTRA_DIST = \ EXTRA_DIST = \
$(SGML_FILES) \ $(XML_FILES) \
DMXSpec.txt \ DMXSpec.txt \
DMXSpec-v1.txt \ DMXSpec-v1.txt \
dmx.txt \ dmx.txt \

1808
hw/dmx/doc/dmx.sgml → hw/dmx/doc/dmx.xml
View File

File diff suppressed because it is too large Load Diff

564
hw/dmx/doc/scaled.sgml → hw/dmx/doc/scaled.xml
View File

@ -1,27 +1,34 @@
<!DOCTYPE linuxdoc PUBLIC "-//XFree86//DTD linuxdoc//EN"> <?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
]>
<article> <article>
<articleinfo>
<!-- Title information --> <!-- Title information -->
<title>Scaled Window Support in DMX</title> <title>Scaled Window Support in DMX</title>
<author>Rickard E. Faith and Kevin E. Martin</author> <authorgroup>
<date>15 October 2003 (created 19 September 2003)</date> <author><firstname>Kevin E.</firstname><surname>Martin</surname></author>
<author><firstname>Rickard E.</firstname><surname>Faith</surname></author>
</authorgroup>
<pubdate>15 October 2003 (created 19 September 2003)</pubdate>
<abstract> <abstract>
<para>
This document investigates the possibility of adding scaled window This document investigates the possibility of adding scaled window
support to the DMX X server, thereby allowing a window or some support to the DMX X server, thereby allowing a window or some
selected part of the logical DMX area to be displayed using a selected part of the logical DMX area to be displayed using a
scaling factor. For example, this might allow the contents of a scaling factor. For example, this might allow the contents of a
window to be magnified for easier viewing. In particular, scaling window to be magnified for easier viewing. In particular, scaling
for the VNC client is explored. <it>Copyright 2003 for the VNC client is explored. <emphasis remap="it">Copyright 2003
by Red Hat, Inc., Raleigh, North Carolina</it> by Red Hat, Inc., Raleigh, North Carolina</emphasis>
</para>
</abstract> </abstract>
</articleinfo>
<!-- Table of contents -->
<toc>
<!-- Begin the document --> <!-- Begin the document -->
<sect>Introduction <sect1><title>Introduction</title>
<sect1>DMX <sect2><title>DMX</title>
<p> <para>
The DMX X server (Xdmx) is a proxy server that is designed The DMX X server (Xdmx) is a proxy server that is designed
to allow X servers on multiple machines to be combined into to allow X servers on multiple machines to be combined into
a single multi-headed X server. Combined with Xinerama, a single multi-headed X server. Combined with Xinerama,
@ -29,86 +36,86 @@
screen. Typical applications include the creation of a screen. Typical applications include the creation of a
video wall with 16 1280x1024 displays arranged in a video wall with 16 1280x1024 displays arranged in a
rectangle, for a total resolution of of 5120x4096. rectangle, for a total resolution of of 5120x4096.
</p> </para>
</sect1> </sect2>
<sect1>Problem Statement <sect2><title>Problem Statement</title>
<p> <para>
Applications displayed on a physically large video wall that Applications displayed on a physically large video wall that
provides high pixel-resolution may be difficult to see, provides high pixel-resolution may be difficult to see,
especially if the application is designed for use on a especially if the application is designed for use on a
typical desktop computer with a relatively small display typical desktop computer with a relatively small display
located close to the human operator. The goal of this paper located close to the human operator. The goal of this paper
is to describe and discuss solutions to this problem. is to describe and discuss solutions to this problem.
</p> </para>
<p> <para>
The original driving problem for this work is to provide The original driving problem for this work is to provide
scaling for the <tt>vncviewer</tt> application when scaling for the <command>vncviewer</command> application when
displayed using DMX (VNC scaling is currently available only displayed using DMX (VNC scaling is currently available only
with the Windows client, and there is no plan to extend that with the Windows client, and there is no plan to extend that
capability to other clients). While this specific problem capability to other clients). While this specific problem
will be addressed in this paper, the general solution space will be addressed in this paper, the general solution space
will also be explored, since this may lead to a good will also be explored, since this may lead to a good
solution not only for <tt>vncviewer</tt> but also for solution not only for <command>vncviewer</command> but also for
other applications. other applications.
</p> </para>
</sect1> </sect2>
<sect1>Task <sect2><title>Task</title>
<p> <para>
For reference, here is the original description of the task For reference, here is the original description of the task
this paper addresses: this paper addresses:
<itemize> <itemizedlist>
<item>Scaled window support (for VNC) <listitem><para>Scaled window support (for VNC)
<itemize> <itemizedlist>
<item> <listitem><para>
Investigate possibility of implementing a "scaled Investigate possibility of implementing a "scaled
window" extension: window" extension:
<itemize> <itemizedlist>
<item> <listitem><para>
Add XCreateScaledWindow call that could be used Add XCreateScaledWindow call that could be used
in place of XCreateWindow in place of XCreateWindow
</item> </para></listitem>
<item> <listitem><para>
All primitives drawn to scaled window would be All primitives drawn to scaled window would be
scaled by appropriate (integral?) scaling factor scaled by appropriate (integral?) scaling factor
</item> </para></listitem>
</itemize> </itemizedlist>
</item> </para></listitem>
<item> <listitem><para>
Alternate approach: special case VNC support Alternate approach: special case VNC support
</item> </para></listitem>
</itemize> </itemizedlist>
</item> </para></listitem>
</itemize> </itemizedlist>
</p> </para>
</sect1> </sect2>
</sect> </sect1>
<sect>Previous Work <sect1><title>Previous Work</title>
<p> <para>
This section reviews relevant previous work. This section reviews relevant previous work.
</p> </para>
<sect1>VNC <sect2><title>VNC</title>
<sect2>Scaling under VNC <sect3><title>Scaling under VNC</title>
<p> <para>
When using the <tt>vncviewer</tt> program for Windows, it When using the <command>vncviewer</command> program for Windows, it
is possible to specify a scaling factor (as numerator and is possible to specify a scaling factor (as numerator and
denominator). When scaling is in effect, the viewer denominator). When scaling is in effect, the viewer
software uses StretchBlt (instead of BitBlt) to display software uses StretchBlt (instead of BitBlt) to display
the pixels for the user. When this call is made, the the pixels for the user. When this call is made, the
viewer already has received all of the pixel information viewer already has received all of the pixel information
(at full unscaled resolution). (at full unscaled resolution).
</p> </para>
<p> <para>
The scaling in VNC is primitive. It does not conserve The scaling in VNC is primitive. It does not conserve
bandwidth, it does not treat textual information bandwidth, it does not treat textual information
differently (i.e., by using a suitably scaled font), and differently (i.e., by using a suitably scaled font), and
it does not provide any anti-aliasing other than that it does not provide any anti-aliasing other than that
provided by the underlying (Windows-only) system library. provided by the underlying (Windows-only) system library.
</p> </para>
</sect2> </sect3>
</sect1> </sect2>
<sect1>The X Video Extension <sect2><title>The X Video Extension</title>
<p> <para>
The X Video Extension is a widely-available extension to the The X Video Extension is a widely-available extension to the
X11 protocol that provides support for streaming video. X11 protocol that provides support for streaming video.
Integral to this support is the ability to arbitrarily scale Integral to this support is the ability to arbitrarily scale
@ -120,58 +127,58 @@
implemented in XFree86 only support data in various YUV implemented in XFree86 only support data in various YUV
formats. However, several modern video adaptors support RGB formats. However, several modern video adaptors support RGB
as well. as well.
</p> </para>
<p> <para>
Note, though, that the target output for this scaling is an Note, though, that the target output for this scaling is an
overlay plane -- so X Video provides functionality that is overlay plane -- so X Video provides functionality that is
fundamentally different from that provided by the Windows fundamentally different from that provided by the Windows
StrechBlt call. StrechBlt call.
</p> </para>
</sect1> </sect2>
</sect> </sect1>
<sect>Possible Solutions <sect1><title>Possible Solutions</title>
<p> <para>
This section briefly discusses possible solutions, including This section briefly discusses possible solutions, including
major advantages and disadvantages from both the major advantages and disadvantages from both the
implementation and the end-user programmer standpoint. implementation and the end-user programmer standpoint.
</p> </para>
<sect1>VNC-like Scaling <sect2><title>VNC-like Scaling</title>
<sect2>Software Scaling <sect3><title>Software Scaling</title>
<p> <para>
The <tt>vncviewer</tt> application could be modified to The <command>vncviewer</command> application could be modified to
provide software scaling. This is not a general solution, provide software scaling. This is not a general solution,
but it does solve one of the goals of this work. but it does solve one of the goals of this work.
</p> </para>
<p> <para>
A prototype of this solution was implemented and a patch A prototype of this solution was implemented and a patch
against <tt>vnc-3.3.7-unixsrc</tt> is available in the against <filename>vnc-3.3.7-unixsrc</filename> is available in the
<tt>dmx/external</tt> directory. Because of limited time <filename>dmx/external</filename> directory. Because of limited time
available for this work, all of the edge cases were not available for this work, all of the edge cases were not
considered and the solution works well mainly for integer considered and the solution works well mainly for integer
scaling. scaling.
</p> </para>
<p> <para>
Currently, <tt>vncviewer</tt> writes to the X display Currently, <command>vncviewer</command> writes to the X display
with XPutImage, XCopyArea, and XFillRectangle. All with XPutImage, XCopyArea, and XFillRectangle. All
instances of these calls have to be aware of scaling instances of these calls have to be aware of scaling
and must round correctly. In the prototype solution, and must round correctly. In the prototype solution,
rounding is incorrect and can cause artifacts. rounding is incorrect and can cause artifacts.
</p> </para>
<p> <para>
A better solution would be to cache all updates to the A better solution would be to cache all updates to the
desktop image in <tt>vncviewer</tt> and only send the desktop image in <command>vncviewer</command> and only send the
damaged area to the X display with XPutImage. This would damaged area to the X display with XPutImage. This would
allow the damaged area to be computed so that rounding allow the damaged area to be computed so that rounding
errors do not create artifacts. This method is probably errors do not create artifacts. This method is probably
similar to what is used in the Window client. (The whole similar to what is used in the Window client. (The whole
VNC suite is being re-written in C++ and the forthcoming VNC suite is being re-written in C++ and the forthcoming
version 4 has not been evaluated.) version 4 has not been evaluated.)
</p> </para>
</sect2> </sect3>
<sect2>Scaling with the X Video Extension <sect3><title>Scaling with the X Video Extension</title>
<p> <para>
The scaling in the Windows <tt>vncviewer</tt> application The scaling in the Windows <command>vncviewer</command> application
makes use of a scaled blit that is supplied by the makes use of a scaled blit that is supplied by the
underlying system library. Several video cards currently underlying system library. Several video cards currently
provide support for a scaled blit, and some X servers provide support for a scaled blit, and some X servers
@ -181,38 +188,38 @@
image being drawn to an overlay plane. Most video cards image being drawn to an overlay plane. Most video cards
also provide support for a scaled blit into the normal also provide support for a scaled blit into the normal
output planes, but this is not exposed via XvPutImage. output planes, but this is not exposed via XvPutImage.
</p> </para>
<p> <para>
The <tt>vncviewer</tt> program could be modified to use The <command>vncviewer</command> program could be modified to use
the X Video Extension to provide scaling under X11 that is the X Video Extension to provide scaling under X11 that is
similar to the scaling currently provided under Windows. similar to the scaling currently provided under Windows.
Unfortunately, Xdmx does not currently export the X Video Unfortunately, Xdmx does not currently export the X Video
Extension, so this would not provide an immediate solution Extension, so this would not provide an immediate solution
usable with DMX. usable with DMX.
</p> </para>
<p> <para>
A very early-stage proof-of-concept prototype was A very early-stage proof-of-concept prototype was
implemented and a preliminary patch against implemented and a preliminary patch against
<tt>vnc-3.3.7-unixsrc</tt> is available in the <filename>vnc-3.3.7-unixsrc</filename> is available in the
<tt>dmx/external</tt> directory. This prototype was <filename>dmx/external</filename> directory. This prototype was
implemented to better understand the problems that must be implemented to better understand the problems that must be
solved to make this solution viable: solved to make this solution viable:
<itemize> <itemizedlist>
<item> <listitem><para>
As noted under the software scaling section above, As noted under the software scaling section above,
<tt>vncviewer</tt> writes to the X display with <command>vncviewer</command> writes to the X display with
several different calls. These calls write to the several different calls. These calls write to the
normal output planes and are compatible with normal output planes and are compatible with
XvPutImage, which writes to an overlay plane. To XvPutImage, which writes to an overlay plane. To
eliminate artifacts caused by this problem, eliminate artifacts caused by this problem,
<tt>vncviewer</tt> should be modified so that a cached <command>vncviewer</command> should be modified so that a cached
copy of the desktop is available, either as a copy of the desktop is available, either as a
client-side image or a server-side off-screen pixmap, client-side image or a server-side off-screen pixmap,
so that XvPutImage would be the only method for so that XvPutImage would be the only method for
writing to the X display. writing to the X display.
</item> </para></listitem>
<item> <listitem>
<p> <para>
Although several modern graphics adaptors support Although several modern graphics adaptors support
hardware scaling using an RGB format (e.g., ATI hardware scaling using an RGB format (e.g., ATI
Radeon, nVidia, etc.), XFree86 drivers typically Radeon, nVidia, etc.), XFree86 drivers typically
@ -226,7 +233,8 @@
wire, additional artifacts are introduced (because wire, additional artifacts are introduced (because
there may not be enough information from the wire to there may not be enough information from the wire to
update a pair of pixels). update a pair of pixels).
<p> </para>
<para>
Further, the well-known problem with YUV encoding Further, the well-known problem with YUV encoding
is even more evident when the image is a desktop is even more evident when the image is a desktop
instead of a movie. For example, consider a instead of a movie. For example, consider a
@ -237,26 +245,28 @@
depending on the algorithm used for RGB to YUV depending on the algorithm used for RGB to YUV
conversion and on how the border pixel is ordered in conversion and on how the border pixel is ordered in
the pair of pixels used by the algorithm. the pair of pixels used by the algorithm.
<p> </para>
<para>
Many of these artifacts could be eliminated if Many of these artifacts could be eliminated if
<tt>vncviewer</tt> cached a complete RGB image of <command>vncviewer</command> cached a complete RGB image of
the desktop, and only did the conversion to YUV for the desktop, and only did the conversion to YUV for
properly aligned areas of damage. The remaining artifacts properly aligned areas of damage. The remaining artifacts
could be eliminated if an RGB format was used with X could be eliminated if an RGB format was used with X
Video (which may require the extension of existing Video (which may require the extension of existing
XFree86 drivers to support RGB). XFree86 drivers to support RGB).
</item> </para>
<item> </listitem>
<listitem><para>
Most modern video cards support exactly one overlay Most modern video cards support exactly one overlay
plane that is suitable for use with X Video. plane that is suitable for use with X Video.
Therefore, only one application can use X Video at any Therefore, only one application can use X Video at any
given time. This is a severe limitation in a desktop given time. This is a severe limitation in a desktop
environment. environment.
</item> </para></listitem>
</itemize> </itemizedlist>
</p> </para>
<sect3>Implementing the X Video Extension for DMX <sect4><title>Implementing the X Video Extension for DMX</title>
<p> <para>
The user-level API for X Video is fairly simple, but the The user-level API for X Video is fairly simple, but the
underlying support required for the full specification underlying support required for the full specification
is large. However, since the API provides a method to is large. However, since the API provides a method to
@ -264,56 +274,56 @@
Video can be implemented that would support XvPutImage Video can be implemented that would support XvPutImage
and little else. This would require support for the and little else. This would require support for the
following: following:
<itemize> <itemizedlist>
<item> <listitem><para>
X Video Extension API calls, including the X Video Extension API calls, including the
following: following:
<itemize> <itemizedlist>
<item>XvQueryExtension</item> <listitem><para>XvQueryExtension</para></listitem>
<item>XvQueryAdaptors</item> <listitem><para>XvQueryAdaptors</para></listitem>
<item>XvQueryPortAttributes</item> <listitem><para>XvQueryPortAttributes</para></listitem>
<item>XvFreeAdaptorInfo</item> <listitem><para>XvFreeAdaptorInfo</para></listitem>
<item>XvListImageFormats</item> <listitem><para>XvListImageFormats</para></listitem>
<item>XvGrabPort</item> <listitem><para>XvGrabPort</para></listitem>
<item>XvCreateImage</item> <listitem><para>XvCreateImage</para></listitem>
<item>XvPutImage</item> <listitem><para>XvPutImage</para></listitem>
<item>XvShmCreateImage</item> <listitem><para>XvShmCreateImage</para></listitem>
<item>XvShmPutImage</item> <listitem><para>XvShmPutImage</para></listitem>
</itemize> </itemizedlist>
</item> </para></listitem>
<item> <listitem><para>
Support for querying back-end X Video Extension Support for querying back-end X Video Extension
capabilities. capabilities.
</item> </para></listitem>
<item> <listitem><para>
Support for sending the image to the back-ends. Support for sending the image to the back-ends.
Because X Video requires sending full images, there Because X Video requires sending full images, there
may be a trade-off between bandwidth limitations and may be a trade-off between bandwidth limitations and
additional complexity to divide the image up such additional complexity to divide the image up such
that is scales properly. that is scales properly.
</item> </para></listitem>
<item> <listitem><para>
Possible support for a software fall-back. For Possible support for a software fall-back. For
example, if all of the back-ends do not support the X example, if all of the back-ends do not support the X
Video Extension, software scaling can be implemented Video Extension, software scaling can be implemented
such that the image is sent to the back-end with such that the image is sent to the back-end with
XPutImage. This pathway would have poor XPutImage. This pathway would have poor
performance. performance.
</item> </para></listitem>
</itemize> </itemizedlist>
</p> </para>
</sect3> </sect4>
<sect3>Supporting RGB formats for the X Video Extension <sect4><title>Supporting RGB formats for the X Video Extension</title>
<p> <para>
Assuming an XFree86 driver already supports the X Video Assuming an XFree86 driver already supports the X Video
Extension, and assuming the target hardware supports an Extension, and assuming the target hardware supports an
RGB format, then adding support for that format is RGB format, then adding support for that format is
relatively simple and straightforward. relatively simple and straightforward.
</p> </para>
</sect3> </sect4>
</sect2> </sect3>
<sect2>Scaling with an XPutImageScaled Extension <sect3><title>Scaling with an XPutImageScaled Extension</title>
<p> <para>
Instead of (or in addition to) implementing the X Video Instead of (or in addition to) implementing the X Video
Extension in DMX, one obvious solution would be to Extension in DMX, one obvious solution would be to
implement a new extension that provides access to implement a new extension that provides access to
@ -321,59 +331,59 @@
call available under Windows. This call would scale RGB call available under Windows. This call would scale RGB
images and would not use the overlay plane (unlike the X images and would not use the overlay plane (unlike the X
Video Extension). Video Extension).
</p> </para>
<p> <para>
This approach has many of the same advantages and This approach has many of the same advantages and
disadvantages as the XCopyAreaScaled Extension, discussed disadvantages as the XCopyAreaScaled Extension, discussed
in the next section. Discussion of XPutImageScaled is in the next section. Discussion of XPutImageScaled is
deferred in favor of XCopyAreaScaled for the following deferred in favor of XCopyAreaScaled for the following
reasons: reasons:
<itemize> <itemizedlist>
<item> <listitem><para>
XPutImageScaled can be emulated with XCopyAreaScaled XPutImageScaled can be emulated with XCopyAreaScaled
by first using XPutImage to copy the image to an by first using XPutImage to copy the image to an
off-screen pixmap, and then calling XCopyAreaScaled off-screen pixmap, and then calling XCopyAreaScaled
between that off-screen pixmap and the target between that off-screen pixmap and the target
drawable. drawable.
</item> </para></listitem>
<item> <listitem><para>
Since XCopyAreaScaled would copy between two areas of Since XCopyAreaScaled would copy between two areas of
on-screen or off-screen memory, it has additional uses on-screen or off-screen memory, it has additional uses
and can be viewed as efficiently providing a superset and can be viewed as efficiently providing a superset
of XPutImageScaled functionality. of XPutImageScaled functionality.
</item> </para></listitem>
</itemize> </itemizedlist>
</p> </para>
</sect2> </sect3>
<sect2>Scaling with an XCopyAreaScaled Extension <sect3><title>Scaling with an XCopyAreaScaled Extension</title>
<p> <para>
As noted in the previous section, because XCopyAreaScaled As noted in the previous section, because XCopyAreaScaled
provides a superset of the functionality provided by provides a superset of the functionality provided by
XPutImageScaled, we will consider this extension instead. XPutImageScaled, we will consider this extension instead.
</p> </para>
<p> <para>
First, XCopyAreaScaled would provide for RGB scaling First, XCopyAreaScaled would provide for RGB scaling
between pixmaps (i.e., on-screen or off-screen areas of between pixmaps (i.e., on-screen or off-screen areas of
memory that reside on the video card). Unlike the X Video memory that reside on the video card). Unlike the X Video
Extension, which writes into an overlay plane, Extension, which writes into an overlay plane,
XCopyAreaScaled would write into the non-overlay areas of XCopyAreaScaled would write into the non-overlay areas of
the screen. Key points to consider are as follows: the screen. Key points to consider are as follows:
<itemize> <itemizedlist>
<item> <listitem><para>
Because different planes are involved, the two scaling Because different planes are involved, the two scaling
operations are usually implemented in hardware operations are usually implemented in hardware
differently, so an XCopyAreaScaled extension could be differently, so an XCopyAreaScaled extension could be
added in a manner that would neither conflict with nor added in a manner that would neither conflict with nor
interact with the X Video extension in any way. interact with the X Video extension in any way.
</item> </para></listitem>
<item> <listitem><para>
The XCopyAreaScaled extension provides new The XCopyAreaScaled extension provides new
functionality that the X Video Extension does not functionality that the X Video Extension does not
provide. Based on anecdotal feedback, we believe that provide. Based on anecdotal feedback, we believe that
many people outside the DMX and VNC communities would many people outside the DMX and VNC communities would
be excited about this extension. be excited about this extension.
</item> </para></listitem>
<item> <listitem><para>
The main drawback to this extension is that it is new The main drawback to this extension is that it is new
and needs to be implemented at the driver level in and needs to be implemented at the driver level in
XFree86 for each video card to be supported. At the XFree86 for each video card to be supported. At the
@ -384,8 +394,8 @@
XCopyAreaScaled extension to be implemented along with XCopyAreaScaled extension to be implemented along with
the X Video extension, especially if it becomes the X Video extension, especially if it becomes
popular. popular.
</item> </para></listitem>
<item> <listitem><para>
Another drawback is that not all modern cards provide Another drawback is that not all modern cards provide
support for a simple scaled blit operation. However, support for a simple scaled blit operation. However,
these cards usually do provide a 3D pipeline which these cards usually do provide a 3D pipeline which
@ -394,12 +404,12 @@
that is using the XCopyAreaScaled extension. However, that is using the XCopyAreaScaled extension. However,
this implementation pathway would make this extension this implementation pathway would make this extension
somewhat more difficult to implement on certain cards. somewhat more difficult to implement on certain cards.
</item> </para></listitem>
</itemize> </itemizedlist>
</p> </para>
</sect2> </sect3>
<sect2>Scaling with OpenGL <sect3><title>Scaling with OpenGL</title>
<p> <para>
Another general solution to the scaling problem is to use Another general solution to the scaling problem is to use
the texture scaling found in all 3D hardware. This the texture scaling found in all 3D hardware. This
ability is already exposed through OpenGL and can be ability is already exposed through OpenGL and can be
@ -411,8 +421,8 @@
around the single overlay problem with the X Video around the single overlay problem with the X Video
Extension as well as the need to implement additional Extension as well as the need to implement additional
scaled primitive extensions. scaled primitive extensions.
</p> </para>
<p> <para>
The downside is that most OpenGL implementations require The downside is that most OpenGL implementations require
power of 2 texture sizes and this can be very wasteful of power of 2 texture sizes and this can be very wasteful of
memory if, for example, the application needs to scale a memory if, for example, the application needs to scale a
@ -422,18 +432,18 @@
implementations have a limited about of texture memory and implementations have a limited about of texture memory and
cannot handle textures that are very large. For example, cannot handle textures that are very large. For example,
they might limit the texture size to 1024x1024. they might limit the texture size to 1024x1024.
</p> </para>
</sect2> </sect3>
</sect1> </sect2>
<sect1>Application-transparent Scaling for DMX <sect2><title>Application-transparent Scaling for DMX
<sect2>Back-end Scaling Without Disconnect/Reconnect </title><sect3><title>Back-end Scaling Without Disconnect/Reconnect</title>
<p> <para>
VNC does scaling on the client side (in the VNC does scaling on the client side (in the
<tt>vncviewer</tt> application). Implementing a similar <command>vncviewer</command> application). Implementing a similar
solution for DMX would require support in the back-end X solution for DMX would require support in the back-end X
servers and, therefore, is not a general solution. servers and, therefore, is not a general solution.
</p> </para>
<p> <para>
XFree86 already implements some support for "scaling" that XFree86 already implements some support for "scaling" that
could be used with DMX: if, in the XF86Config file, could be used with DMX: if, in the XF86Config file,
multiple Modes are listed in the Display Subsection of the multiple Modes are listed in the Display Subsection of the
@ -443,15 +453,15 @@
dimensions in the Modes line, but the logical dimensions dimensions in the Modes line, but the logical dimensions
of the X server (i.e., the dimensions that Xdmx knows of the X server (i.e., the dimensions that Xdmx knows
about) will not change. about) will not change.
</p> </para>
<p> <para>
Further, the dimensions of the XFree86 display are under Further, the dimensions of the XFree86 display are under
software control (via the XFree86-VidModeExtension), so software control (via the XFree86-VidModeExtension), so
the Xdmx server could change the screen dimensions on a the Xdmx server could change the screen dimensions on a
per-display basis, thereby scaling the information on part per-display basis, thereby scaling the information on part
of that display. of that display.
</p> </para>
<p> <para>
However, this scaling appears to have limited use. For However, this scaling appears to have limited use. For
example, assume a 4 by 4 display wall consisting of 16 example, assume a 4 by 4 display wall consisting of 16
1280x1024 displays. If all of the back-end servers were 1280x1024 displays. If all of the back-end servers were
@ -461,31 +471,31 @@
display at a time could be usable, but could have limited display at a time could be usable, but could have limited
utility, since the result would still be no larger than a utility, since the result would still be no larger than a
single display. single display.
</p> </para>
</sect2> </sect3>
<sect2>Back-end Scaling With Disconnect/Reconnect <sect3><title>Back-end Scaling With Disconnect/Reconnect</title>
<p> <para>
Disconnect and reconnect features are not currently Disconnect and reconnect features are not currently
supported in DMX, but are scheduled to be implemented in supported in DMX, but are scheduled to be implemented in
the future. These features, combined with the the future. These features, combined with the
XFree86-VidModeExtension Extension, would allow an XFree86-VidModeExtension Extension, would allow an
application to do the following: application to do the following:
<itemize> <itemizedlist>
<item> <listitem><para>
Disconnect a specific back-end server (via the DMX Disconnect a specific back-end server (via the DMX
Extension), Extension),
</item> </para></listitem>
<item> <listitem><para>
reconfigure the XFree86 back-end server resolution, reconfigure the XFree86 back-end server resolution,
and and
</item> </para></listitem>
<item> <listitem><para>
reconnect the back-end server to DMX -- at a new reconnect the back-end server to DMX -- at a new
origin with the new screen resolution. origin with the new screen resolution.
</item> </para></listitem>
</itemize> </itemizedlist>
</p> </para>
<p> <para>
For example, consider a display wall consisting of 16 For example, consider a display wall consisting of 16
1280x1024 displays with a total resolution of 5120x4096. 1280x1024 displays with a total resolution of 5120x4096.
All of the screens could be disconnected, repositioned, All of the screens could be disconnected, repositioned,
@ -498,18 +508,18 @@
the increased resolution was completed, the back-end the increased resolution was completed, the back-end
servers could be disconnected, reconfigured, and servers could be disconnected, reconfigured, and
reconnected for the original 5120x4096 view. reconnected for the original 5120x4096 view.
</p> </para>
<p> <para>
Support for this type of scaling can be implemented in a Support for this type of scaling can be implemented in a
DMX-aware X11 client assuming the DMX server support DMX-aware X11 client assuming the DMX server support
arbitrary disconnect and reconnect semantics. Because arbitrary disconnect and reconnect semantics. Because
this application cannot be written before this application cannot be written before
disconnect/reconnect is implemented, this solution will disconnect/reconnect is implemented, this solution will
not be discussed further in this paper. not be discussed further in this paper.
</p> </para>
</sect2> </sect3>
<sect2>Server-side Scaling <sect3><title>Server-side Scaling</title>
<p> <para>
In earlier versions of DMX, a frame buffer was maintained In earlier versions of DMX, a frame buffer was maintained
on the server side, and XPutImage was used to move the on the server side, and XPutImage was used to move the
information from the server to the client (similar to some information from the server to the client (similar to some
@ -518,14 +528,14 @@
not a recommended solution because of overall performance not a recommended solution because of overall performance
issues and server-side memory issues (i.e., the frame issues and server-side memory issues (i.e., the frame
buffer would be very large for large display walls). buffer would be very large for large display walls).
</p> </para>
<p> <para>
Exploration of this path is not recommended. Exploration of this path is not recommended.
</p> </para>
</sect2> </sect3>
</sect1> </sect2>
<sect1>XCreateScaledWindow API <sect2><title>XCreateScaledWindow API</title>
<p> <para>
The implementation of X Video Extension in DMX, and the use The implementation of X Video Extension in DMX, and the use
of XvPutImage by applications requiring scaling requires of XvPutImage by applications requiring scaling requires
significant changes in DMX Further, XvPutImage is, significant changes in DMX Further, XvPutImage is,
@ -533,8 +543,8 @@
applications which are already using (or can be modified to applications which are already using (or can be modified to
use) XPutImage. Therefore, a more general API will be use) XPutImage. Therefore, a more general API will be
discussed as another possibility. discussed as another possibility.
</p> </para>
<p> <para>
X applications typically create windows with the X applications typically create windows with the
XCreateWindow call. A new extension could provide an XCreateWindow call. A new extension could provide an
XCreateScaledWindow call that could be used in place of the XCreateScaledWindow call that could be used in place of the
@ -544,33 +554,33 @@
scaling. In this section we describe how the call would scaling. In this section we describe how the call would
work, what transparency it provides, and how to solve the work, what transparency it provides, and how to solve the
potential problems that transparency creates. potential problems that transparency creates.
</p> </para>
<sect2>XCreateWindow <sect3><title>XCreateWindow</title>
<p> <para>
The XCreateWindow call takes width and height as The XCreateWindow call takes width and height as
parameters. An XCreateScaledWindow call could take all parameters. An XCreateScaledWindow call could take all
the same parameters, with the addition of a scaling factor. the same parameters, with the addition of a scaling factor.
</p> </para>
</sect2> </sect3>
<sect2>XSetWindowAttributes <sect3><title>XSetWindowAttributes</title>
<p> <para>
An X11 window has several attributes that would have to be An X11 window has several attributes that would have to be
scaled: scaled:
<itemize> <itemizedlist>
<item>Background and border pixmaps</item> <listitem><para>Background and border pixmaps</para></listitem>
<item>Border width</item> <listitem><para>Border width</para></listitem>
<item>Cursor</item> <listitem><para>Cursor</para></listitem>
</itemize> </itemizedlist>
</p> </para>
</sect2> </sect3>
<sect2>XGetWindowAttributes, XGetGeometry <sect3><title>XGetWindowAttributes, XGetGeometry</title>
<p> <para>
For transparency, calls that query the window attributes For transparency, calls that query the window attributes
should return unscaled information. This suggests that should return unscaled information. This suggests that
all unscaled pixmaps and window attributes should be all unscaled pixmaps and window attributes should be
cached. cached.
</p> </para>
<p> <para>
Unfortunately, a window manager requires the scaled Unfortunately, a window manager requires the scaled
geometry to properly decorate the window. The X server geometry to properly decorate the window. The X server
can probably determine which client is acting as the can probably determine which client is acting as the
@ -581,26 +591,26 @@
least two additional extension calls should be least two additional extension calls should be
implemented: XGetScaledWindowAttributes and implemented: XGetScaledWindowAttributes and
XGetScaledGeometry. XGetScaledGeometry.
</p> </para>
</sect2> </sect3>
<sect2>Popup and Child window positions <sect3><title>Popup and Child window positions</title>
<p> <para>
Some applications may position popup and child windows Some applications may position popup and child windows
based on an unscaled notion of the main window geometry. based on an unscaled notion of the main window geometry.
In this case, additional modifications to the client would In this case, additional modifications to the client would
be required. be required.
</p> </para>
</sect2> </sect3>
<sect2>Events <sect3><title>Events</title>
<p> <para>
Most events (e.g., for mouse motion) return information Most events (e.g., for mouse motion) return information
about the coordinates at which the even occurred. These about the coordinates at which the even occurred. These
coordinates would have to be modified so that unscaled coordinates would have to be modified so that unscaled
values were presented to the client. values were presented to the client.
</p> </para>
</sect2> </sect3>
<sect2>Implementation <sect3><title>Implementation</title>
<p> <para>
There are many implementation issues, some of which are There are many implementation issues, some of which are
similar to the issues involved in implementing the X Video similar to the issues involved in implementing the X Video
Extension for DMX. The window contents must be scaled, Extension for DMX. The window contents must be scaled,
@ -610,25 +620,26 @@
various drawing operations to perform scaling. Because of various drawing operations to perform scaling. Because of
the complexity involved, the frame buffer option is the complexity involved, the frame buffer option is
recommended. recommended.
</p> </para>
</sect2> </sect3>
</sect1> </sect2>
</sect> </sect1>
<sect>Conclusion and Recommendations <sect1><title>Conclusion and Recommendations
<p> </title><para>
We recommend a three phase implementation strategy, based on We recommend a three phase implementation strategy, based on
how an application could be written to take advantage of how an application could be written to take advantage of
scaling: scaling:
<enum> <orderedlist>
<item> <listitem>
<p> <para>
The XCopyAreaScaled extension should be implemented, since The XCopyAreaScaled extension should be implemented, since
this is the ideal solution for applications like VNC, and this is the ideal solution for applications like VNC, and
since making use of this extension will require minimal since making use of this extension will require minimal
changes to applications that already use XPutImage or changes to applications that already use XPutImage or
XCopyArea. XCopyArea.
<p> </para>
<para>
The initial implementation work would include the design The initial implementation work would include the design
of the X protocol extension, writing this up in the of the X protocol extension, writing this up in the
usual format for extension documentation, implementation usual format for extension documentation, implementation
@ -636,7 +647,8 @@
implementation of a software fall-back in XFree86 and implementation of a software fall-back in XFree86 and
DMX, one example hardware implementation for XFree86, DMX, one example hardware implementation for XFree86,
and implementation of support for this extension in DMX. and implementation of support for this extension in DMX.
<p> </para>
<para>
We suggest implementing the extension first on the ATI We suggest implementing the extension first on the ATI
Radeon cards. However, since these cards do not provide Radeon cards. However, since these cards do not provide
a 2D scaled blit primitive, the implementation would a 2D scaled blit primitive, the implementation would
@ -645,61 +657,67 @@
graphics cards also do not provide a simple 2D scaled graphics cards also do not provide a simple 2D scaled
blit operation and an example of the more difficult blit operation and an example of the more difficult
implementation pathway would be helpful to others. implementation pathway would be helpful to others.
</item> </para>
<item> </listitem>
<p> <listitem>
<para>
Until XCopyAreaScaled is widely supported, applications Until XCopyAreaScaled is widely supported, applications
that require scaling will have to fall back to another that require scaling will have to fall back to another
scaling method. We suggest OpenGL as the first fall-back scaling method. We suggest OpenGL as the first fall-back
method because it is widely available and supported by method because it is widely available and supported by
DMX. DMX.
<p> </para>
<para>
A project centered around OpenGL-based scaling would A project centered around OpenGL-based scaling would
implement this scaling in VNC as an example. This work implement this scaling in VNC as an example. This work
would include re-writing the <tt>vncviewer</tt> would include re-writing the <command>vncviewer</command>
rendering engine to cache a master copy of the desktop rendering engine to cache a master copy of the desktop
image for all operations. image for all operations.
</item> </para>
<item> </listitem>
<p> <listitem>
<para>
Since OpenGL is not implemented everywhere, and may not Since OpenGL is not implemented everywhere, and may not
provide hardware-assisted performance in every provide hardware-assisted performance in every
implementation, an application that requires scaling implementation, an application that requires scaling
should also fall back to using the X Video Extension. should also fall back to using the X Video Extension.
<p> </para>
<para>
This project would add support for the X Video Extension This project would add support for the X Video Extension
to DMX and would add support to VNC to take advantage of to DMX and would add support to VNC to take advantage of
this extension without introducing artifacts. This this extension without introducing artifacts. This
would require modifying the <tt>vncviewer</tt> rendering would require modifying the <command>vncviewer</command> rendering
engine to cache a master copy of the desktop image for engine to cache a master copy of the desktop image for
all operations. This project should also add support all operations. This project should also add support
for the RGB format to at least one XFree86 driver (e.g., for the RGB format to at least one XFree86 driver (e.g.,
ATI Radeon). ATI Radeon).
<p> </para>
<para>
The X Video Extension is one of the few popular The X Video Extension is one of the few popular
extensions that DMX does not support. We recommend extensions that DMX does not support. We recommend
implementing the X Video Extension even if scaling is implementing the X Video Extension even if scaling is
the specific goal of that work. the specific goal of that work.
</item> </para>
</enum> </listitem>
</p> </orderedlist>
<p> </para>
We do <bf>not</bf> recommend implementation of the <para>
We do <emphasis>not</emphasis> recommend implementation of the
XCreateScaledWindow extension because of the complexity XCreateScaledWindow extension because of the complexity
involved. We do <bf>not</bf> recommend implementation of the involved. We do <emphasis>not</emphasis> recommend implementation of the
XPutImageScaled extension because it requires the same amount XPutImageScaled extension because it requires the same amount
of work as the XCopyAreaScaled extension, but provides less of work as the XCopyAreaScaled extension, but provides less
functionality. Further, server-side scaling with a large functionality. Further, server-side scaling with a large
frame buffer is <bf>not</bf> recommended because of the frame buffer is <emphasis>not</emphasis> recommended because of the
performance implications. performance implications.
</p> </para>
<p> <para>
The back-end scaling, especially with disconnect/reconnect The back-end scaling, especially with disconnect/reconnect
support should be explored in the future after support should be explored in the future after
disconnect/reconnect is implemented, but not at the present disconnect/reconnect is implemented, but not at the present
time. time.
</p> </para>
</sect> </sect1>
</article> </article>
<!-- Local Variables: --> <!-- Local Variables: -->

7420
hw/xfree86/doc/sgml/DESIGN.sgml
View File

File diff suppressed because it is too large Load Diff

9376
hw/xfree86/doc/sgml/DESIGN.xml Normal file
View File

File diff suppressed because it is too large Load Diff

37
hw/xfree86/doc/sgml/Makefile.am
View File

@ -19,36 +19,13 @@
# NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN # NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. # CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
SGML_FILES = DESIGN.sgml XML_FILES = DESIGN.xml
if BUILD_LINUXDOC include ../../../../doc/xml/xmlrules.in
TXT_FILES = $(SGML_FILES:%.sgml=%.txt)
PS_FILES = $(SGML_FILES:%.sgml=%.ps) if ENABLE_DEVEL_DOCS
if BUILD_PDFDOC noinst_DATA = $(BUILT_DOC_FILES)
PDF_FILES = $(SGML_FILES:%.sgml=%.pdf)
endif endif
HTML_FILES = $(SGML_FILES:%.sgml=%.html) CLEANFILES = $(CLEAN_DOC_FILES)
SUFFIXES = .sgml .txt .html .ps .pdf EXTRA_DIST = $(XML_FILES)
.sgml.txt:
@rm -f $@
$(AM_V_GEN)$(MAKE_TEXT) $<
.sgml.ps:
@rm -f $@
$(AM_V_GEN)$(MAKE_PS) $<
.ps.pdf:
@rm -f $@
$(AM_V_GEN)$(MAKE_PDF) $<
.sgml.html:
@rm -f $@
$(AM_V_GEN)$(MAKE_HTML) $<
noinst_DATA = $(TXT_FILES) $(PS_FILES) $(PDF_FILES) $(HTML_FILES)
CLEANFILES = $(TXT_FILES) $(PS_FILES) $(PDF_FILES) $(HTML_FILES)
endif
EXTRA_DIST = $(SGML_FILES)