
CDL -- Client Display Library
=============================

	This directory contains the Client Display Library (CDL) sources.
The CDL is a  host interface for C or Fortran programs allowing them to
display images or overlay graphics to display servers such as XImtool or
SAOimage / SAOtng.  High-level procedures allow IRAF or FITS images to be
displayed simply, other routines permit access to all other server functions
(e.g. cursor and image readback, frame selection, etc).  The library also
features a number of functions for doing image overlay graphics; supported
graphics primitives include numerous point shapes, lines, circles, ellipses,
polygons, annular shapes, and text.

    This package is made up of several interfaces, specifically

	CDL	- high-level image display and graphics overlay
	IMD	- mid-level image display routines
	COMM	- server communications (currently IIS)

See the Notes file or Reference Guide in the doc subdirectory for more
information.
	Source the for library itself is in this directory.  Documentation
is in the 'doc' subdirectory and demonstration applications can be found in
the 'examples' subdirectory.  The 'test' subdirectory contains debugging
programs used during development; they're not really good examples of
programming practice but may serve as demos of how individual functions
can be called.


Documentation and Example Applications
--------------------------------------
	Documentation for the package is located in the 'doc' subdirectory
as both TROFF source and Postscript.  The reference manual covers each of
the routines available in the library and contains a summary of the interface
as well as code samples.  
	Working programs are also included in the 'examples' subdirectory. 
Users may find it easier to start by modifying these programs for a particular
need (e.g. add a new command for marking, an option for overlaying points
from a file, etc) before starting an application from scratch to become fam-
iliar with the library.
	Fortran programmers should consult the reference manual for information
on array passing in the CDL.  In particular, while the CDL can be used from
IMFORT programs special care needs to be taken when displaying arrays read
using the IMFORT routines.


Building the Package
--------------------
	The CDL package relies on the Imake facility to generate the make-
files needed to compile the package.  To build the CDL use the following
command:

	% xmkmf				# build the parent Makefile
	% make World			# compile it all

There is no supported "make install" option, all files will be left in the
CDL working directory following the World build.  Users of the package
must either build the library and install the lib and include files by hand
in their final destination, or use compiler "-I" and "-L" flags to find the
files when compiling clients.
	As an alternative for sites that don't have Imake installed or en-
counter problems you can try the generic makefiles provided.  To use these
simply do

	% configure			# create the makefiles
	% make World			# compile it all

	Programs using the CDL will need one of two include files: the
"cdl.h" file for C programs or the "cdlftn.inc" file for Fortran programs.
The C include file is required, the Fortran include file is optional and
just defines symbolic names for various constants.  Fortran programmers
not using the cdlftn.inc file should see to Reference Manual for values of
constants.  The library file to be linked is "libcdl.a", all programs using
the CDL must also link with the system math library.

****************************************************************************
*****  NOTE: Solaris users will also need to include "-lnsl -lsocket"  *****
*****  when linking programs to include the socket interfaces.         *****
****************************************************************************


Reporting Problems
------------------
	Each of the CDL functions has been tested individually but there is
no practical way to test how various combinations of routines may be used
in any given application so bugs are inevitable.  If you think you've found
a bug, have a suggestion for future enhancements, or just have a question
about how something works, contact

			iraf@noao.edu

Messages may also be posted to the adass.iraf.programming newsgroup so that
others may benefit from the exchange.  If you're not familiar with the ADASS
newsgroup hierarchy send a message 

		    irafinfo@iraf.noao.edu

with the one-line message "get iraf newsgroups" in the body of the message
for more information.  A small code sample demonstrating the problem would
help greatly in finding the solution.  Debugging output for the package may
be enabled by defining a unix CDL_DEBUG environment variable.  For example

	% setenv CDL_DEBUG	0		# minimal debug output
	% setenv CDL_DEBUG	1		# CDL and IMD debug info
	% setenv CDL_DEBUG	2		# print it all

Send this output along with the code sample.  An FAQ may be added later if
needed.


Mike Fitzpatrick
NOAO/IRAF Project
February 1997
