Chapter 8. The Programming Environment

This chapter describes the programming environment available on Silicon Graphics workstations. Special tools are also described that may help you in writing, compiling, and debugging your IL program.

This chapter contains the following major sections:

Compiling and Linking an IL Program

The following sections show you how to compile and link IL programs written in C++ and C.

Programs Written in C++

To compile an IL program, in this example, sample.c++, use the following command line:

# cc -g sample.c++ -o sample -lil 

By default, the *.so libraries are used to link your programs, however, you must link to the IL library itself.

In general, you should not link to the static, *.a, libraries unless you want to keep your application in one complete binary. If you do choose to use the static libraries, use the following command to compile your program:

# cc -g sample.c++ -o sample /usr/lib/libil.a  /usr/lib/libifl.a -lil     -lm -lGL -IX11

If you link to the static libraries, include the IL library, the GL shared library, the X Window library, the math library, and the C++ library.

A Sample Makefile

Example 8-1 shows a sample Makefile for compiling IL programs.

Example 8-1. Makefile for a C++ Program

# Makefile for IL test programs
SHELL = /bin/sh
# If you want to debug,turn on the “-g” option.
FLAGS = -g
MAINS= sample.c++
OBJS = ${FILES:.c++=.o}
PROGS = ${MAINS:.c++=}
LIBS = -lil
        CC $(FLAGS) $< -o $@ $(LIBS)
        CC $(FLAGS) -c $<
        rm -rf $(OBJS) $(PROGS)
        rm -rf core

Programs Written in C

Link your C program to the library, the C version of the IL. For example, to compile a C program called ctest.c, use this line:

# cc -g ctest.c -o carprot -lcil 

IL is compatible with ANSI C. To use the older, pre-ANSI dialect, add –cckr to the command line. Ignore any warnings generated during compilation.

Refer to the C reference page for more information about the C compilers.

A Sample Makefile

Example 8-2 shows a sample Makefile for compiling IL programs written in C.

Example 8-2. Makefile for a C Program

# A very simple Makefile for IL test programs
SHELL = /bin/sh
FLAGS = -g 
CMAINS = csample.c
COBJS = ${CMAINS:.c=.o}
CLIBS = -lcil 
    cc $(FLAGS) $< -o $@ $(CLIBS)
    rm -rf $(COBJS) 
    rm -rf core
clobber: clean
    rm $(CPROGS)

Reading the Reference Pages

IL reference pages look atypical because they are class reference pages. They are available online by typing the following on the command line:

# man -d ClassName 

ClassName is the name of the IL or IFL class that you want to read about.

A printed version of the reference pages is available as an option; see the Introduction for ordering information.

The C++ and C versions of the class reference pages share a similar format. The following list describes the main sections of each reference page:


The class name and a one-line description of the class.

Inherits From  

A colon-separated list of superclasses, beginning with the base class.

Header File 

The class's header file.

Class Description 

Describes how the class fits into the IL and how to use it. This section briefly mentions the most important functions associated with the class. The C++ version also contains information about deriving from the class, if appropriate.

Class Member Function Summary 

Lists the prototypes of the functions associated with the class. They are grouped functionally with headings that indicate the general task they perform. Functions that are protected are identified as such. This section should be a synopsis of the class.

Function Descriptions 

Describes what each function does and what its arguments mean. Sometimes code examples are included. This section is arranged alphabetically so that you can easily find the description of a particular function of interest.

Inherited Member Functions 

Contains an alphabetical list of the functions inherited from superclasses.

See Also 

Lists other reference pages of interest.

Notes (optional) 

Contains special information about the class.

Image Tools

IL provides several useful utilities for displaying, copying, and manipulating images. Since these image tools are based on IL, they support TIFF, SGI, PCD (Photo CD), PCDO, TCL, PNG, GIF, and FIT file formats. These tools are installed in /usr/sbin and most of them are documented in the IRIS Utilities User's Guide. (They also have reference pages.)


Image Copy copies a specified region of an input image file to an output image file. It can also be used to convert between IL-supported file formats. See the imgcopy reference page.


