========================
ALE version 0.8.4 README
========================

This README discusses downloading, extraction, and compilation of ALE.
Documentation about the command-line interface and program options can be found
on the ALE web site; see the end of the README for relevant URLs.

Subsections:

	+ Windows Binaries
		- URLs
		- Extraction and Use
	+ Compiling from source
		- URLs
		- Build prerequisites
		- Extraction and Building
	+ Compilation options
		- ImageMagick Support
		- Color Data Precision
		- Coordinate Data Precision
		- FFTW Support
		- POSIX Support
		- IOCTL Support
		- Assertions
	+ Further Documentation
	+ URLs
	+ Mailing List


Windows Binaries
================


URLs
----

http://auricle.dyndns.org/ALE/download/ale-0_8_4-win32.zip


Extraction and Use
------------------

The zip file available at the above URL is an archive containing the ALE
executable; a zip archival utility can be used to extract the executable from
the archive.

Once extracted, since ALE is a command-line program, it may be necessary to
open a command prompt window to use ALE successfully.  For more information
about command-line usage and options, see the User Manual at the URL given at
the bottom of this file.

Note that the Windows binaries available on the ALE website read and write only
PPM-formatted image files.  However, separate conversion tools can be used to
convert between other formats and PPM (e.g. ImageMagick's command-line
utilities, available from http://www.imagemagick.org/ ).


Compiling from source
=====================


URLs
----

http://auricle.dyndns.org/ALE/download/ale-0.8.4.tar.gz


Build prerequisites
-------------------

GCC version 3.2.3 with C++ support and GNU Make 3.80 are known to build ALE
successfully.  Older versions of GCC may fail to compile some versions of ALE.


Extraction and Installation
---------------------------

Download the source archive file from the URL indicated above, and invoke:

	tar xzf ale-0.8.4.tar.gz
	cd ale-0.8.4
	make [OPTIONS]

where the text '[OPTIONS]' is replaced by zero or more of the compilation
options listed below.  (The makefile may need to be modified for successful
compilation on Windows systems.)


Compilation options
===================

All compilation options are of the form OPTION=VALUE.  Default options are
denoted by '*'.


ImageMagick Support
-------------------

Enabling ImageMagick support allows ALE to make use of the file-handling
capabilities of ImageMagick ( http://imagemagick.org/ ).  This includes reading
and writing a variety of file formats, including, among many others, PNG and
JPEG (two formats commonly used in web publishing) as well as common
interchange formats such as PPM and TIFF.  ImageMagick 6.0.6 is known to work
with this version of ALE; certain older versions of ImageMagick may cause
compile, link, or runtime errors.

IMAGEMAGICK=0 *        Disable ImageMagick support.
IMAGEMAGICK=1          Enable ImageMagick support.  


Color Data Precision
--------------------

ALE's internal data structures store each color channel within a pixel as
floating-point data; similarly, arithmetic operations on color channels are
performed in floating point.  The three available data-type configurations are
listed below, with typical data sizes indicated in parentheses.  Note that the
required runtime for COLORS=HALF configurations can be several times that of
COLORS=SINGLE configurations.

                       Storage                Arithmetic
                       -------------------    -------------------
COLORS=SINGLE *        C++ float  (32-bit)    C++ float  (32-bit)
COLORS=DOUBLE          C++ double (64-bit)    C++ double (64-bit)
COLORS=HALF            Custom     (16-bit)    C++ float  (32-bit)

Note: COLORS=HALF can be very computationally expensive.


Coordinate Data Precision
-------------------------

In general, coordinate transformations used by ALE produce results outside of
the set of integers; hence, coordinates are treated as floating-point data.
The two available data-type configurations are listed below, with typical data
sizes indicated in parentheses.

COORDINATES=SINGLE *   C++ float  (32-bit)
COORDINATES=DOUBLE     C++ double (64-bit)


FFTW Support
------------

For Irani-Peleg rendering, ALE computes a discrete Fourier transform of the
estimated point-spread function.  Since the area in which an estimated
point-spread function is non-zero is usually much smaller than the size of an
input frame, the efficiency of this operation is unlikely to be important.
Hence, ALE uses a relatively inefficient built-in transform by default.  To use
FFTW instead of the built-in transform, specify FFTW=1.  This option requires
FFTW version 3 libraries and header files to be installed.  For more details on
FFTW, see http://fftw.org/

This build option is required in order to use the --fl option.

FFTW=0 *               Use a built-in discrete Fourier transform.
FFTW=1                 Use the FFTW3 discrete Fourier transform.


POSIX Support
-------------

This build option is required in order to use the --wmx option.  If
POSIX=1 is specified, it is expected that fork() and execlp() calls
are available.

POSIX=0                Do not use POSIX fork() and execlp()
POSIX=1 *              Use POSIX fork() and execlp()


IOCTL Support
-------------

This build option is required to obtain additional output from --ui=tty.  If
TIOCGWINSZ is not defined in <sys/ioctl.h>, however, additional output will not
be provided even if IOCTL=1 is specified at build time.

IOCTL=0 *		Do not use ioctl()
IOCTL=1			Use ioctl()


Assertions
----------

Finding bugs within ALE, or within custom modifications to ALE, can be
simplified by enabling run-time assertions.  These checks enforce conditions
believed to be necessary or desirable for correct program operation.  If a
condition is not satisfied, ALE will abort and display a message indicating the
failed assertion.

DEBUG=0 *              Disable assertions.
DEBUG=1                Enable assertions.


Further Documentation
=====================

For information about command-line usage and program options, see the on-line
user manual, available at the URL indicated in the next section.  A technical
description of ALE operation is also available.  


URLs
====

Home Page		http://auricle.dyndns.org/ALE/
User Manual		http://auricle.dyndns.org/ALE/user/
Technical Description   http://auricle.dyndns.org/ALE/tech/
Mailing list archive	http://ventricle.dyndns.org/pipermail/ale/


Mailing List
============

Bug reports, feature requests, patch and release announcements, and related
discussion can be sent to ale@ventricle.dyndns.org.  Archives of past postings
and subscription information are available at the URLs indicated below.

Posting address		ale@ventricle.dyndns.org
Subscription info	http://ventricle.dyndns.org/cgi-bin/mailman/listinfo/ale
Archives		http://ventricle.dyndns.org/pipermail/ale/
