X11IRAF V2.0 RELEASE NOTES
==========================
Last Modified: Mon Nov 17 12:00:11 MST 2008
-------------------------------------------------------------------------------
Release History:
November 17, 2008 -- Initial V2.0BETA public release
-------------------------------------------------------------------------------
Table of Contents:
------------------
Executive Summary
1. Download and Installation
1.1 Downloading the Distribution
1.2 Installing Pre-Built Binaries
1.3 Building From Source
1.4 Comments, Suggestions and Bug Reports
2. XImtool Revisions
2.1 XGterm Revisions
3. Platform Support Issues
3.1 Linux Systems
3.1.1 Determining your Graphics Hardware
3.1.2 Intel Chipset Issues
3.1.3 NVidia Issues
3.2 Mac OSX Systems
3.2.1 Tiger and Leopard Support
3.3 Other Platforms
4. OBM (Widget Server) Revisions
4.1 GTerm Widget Changes
4.2 Athena Widget Changes
5. Client Display Library (CDL) Revisions
5.1 Display Protocol Changes
6. Technical Notes
6.1 IIS Protocol Changes
6.1.1 IIS Protocol Summary
6.1.2 Faster Sub-Raster Writes
7. Post-Release Notes
-------------------------------------------------------------------------------
==================
Executing Summary
==================
This release provides the following improvements over previous versions:
1) 24-bit display Support for XImtool
2) 24-bit display Support for XGterm applications using imaging
3) General platform support improvements
For those accustomed to DS9 and not familiar with XImtool, a summary of
features is provided at
ftp://iraf.noao.edu/iraf/x11iraf/Notes-V1.3.html
This document will be updated as needed, see the 'Revisions' file for a
detailed list of changes made in the source code.
-------------------------------------------------------------------------------
=============================
1. DOWNLOAD AND INSTALLATION
=============================
1.1 Downloading the Distribution
---------------------------------
The X11IRAF v2.0 system is being distributed as tarballs of either
pure-source or prebuilt binaries. The convention in open-source software
is that such tarballs create the toplevel directory for the application,
however we require that users first create a directory for the distribution
file since we don't want to impose a directory name that might overlap
existing versions. We may reconsider this based on user suggestions, but
users should be aware that creating the package directory is required before
unpacking either source or binaries.
Distributions are available in the following files:
Source Distribution:
http://iraf.noao.edu/x11iraf/x11iraf-v2.0BETA-src.tar.gz
Pre-built Binaries:
http://iraf.noao.edu/x11iraf/x11iraf-v2.0BETA-bin.redhat.tar.gz
http://iraf.noao.edu/x11iraf/x11iraf-v2.0BETA-bin.macosx.tar.gz
http://iraf.noao.edu/x11iraf/x11iraf-v2.0BETA-bin.macintel.tar.gz
Once the system is out of the Beta-test phase the version string will
change, additional platform binaries will be added as they become
available. The Mac OSX binaries are suitable for Tiger or Leopard systems,
Redhat binaries should run on most Linux systems whether based on a Redhat
distribution or not. See the platform-specific notes below for additional
details.
1.2 Installing Pre-Built Binaries
----------------------------------
Installing from binaries is a simple matter of finding the approp-
riate distribution file for your platform. Unpacking the file can be
done using the commands (e.g.)
% mkdir /path/x11iraf # create the X11IRAF directory
% cd /path/x11iraf # go into X11IRAF directory
and then unpack the tarball using a command such as
% tar zxvf x11iraf-v2.0BETA-bin.macintel.tar.gz
This will create an 'x11iraf' directory in the place you execute the
command that contains the distribution.
Installing to the default system directories will require root permission
and can be accomplished with the commands:
% su # become the root user
# ./install # install the files (interactive)
or
% sudo ./install # execute install as root
1.3 Building From Source
-------------------------
Installing from source is a simple matter downloading the
source distribution and unpacking the file in a directory you create.
Unpacking the file can be done using the commands (e.g.)
% mkdir /path/x11iraf # create the X11IRAF directory
% cd /path/x11iraf # go into X11IRAF directory
and then unpack the tarball using a command such as
% tar zxvf x11iraf-v2.0BETA-src.tar.gz
This will create an 'x11iraf' directory in the place you execute the
command that contains the distribution.
To build and install from an unpacked source distribution:
% mkdir /path/x11iraf create the X11IRAF directory
% cd /path/x11iraf go into X11IRAF directory
% xmkmf build the package Makefile
% make World build binaries from sources
% su become the root user
# ./install install the files (interactive)
or
% sudo ./install execute install as root
Only the last two commands are required to install from an unpacked binary
distribution. Note that root permission is required in order to install to
the default system locations. The X development environment for your
platform must be installed prior to building sources, otherwise please
install from one of the available binary distributions.
1.4 Comments, Suggestions and Bug Reports
------------------------------------------
Please report any bugs, comments or suggestions to
fitz@noao.edu
Additionally, X11IRAF announcements and a user-forum is available at
http://iraf.net
When reporting problems, please provide as much information as possible
(e.g. platform, OS version, commands used, buttons pushed, etc) so the
error can be reproduced.
--------------------------------------------------------------------------------
======================
2. XIMTOOL REVISIONS
======================
The scope of this upgrade was limited entirely to supporting the
existing X11IRAF applications and features on TrueColor visuals (so-called
'24-bit displays'). As such, the changes to XImtool itself were relatively
minor and mostly limited to internal changes and not user-features.
The one exception to this is the addition of a new GUI feature on
the display window we call the 'colormap focus slider'. This is a new GUI
element that is used to set the size of an interactive update box on the
display window that will be refreshed as the user slides the mouse around
to do the contrast stretching of the image. By default, this will be the
entire display window (i.e. the slider is all the way to the right), but it
can be changed to make the update window smaller to the point where when
the slider is on the far-left a box of 128x128 (deemed to be the minimally
useful size) is set. Upon releasing the mouse window, the entire display
will be updated.
[NOTE: At present, there are known issues in the V2.0BETA version
with this box not being properly updated as a result of window
resizing. These problems will be addressed.]
On many systems, the refresh rates for contrast stretching will be
satisfactory, however certain OS/hardware configurations exhibit problems
resulting in poor performance. Details (as they are known) of these
configurations are described below, however this slider is meant as a
stopgap for users to change the refresh box as needed to achieve acceptable
rates. Even on fully-supported hardware, this box can be used to mitigate
performance problems when using XImtool over remote X connections.
A long list of possible XImtool enhancements is prepared, however
we are relying on the user-community to provide input in the way of
suggestions and comments that this work is needed before deciding to allocate
scarce resources to further development.
2.1 XGterm Revisions
----------------------
No changes to XGterm we made specifically during this upgrade,
however the underlying Gterm widget changes means that IRAF tasks in the
XAPPHOT package of the GUIAPPS external package can now be used on 24-bit
displays. Because of the color changes required, some work still remains
to fixup resource in the XAPPHOT gui itself, however for the most part it
is now functional on 24-bit displays as well.
--------------------------------------------------------------------------------
============================
3. PLATFORM SUPPORT ISSUES
============================
3.1 Linux Systems
------------------
In early testing, a number of issues arose that were caused in part
by host-system graphics issues. With TrueColor support, the interactive
contrast stretching requires many times more screen refreshes than in the
8-bit version where only the colormap was updated. As a result, even though
the machines have become much faster, there is a greater dependence on how
well the underlying hardware is supported by the system. Combined with a
general switch from the old XFree86 X11 systems to the newer (and supposedly
better) X.org code base, we are once again faced with the issue of driver
support under Linux systems.
Proprietary drivers such as for NVidia graphics card present a
challenge for Linux developers since much of the system has to be reverse-
engineered. NVidia itself is improving it's support for Linux but the most
recent drivers have not yet made their way into mainstream linux
distributions. Likewise, there are problems with other graphics chipsets
or specific window managers, but there are also a large number of users who
will see no specific problems at all.
The sections below will be updated as new problems (and solutions)
are found, and if changes can be made in the XImtool application itself they
will be implemented. Most commonly, any problems you experience will be
with the rate at which the screen refreshes in response to brightness/contrast
scaling of the image. Window resizing is another issue that may come up
and will depend on the type of window manager used. When reporting issues,
please be as specific as possible about the hardware, window manager and
OS version you are using as well as steps needed to reproduce any problem.
3.1.1 Determining your Graphics Hardware
-----------------------------------------
On many Linux systems the 'lspci' command can be used to print
the PCI hardware of the machine. For example
% /sbin/lspci | grep -i VGA
22:06:01.0 VGA compatible controller: ATI Technologies Inc Rage XL (rev 27)
indicates this machine has an ATI Rage XL graphics card. The location of
the command may vary but /sbin is common.
Additionally, systems such as Ubunto have control-panel applications
that can be used to list details of machine hardware.
3.1.2 Intel Chipset Issues
----------------------------
Intel graphics chips are common on many laptops, however the default
'EXA' acceleration is known to be slow on systems using recent versions of
the X.org server. The suggested workaround is to edit your /etc/X11/xorg.conf
file and add the following to your 'Device' section:
Option "AccelMethod" "exa"
Option "MigrationHeuristic" "greedy"
Option "ExaNoComposite" "false"
This has been reported to improve the screen-refresh performance of a number
of applications.
An alternative, is to change the 'AccelMethod' option to be 'xaa'
to use a different accelerator. The disadvantage here is that certain
applications requiring video capability (such as Compiz-Fusion window manager
on Ubuntu) will no longer work properly. For older X.org systems, however,
this may be the only option.
3.1.3 NVidia Issues
---------------------
Linux systems running the X.org server with the stock 'nv' driver
have reported slow refresh rates when stretching the image contrast. To
help alleviate thi sproblem the 'colormap focus slider' on the bottom of
the main window can be used to adjust the size of the interactive refresh
area to tolerable rates.
A better solution is to install the latest version of the nvidia
driver available for linux from the driver page at:
http://www.nvidia.com/object/unix.html
This driver update has been reported to greatly improve the performace of
the system and is recommended to those comfortable doing the upgrade.
3.1.4 Ubuntu Issues
---------------------
Ubuntu linux systems using the Compiz-Fusion window manager have
reported problems with some of the static colors being rendered properly.
At this time, there are no known workarounds while the problem is being
investigated.
3.2 Mac OSX Systems
--------------------
3.2.1 Tiger and Leopard Support
--------------------------------
An Intel MacBook Pro running 10.4 (Tiger) was used as a primary
development platform, however the same code base compiled under 10.4 is
known to run on 10.5 (Leopard) systems for both Intel and PPC systems.
With 10.5, Apple switched from an XFree6-based X11 environment to
one based on the X.org server, and the resulting problems are well documented
on the net but pertain mainly to 8-bit application support. As far as this
package is concerned, the only issue appears to be one of screen-refresh
speeds on machines with NVidia graphics cards (e.g. 12" MacBook Pro and other
older systems). This is similar to speed problems seen under Linux and may
be solved in future updates of the Apple X11 server. For now, the workaround
is to utilize the "colormap focus slider" described above to set an update
box-size that gives satisfacory performance.
Other issues and solutions found with Mac systems will be documented
here as they arise.
3.3 Other Platforms
--------------------
As of this release the only major system lacking support is the
Windows platform using Cygwin, however this is planned before the final
public release of the package.
Issues identified with Mac version support (considering the
upheavals in the X support under 10.5) will be addressed as they come up
with the goal that a single binary for each CPU architecture will be all
that is required. A Universal binary is being considered but was not a
focus of this release.
--------------------------------------------------------------------------------
==================================
4. OBM (WIDGET SERVER) REVISIONS
==================================
The primary focus of changes in this release is to update all
tasks and toolkits to support 24-bit (more generically, 'TrueColor visual')
displays. No signbificant new features were added however many files
were checked and slightly modified so they would work in the new display
environment.
4.1 GTerm Widget Changes
-------------------------
The custom Gterm widget obviously underwent significant change
during this upgrade. To summarize the issue: With an 8-bit PseudoColor
display the contrast stretching is done by simply rewriting the scaled
colormap to the display (256 elements), but with a TrueColor visual there
is no colormap and the RGB value of *each pixel on the screen* must be
updated and refreshed when a change is made (i.e. 512x512 pixels or more
depending on the screen size). Increased CPU/GPU power makes fast updates
possible compared to 10 years ago, however much depends on the graphics
hardware and how well it is supported by the underlying OS and the X server
used.
Fundamentally, the Gterm widget still retains the concept of a
colormap so that the higher-level applications which rely on it can remain
almost completely unchanged. The support for TrueColor displays is added
at the lowest level of the widget that interacts directly with the X
display. For example, in XImtool a "frame" consists internally of a client
XImage that holds the 8-bit display data sent by the client and is the size
of the frame buffer. This frame also has a 'pixmap' that is the same depth
as the display visual (e.g. 24-bits) however it is only the size of the
Gterm window. It is the pixmap that is rendered to the screen and so we
can implement 24-bit support by mapping the 8-bit XImage data to the 24-bit
pixmap when we pan/zoom or stretch the display contrast. Converting these
pixels is done using the colormap still present in the widget and set by
the user and the conversion is optimized with lookup-tables to minimize
computation time.
The static colors in the widget are unchanged and we are able to
fully utilize all 200+ colors available in the Gterm color model. Vector
graphics and "markers" in the widget were largely unchanged except for
cases where resource colors (e.g. the vector color in a plot) needed to be
specified explicitly.
This approach worked remarkably well in limiting the changes to the
Gterm widget itself and requiring (relatively) little in the way of changes
needed by applications such as XImtool or XGterm. A number of small issues
remain to be solved (and new ones will no-doubt be found) during the
beta-test period, but a fully-supported and stable system is clearly within
reach.
4.2 Athena Widget Changes
--------------------------
The Athena3D widget toolkit used also had problems under 24-bit
systems, mostly related to the definition of color resources. This toolkit
provides the 3-D effect for common widgets such as Buttons, Menus and
Toggles and changes were needed to allow these widgets to be used on
TrueColor visuals.
Other projects had encountered these same problems and patches for
the toolkit were easily found on the web and applied. The older version of
the library source was retained in the distribution for reference in case
future bugs are found.
One issue still to be investigated is the rendering of widgets on
8-bit pseudocolor displays, which on some systems appears to lose the 3-D
effect. This will be resolved during the "cleanup" phase and would only
affect a very small numbers of users.
--------------------------------------------------------------------------------
===========================================
5. CLIENT DISPLAY LIBRARY (CDL) REVISIONS
===========================================
5.1 Display Protocol Changes
-----------------------------
The following CDL methods were modified in order to implemented the
faster sub-raster I/O described below in section 5.1.2:
cdl_readSubRaster (cdl, lx, ly, nx, ny, &pix)
cdl_writeSubRaster (cdl, lx, ly, nx, ny, pix)
The changes made are internal to the procedure and do not affect the
application interface, only the behavior of the procedure.
Specfically, if the connection to the display server detects a WCS
version greater than "10" (i.e. v1.0), then a new method for writing
subraster data will be used that transfers data directly to the region
specified. This should greatly improve the performance of applications that
do many subraster transfers of this type and is fully backward compatible
to other display servers.
All that is required to use this feature is to relink the CDL
application with the new version of the library, and to use the XImtool
server distributed with X11iraf V2.0 or later.
--------------------------------------------------------------------------------
===================
6. TECHNICAL NOTES
===================
6.1 IIS Protocol Changes
-------------------------
The IIS protocol was modified slightly in this release in order
to provide greatly improved performance of sub-raster read and write oper-
ations from client applications. The change was made to accomodate a
Real-Time Display capability for a new IR Mosaic instrument recently
developed in which the display is loaded simultaneously by independent
clients responsible for different parts of the focal plane. The change
resulted in a 200-fold increase in speed allowing a 4k x 4k image to be
displayed from multiple machines in under a second.
The details of this change are covered in detail in section 5.1.2
below but will be automatic for any application linking against the new
version of the CDL library. In summary, earlier versions of the subraster
display were done by reading back the entire width of the frame buffer,
editing the affected pixels and then writing back the rows in the buffer.
For small sub-raster this is highly inefficient but usually acceptable
because of the small number of subraster reads/writes being done. In this
improved version, the pixels in the frame buffer are written directly to
the screen, avoiding the unnecessary readback-edit-write cycle as before.
When displaying a full image into a frame buffer approximately the same
size as the image, the change will not be noticeable. However, when the
image is much smaller than the buffer, or when writing many small
subrasters to the display (e.g tiling images or editing indivual regions),
users should notice a considerable improvement in the speed.
6.1.1 IIS Protocol Summary
---------------------------
This section is meant to provide an up-to-date reference of the IIS
protocol used in X11IRAF v2.0, including any changes described above or in
following sections. These changes are implemented in XImtool display
server, the VXImtool virtual frame buffer, and the CDL application library
included with this release. Necessary changes in the current IRAF v2.14
release are also implied.
IIS Header Packet Summary
TID Subunit Tct X Y Z T Data
+------------------+-------------+-----+---+---+----+---+--------+
Read Data | IIS_READ|PACKED | MEMORY | -NB | x | y | fr |nx | nbytes |
Write Data | IIS_WRITE|PACKED | MEMORY | -NB | x | y | fr |nx | nbytes |
Read Cursor | IIS_READ | IMCURSOR | - | - | - | wcs| - | - |
Write Cursor | IIS_WRITE | IMCURSOR | - | x | y | wcs| - | - |
Set Frame | IIS_WRITE | LUT|COMMAND | -1 | - | - | - | - | 2 |
Erase Frame | IIS_WRITE | fb | FEEDBACK | - | - | - | fr | - | - |
| | | | | | | | |
Old Read WCS | IIS_READ | WCS | - | - | - | fr | - | 320 |
Old Write WCS | IIS_WRITE|PACKED | WCS | -N | - | - | fr |fb | 320 |
| | | | | | | | |
WCS Version? | IIS_READ | WCS | - | 1 | 1 | - | - | 320 |
WCS by Num.? | IIS_READ | WCS | - | 1 | - | fr |wcs| 1024 |
New Read WCS | IIS_READ | WCS | - | 1 | - | fr | - | 1024 |
New Write WCS | IIS_WRITE|PACKED | WCS | -N | 1 | - | fr |fb | 1024 |
+------------------+-------------+-----+---+---+----+---+--------+
Where nbytes | NB = number of bytes expected or written
x = x position of operation in frame buffer coords
y = y position of operation in frame buffer coords
nx = width of data to be read/written. If zero, the width
of the current frame buffer is assumed.
fr = frame number (passed as bitflag (i.e. 1, 2 ,4 8, etc)
fb = frame buffer config number (zero indexed)
N = length of WCS string
wcs = WCS number (usually zero)
Data = the number of bytes of data to be read or written
following the header packet.
IIS_WRITE = 0400000
IIS_READ = 0100000
COMMAND = 0100000
PACKED = 0040000
IMC_SAMPLE = 0040000
MEMORY = 001
LUT = 002
FEEDBACK = 005
IMCURSOR = 020
WCS = 021
6.1.2 Faster Sub-Raster Writes
-------------------------------
Sub-raster I/O is a special case of the IIS_READ and IIS_WRITE
commands in which the caller specifies the (x,y) position of the operation
and the number of bytes to be transferred. Traditionally, the X position
was always zero (indicating the starting row of the frame buffer), the Y
position was the row to be written and the data sent represented one or
more complete rows of the frame buffer.
In the new scheme, we take advantage of the unused 't' register in
the IIS header packet to specify the width of the subraster. If this value
remains 0 (zero), we use the old behavior and assume the data are the full
width of the frame buffer. For values greater than zero in the 't'
register, the value is taken to be the width of the subraster to be written
at the given (x,y) position. The size of the subraster is then 't' pixels
wide by 'nbytes/t' rows high.
When using the cdl_readSubRaster() or cdl_writeSubRaster() methods
in the CDL application library, the setting of the 't' register is handled
automatically on behalf of the caller. This faster display model is used
only if the "iis_version" is greater than 10 meaning CDL applications
should remain backward compatible with the current (as of this writing)
DS9.
-------------------------------------------------------------------------------
7. POST-RELEASE NOTES
=====================