Image Info reports image information such as size, data type, color model, and file format for any IL-supported file format. See the imginfo reference page.


Image View allows you to display and manipulate any combination of IL-supported image files. Images can be roamed, dragged, cropped, or wiped separately or simultaneously. See the imgview reference page.


Image Formats lists all the IL-compatible formats currently installed.

Online Source Code

To provide you with source code examples, IL installs several directories in /usr/share/scr/il. They are as follows:

  • guide contains the whole-program examples presented in this guide. They are provided so that you can compile and run them as you read the relevant discussion in the guide.

  • apps contains sample IL applications, such as imgcopy and imgview. These applications serve as examples of how to program with the IL and serve as possible templates for developing new applications.

  • src contains IL source code that may use to derive your own classes. The directory includes the source for several operators, including the ilViewer class. The corresponding header files are in /usr/include/il or /usr/include/ifl.

  • tutorial contains a series of programs that build on one another. The first in the series (ex0.c++) simply opens and displays an IL image file. The other programs use various operators and display techniques.

You can examine the README files in the various directories for more information on each of the code examples. Also, each of the directories containing complete programs has an appropriate Makefile. To compile any of the programs, type:

# make program_name

where program_name is the name of the file minus its .c++ suffix.

Environment Variables

You use environment variables to configure the global IL environment. Environment variables configure such things as the file format, multi-processing, graphics hardware acceleration, caching capabilities, and monitoring functions.

Table 8-1 provides a brief description of the environment variables with their default values.

Table 8-1. Environment Variable Definitions

Environment Variable

Definition and Default Value


Specifies the file location where the IFL-supported image file formats are defined; default is ifl/src/ifl_database.


Specifies the maximum number of threads that can share a multi-processing arena; default is 40.


Specifies the amount of user memory reserved for the cache; default is .3 (30%).


Specifies the size of the cache; default is


Specifies the number of threads generated; default is the number of processors in the system.


Specifies the debug level; default is 0.


Specifies whether or not hardware is used to accelerate image processing; default is all enabled.


Specifies the X display used by IL to obtain a display connection which is then passed to XOpenDisplay().


Overrides the return value of glGetString(GL_RENDERER) which forces IL to treat the display as a different type of renderer.


Specifies whether or not all monitors are on; default is off. Monitors print messages when specific events occur.


Specifies whether or not a log entry is generated when the cache is used; default is off.


Specifies whether or not a log entry is generated when the cache is compacted; default is off.


Specifies whether or not a log entry is generated when an operator resets; default is off.


Specifies whether or not a log entry is generated each time a lock is created or destroyed; default is off.


Specifies the size of the arena; default is
2 Mb.


Specifies whether or not concurrent access to IL data structures is allowed for threads; default is on.


Specifies how many pbuffers to try to allocate; default is 1. IL tries to get as many as can up to this value.


Specifies the number of read threads used per processor to handle disk I/O; default is one.

The following sections describe the uses of some of the environment variables.

Caching Configuration Issues

You can use the environment variable IL_CACHE_FRACTION to specify the size of the IL image data cache. The default size is 30% of available user memory. For example, you could set the cache size to 20% of available user memory by issuing the following command prior to running an IL-based application:


Alternatively, you can use the environment variable IL_CACHE_SIZE to set the size of the cache in bytes. For example, you could set the cache size to 4 million bytes by issuing the following command prior to running an IL-based application:

% setenv IL_CACHE_SIZE 4000000

The IL_CACHE_SIZE variable takes precedence over IL_CACHE_FRACTION if both are set.

Hardware-Acceleration Configuration Issues

You can use the environment variable IL_HW_ACCELERATE to override the default behavior of using the graphics hardware to perform processing whenever possible. For example, you can disable the hardware acceleration feature of IL by issuing the following command prior to running an IL based application:


You might turn off hardware acceleration when debugging operators that are accelerated by the hardware.

Hardware Display Configuration Issues

When you open a display using IL, you first use the X call, XOpenDisplay(), to return a pointer to the display device. The return value is then passed into ilDisplay to open a window to display an image. You can use IL_HW_DISPLAY to set the value of the display which the return value of XOpenDisplay() points to.

The rendering machine returned by glGetString(GL_RENDERER) is generally the machine you are using. You can override the value returned by glGetString(), however, by setting the IL_HW_RENDERER value. For example, you might be running on an InfiniteReality but want to see what the display would be like on an Impact. In this case, you would set IL_HW_RENDERER to Impact.

Caution: Make sure your machine supports the platform you are setting IL_HW_RENDERER to.

Monitoring Control Issues

You can use the IL_MONITOR environment variable to turn on the IL Monitor. The IL Monitor logs an entry wherever one of the following events occurs:

  • The cache is used.

  • The cache is compacted.

  • An operator is reset.

  • A lock is either created or destroyed.

If you want a less-complete level of monitoring is needed, or you need to capture a log of the operations, you can use any combination of the following environment variables:





If you set IL_MONITOR_CACHE to 1, a log entry is generated each time the cache is used, for example:

Page (0,0,0,0) loading in File(0x1000a858)
Page (0,32,0,0) loading in File(0x1000a858)
Page (253,29,0,0) loading in Nop(0x100c8108)

If you set IL_MONITOR_COMPACTION to 1, a log entry is generated each time the cache is compacted, for example:

Compaction reclaimed 144K.
Compaction reclaimed 0K.
Compaction reclaimed 160K.
Compaction reclaimed 144K.
Compaction reclaimed 0K.
Compaction reclaimed 64K.
Compaction reclaimed 176K.
Compaction reclaimed 0K.
Compaction reclaimed 0K.

If you set IL_MONITOR_RESET to 1, a log entry is generated each time an operator is reset, for example:

(brandt@chaos:tests) convrz
File(0x1000a858) initialized
Convolve(0x1000db98) initialized
Rotate/Zoom(0x1000e1a0) initialized
X Window(0x100813f0) initialized
PBuffer(0x10099668) initialized
X Window(0x100ad9a8) initialized
X Window(0x100ad9a8) altered
View(0x100a3218) initialized
X Window(0x100ad9a8) altered
OpenGL Hardware Pass(0x100c1088) initialized
OpenGL Hardware Pass(0x100c1870) initialized
OpenGL Hardware Pass(0x100c1870) altered
Pixel Cache(0x100c2058) initialized

If you set IL_MONITOR_LOCKS to 1, a log of lock creations and destructions is generated. Additionally, at program exit, any remaining locks are displayed. For locks that are created, a short message is printed with the name of the lock. The name consists of the address of the lock optionally followed by a parenthetical comment describing what the lock is used for, for example:

Created lock 4001fa0 (ilMpNode cache)
Created lock 4002070 (ilMpParkedGroup cache)
Created lock 4002140 (ilMpPool cache)
Created lock 4002210 (ilLink mutex)
Created lock 40022e0 (ilImage evalLock)
Created lock 40023b0 (ilLink mutex)

For the destruction of locks as they exit, the name of the lock and its metering information are displayed. The metering information measures such things as how many attempts were made to acquire the lock, how many of those attempts were successful, and how many times the software was forced to start spinning on the lock.

Multi-Threading Configuration Issues

You can use the environment variables IL_COMPUTE_THREADS and IL_READ_THREADS to specify the number of compute threads and file read threads used by each processor. By default, one compute thread is created for each processor on the host system (including the user's thread), and one read thread is created to perform disk I/O in the background. For example, you can disable all multi-processing features in IL by issuing the following commands prior to running an IL-based application:

% setenv IL_READ_THREADS 0

You can set the size of the arena used to allocate spin-locks and semaphores for multi-processing control with the IL_MP_ARENA_SIZE variable. You might set this variable if, for example, you create a large number of objects derived from ilLink.

By default, IL allows up to forty threads to share multi-processing arenas. If you need more, you can set the IL_ARENA_MAXUSERS environment variable to a larger value.