Introduction to the XIL Imaging Library

The Solaris XIL Imaging Library provides a basic set of functions for imaging and video applications. The XIL library is the imaging component of the Solaris Graphics Architecture, a strategy for providing low-level software interfaces known as foundation libraries. Application and API developers can port their code to such foundation libraries. The XIL library is complemented by the OpenGL Graphics Library, which addresses application and API requirements for geometry-based graphics, and the Kodak Color Management System (KCMS^(TM)) library, which enables device color management.

Solaris Graphics Architecture

The XIL foundation library is an integral part of the Solaris Graphics Architecture. The Solaris software, using loadable drivers, enables display devices using the Solaris Graphics Architecture to be easily installed and used, without requiring kernel modifications. The Solaris Graphics Architecture, through the XIL, OpenGL, KCMS, and X11 software, provides a means for third-party hardware and software vendors to develop applications with the knowledge that their investment will see long-term benefits, including access to a range of computing platforms and complete integration into the Solaris environment.

---

Note - Currently, the compression GPI interfaces to the XIL library discussed in this book are not binary committed. Due to the evolving nature of the C++ language, these interfaces may change in ways that may require you to change your code and recompile in a later Solaris release. However, the compute, I/O, and storage GPI interfaces are now committed, which means that we will maintain source-code compatibility. The API continues to be committed for binary compatibility.

---

Division of Function in the XIL Library

The XIL architecture consists of a high-level application programming interface (API), device-independent core code (including the XIL API and GPI layers), which manages the loading and calling of specific device-dependent functions, a graphic porting interface (GPI), which separates device-independent and device-dependent code, and the device-dependent (DD) algorithm implementation. Figure 1-1 illustrates this division of function and shows how these sections relate:

Figure 1-1

This document describes the XIL core (including the XIL API and GPI layers), the GPI, and the method needed to supply alternative DD code. In general, porting new hardware to the XIL environment involves providing new implementations of DD modules. The GPI is the interface through which the DD modules are called and is responsible for allowing the creation of new DD implementations without requiring exposure of XIL library source code.

XIL API Layer

The API layer in the XIL library contains the C wrappers on the C++ device-independent classes. It consists of functions that can be categorized in the following way:

• Create and destroy objects
• Set and get object attributes
• Modify image data
• Extract information from an image
• Modify data in non-image objects
• Synchronize operations

The semantics of the functions exposed in the API are described in the XIL Programmer's Guide and the XIL Reference Manual.

The C++ device-independent classes are used to implement the API functions described above. These classes provide a device-independent interface to the XIL library imaging functionality and are primarily used to pass information through the GPI to the DD modules. Table 1-1 briefly summarizes these classes and presents them alphabetically as base classes or API-level classes. For additional information on each class, see "XIL Base Classes" on page 23, and "XIL API Level Classes" on page 24.

Table 1-1

Class Name	Description
XIL Base Classes
XilGlobalState	Contains a list of system states and the tree of atomic/molecular operations and their corresponding function pointers
XilObject	Is the parent class for all XIL API classes
XilSystemState XIL API Level Classes	Contains the creation methods for all API classes
XilCis	Contains the compressed image data and compression functions
XilColorspace	Contains information to specify a color space
XilColorspaceList	Contains information for specifying a list of color spaces
XilDevice	Contains multiple device attributes
XilDitherMask	Contains dither matrices for ordered dithering
XilError	Contains information for reporting errors
XilHistogram	Contains image histogram information
XilImage	Contains the basic data elements for XIL functions
XilImageFormat	Contains an image description without data
XilInterpolationTable	Contains an array of 1 x n kernels that represent the interpolation filter in either the horizontal or vertical direction

Table 1-1 (Continued)

Class Name	Description
XilKernel	Contains kernel data used in convolution, error diffusion, paint, and band combine
XilLookup	Contains data for image conversion and colormap use
XilRoi	Contains region of interest information for an image
XilSel	Contains a structuring element used in erosion and dilation
XilStorage	Contains storage format information for an image

XIL Base Classes

The XilGlobalState Class

One instance of XilGlobalState exists for each heavyweight XIL process.

This class is responsible for loading DD code as needed by the application. This class contains a table that converts operation numbers to operation names and vice versa.

The XilGlobalState class is defined in the _XilGlobalState.hh header file.

The XilObject Class

XilObject is the base class from which all API level XIL objects are derived. It is the parent of the XilDeferrableObject and XilNonDeferrableObject classes from which the API level XIL objects are directly derived.

The XilObject class contains all the attributes and functions that are generic to the exposed objects. It is an abstract class; no instance of this class is ever created.

Each API level object has a 64-bit object number and version number. The combination of these two numbers indicates a unique version of the same object and can be returned for any XilObject derived class using the member function getVersion(). A copy of an object returns the same version number.

When API-level objects are modified, their version number is changed. Use of object versions allows intelligent caching of API objects within the implementation.

This XilObject class is defined in the _XilObject.hh header file.

The XilDeferrableObject Class The XilDeferrableObject class is used to derive those objects that may be deferred, such as the XilImage and the XilCis. These objects have common characteristics of the deferrable execution information. For more information on deferral of objects, see "Deferred Execution" on page 30.

The XilNonDeferrableObject Class The XilNonDeferrableObject class contains all those objects that are not deferrable such as the XilRoi, XilLookup, XilHistogram, and so forth.

The XilSystemState Class

The XilSystemState class contains the common information for an individual XIL session initiated via xil_open(). This class can be used to create objects. All objects have a reference to the system state that created them. The system state is also used to generate errors via macros defined in its header file.

The XilSystemState class is defined in the _XilSystemState.hh header file.

XIL API Level Classes

The sections below describe the API level classes. As stated in "The XilObject Class" on page 23, XilObject is the base class for all the API level classes. You cannot instantiate an object from these classes; instead, you must get a copy of or a reference (pointer) to the object. If you get a copy, you are responsible for freeing the allocated data.

The XilCis Class

The XilCis (for compressed image sequence) class is the primary object for compression in the XIL library. It contains member functions to allow access to and movement through compressed data. The XilCis is created by loading a specified compressor.

The XilCis class is defined in the _XilCis.hh header file.

The XilColorspace Class

XilColorspace describes a color space of an image in such a way that images may be transformed from one color space to another. The XIL Imaging Library supports ten named color spaces. XilColorspace may contain a KCMS profile which is used by xil_color_correct(), not by xil_color_convert().

Each of the named color spaces is identified as an XilColorspaceOpCode. XilColorspaceOpCode is an enumeration type with the values shown below:

• XIL_CS_RGBLINEAR
• XIL_CS_RGB709
• XIL_CS_PHOTOYCC
• XIL_CS_YCC601
• XIL_CS_YCC709
• XIL_CS_YLINEAR
• XIL_CS_Y601
• XIL_CS_Y709
• XIL_CS_CMY
• XIL_CS_CMYK

The XilColorspace class is defined in the _XilColorspace.hh header file.

The XilColorspaceList Class

The XilColorspaceList class contains information for specifying a list of color spaces.

The XilColorspaceList class is defined in the _XilColorspaceList.hh header file.

The XilDevice Class

The XilDevice class describes the attribute/value pairs of a device. The member functions of this class enable you to access and set a device's attributes.

An XilDevice object can be used to set multiple device attributes simultaneously. This is important when device images are created and when the setting of device attributes incurs substantial overhead.

When you use this object to create a device, you should set only attributes the device understands. If the device does not recognize an attribute that you have set through the XilDevice object, an error is generated. You should set default values for a device's attributes based on the list of attribute/value pairs returned by the XilDevice object.

The XilDevice class is defined in the _XilDevice.hh header file.

The XilDitherMask Class

In the simplest case, the dither mask is a two-dimensional array of values that determines how the noise added during the dither process is spread across the image. In the XIL library, the dither mask can have multiple bands, each band with its own matrix. This allows noise to be spread differently for each channel of a true-color image, which can enhance the result of the dither operation. For dithering of multiband images, the number of bands in the dither mask matches the number of bands in the source image.

The XilDitherMask class is defined in the _XilDitherMask.hh header file.

The XilError Class

The XilError class describes errors in the XIL library. Its member functions allow programs to get information about the error, to retrieve the object that is associated with the error, and to control the error handling routines.

The XilError class is defined in the _XilError.hh header file.

The XilHistogram Class

The XilHistogram class describes a multidimensional histogram. This object can be used to gather statistical information on images.

The XilHistogram class is defined in the _XilHistogram.hh header file.

The XilImage Class

Derived from the XilImageFormat class, XilImage represents an image along with its associated data. The XilImage class contains member functions that make up the XIL image functions. It also contains member functions for storage and retrieval of image attributes.

The XilImage class is defined in the _XilImage.hh header file.

The XilImageFormat Class

The XilImageFormat class carries information about an image, independent of its associated pixel values.

---

Note - This class is equivalent to the API class XilImageType.

---

XilImageFormat is used at the API level to return information about the kind of image the application should create to act as a destination from a decompression or device capture, or as a source to a compression or device display. It is subclassed by the XIL library to create the XilImage class. There is an API function that creates an image directly from an XilImageFormat object.

The XilImageFormat class is defined in the _XilImageFormat.hh header file.

The XilInterpolationTable Class

The XilInterpolationTable class supports general interpolation. See the XIL Programmer's Guide for a discussion about general interpolation. This class describes an array of 1 x n kernels. The array represents the interpolation filter in either the horizontal or vertical direction. The member functions of this class enable you to access the data in an XilInterpolationTable object.

The XilInterpolationTable class is defined in the _XilInterpolationTable.hh header file.

The XilKernel Class

The XilKernel class represents a two-dimensional array of floating point values. XilKernel objects are used as parameters in functions like image convolution and error diffusion.

The XilKernel class is defined in the _XilKernel.hh header file.

The XilLookup Class

The XilLookup class describes data that is used to interpret image data. XilLookup is defined in the _XilLookup.hh header file.

Three classes are derived from XilLookup. Table 1-2 lists these classes and the header files in which they are defined.

Table 1-2 XilLookup

Class Name	Header File
XilLookupColorCube	_XilLookupColorcube.hh
XilLookupCombined	_XilLookupCombined.hh
XilLookupSingle	_XilLookupSingle.hh

The XilRoi Class

XilRoi describes an arbitrary region of interest (ROI). Member functions exist to manipulate and logically combine XIL ROIs.

A ROI has three internal representations:

• A list of rectangles (set and get as rectangles by the user)
• A bitmask (set as an image by the user)
• A list of convex regions (accessible by the core and GPI only)

Translation between types is done as needed and stored in the ROI until invalidated by subsequent changes to the ROI.

The XilRoi class is defined in the _XilRoi.hh header file.

The XilSel Class

The XilSel class describes a structuring element, which is a two-dimensional description of a pixel neighborhood. In the XIL library, the structuring element is described with a two-dimensional boolean (integer) array, with pixels in a neighborhood having true values in the array, and pixels excluded from the neighborhood having false values. Structuring elements are currently used as parameters to the xil_erode() and xil_dilate() functions.

The XilSel class is defined in the _XilSel.hh header file.

The XilStorage Class

The XilStorage class describes a contiguous region of memory associated with a given image. At construction, an XilStorage object contains no information but is filled in by subsequent calls. For improved performance and to ensure that an XilStorage object is destroyed automatically when no longer needed, an XilStorage object should be constructed on the stack.You fill in XilStorage objects by calling the XilDeferrableObject::getStorage() and XilImage::getStorage() methods for the appropriate images.

XIL Core Layer

The Core layer in the XIL library manages the dynamic loading of device handlers, deferred execution, and operation scheduling.

Deferred Execution

The primary problem in achieving adequate performance in an imaging library comes from the way in which the units (or atoms) of functionality are arbitrarily combined to perform useful work. The typical imaging case is much more general than, for example, OpenGL with its well-defined processing pipeline. This has tended to limit the usefulness of general imaging libraries, since any reasonable division of imaging functionality into atoms renders the performance of many applications substandard. The result is that useful libraries tend to be closely tailored to applications and vertical markets.

The use of multiple passes of atoms impedes performance in at least three ways:

• Multiple passes through an image cause the entire image to be paged into memory multiple times. Since in many cases the images are large compared with available physical memory, and the application is often working with multiple images simultaneously, this significantly impairs performance. Often a pixel operation can be performed in a single CPU clock cycle, so the time spent getting to the data far outweighs the time needed for the operation. Imaging is often a worst case of I/O bound processing.
• Many combinations of atoms can be performed in a single logical step with little penalty. For example, in the case of a rotation followed by a zoom, the backward-mapped algorithms often used to perform the rotation can perform both operations in nearly the same time as the rotation alone.
• The application must often create temporary images to hold intermediate results. Such intermediate images are not needed in customized code and may be avoided if the operations can be combined.

The XIL Library Method

There are several methods that can address these problems. In the XIL library, we have chosen to implement deferred execution and multiple atomic operation replacement. The goal is to identify and replace a sequence of atomic operations with a functionally equivalent single operation (a molecule). In this approach, the core-layer code keeps track of image dependencies and causes the operations to occur as late as possible. This enables significant performance improvements as described below.

In the library, atomic functions are, by default, deferred as long as possible. To implement this, the API level function creates an instance of the XilOp class (described in "The XilOp Class" on page 39), adds the API parameters to the XilOp, and then places the operation on a tree-like structure that holds deferred operation information. void is then returned to the calling routine (the C binding in this case).

The deferred execution data is stored as a directed acyclic graph (DAG), where the nodes are the instances of the XilOp class described above. The fact that a destination function depends on its sources is stored, along with the operation and parameters necessary to produce the destination image once the sources are produced. As image results are needed, the parts of the graph that hold that information are evaluated. Their dependent images are generated by performing the operations that have been stored.

Several actions can cause the evaluation of a subgraph:

• A request for results by the application--either from an I/O image or through storage acquisition
• A call to xil_state_set_synchronize()which modifies all images in the library to run synchronously
• A call to xil_set_synchronize()that turns on synchronization for an image

The DAG is disassembled upon a call to xil_close().

Graph Evaluation and Molecules

When the graph is evaluated, each node's op (the operation used to produce the node's destination image) is available and could be used to index into a list of function pointers. In fact, the library does something a little more general than this, and thus gains the ability to accelerate combined operations.

The XIL library stores its function table as an array of trees, each tree having one of the atomic functions as its base. Branches exist from the base node describing each composite operation (molecule) that exists. This structure is built from the description of the contents of each compute device handler. As the core code looks at the DAG, it attempts to match the longest sequence of atoms in the DAG to the function table. If the needed molecule is available, it is called; otherwise, the sequence of functions is checked again, leaving off the last function, which is performed atomically.

Each node on the function tree is a list of possible functions, usually using different compute devices. The core code calls the highest priority function, which is assumed to be the optimal (accelerated) one. The accelerated function is allowed to fail gracefully, in which case the second function in the list is called. Typically, the last function in the list is the unaccelerated memory port, which is guaranteed to work for all cases. This construction allows an IHV to accelerate a function for only a subset of the input parameters. For example, the code supporting an accelerator that only scales images up can fail gracefully (and cause the memory function to be called) if the scale factors it pulls off the DAG are less than unity. The mechanism for inserting a function into the table is described later in this document (see "Registering Operations With the XIL Library" on page 73).

The core code does not require porting.

When porting devices, you can accelerate either atomic functions or molecules. You can create molecules from any combination of atomic functions; however, you cannot add new atomic functionality to the library.

Some Considerations

The time needed to determine the sequence of operations from the DAG and choose the appropriate function from the table is trivial compared to typical image operations.

Not all operations can be deferred. An example of this is the xil_extrema() function, which supplies the maximum and minimum image values. The library makes no effort to hide the values returned in an opaque structure, the contents of which could be deferred. Thus, the use of xil_extrema() causes an evaluation of the source image. In general, only the functions that have as their destination an XilDeferrable object such as XilImage or XilCis object (or create those objects) can be deferred. The complete list of the rules for deferred execution is as follows:

1. Functions that return information based on values in the current image cannot be deferred. These functions are:

• xil_choose_colormap()
• xil_extrema()
• xil_histogram()
• xil_lookup_convert()
• xil_squeeze_range()

2. Functions that have nonstandard ROI, origin, or size behavior cannot be deferred. These functions are listed below:

---

Note - The xil_scale() and xil_transpose() functions may be deferred under special circumstances. See the XIL Programmer's Guide.

---

• xil_affine()
• xil_paint()
• xil_rotate()
• xil_scale()
• xil_subsample_adaptive()
• xil_subsample_binary_to_gray()
• xil_tablewarp()
• xil_tablewarp_horizontal()
• xil_tablewarp_vertical()
• xil_translate()
• xil_transpose()

3. General rules that apply to the other XIL functions are as follows:

---

Note - The xil_copy_pattern() function is exempt from general rules b and c below.

---

a. The source and destination images must have the same ROI.

b. The source and destination images must have the same origins.

c. The source and destination images must have the same width (xsize) and height (ysize).

d. The source images cannot have the same parent as the destination image.

We do not envision a large number of molecules in a typical release. In particular, display(zoom(decompress())) molecules have proven to be advantageous. Other display pipelines (display(zoom()), display(dither(zoom())), etc.) will prove useful. It is expected, however, for a third party to add molecules that particularly benefit its vertical market, without requiring that other software running on the XIL library be modified.

One goal of deferred execution is that the application need never know when functions are actually performed. Asynchronous error reporting allows this to be the case in general. However, some cases are impossible to hide. Consider

the case of a frame grabber used as a source to an operation that is done in response to an external signal. In normal operation, the actual grab would be postponed until the dependency tree was evaluated, possibly several steps further in the program. A possible resolution to this is to make the destination of the grab operation synchronized. This causes the grab to occur when the function call is made, but precludes any optimization of the grab function. In the end, the application must choose whether the operation should be deferred or not, and when the synchronization should occur. With the general rule "no optimization through synchronization," the application writer can judge an appropriate place to synchronize.

Molecules must behave semantically like the sequence of atomic operations, and produce the same (or nearly the same) results as calling the individual atomic functions. A molecule cannot have a greater precision than the atomic functions that the molecule contains. For example, a molecule of two XIL_BYTE convolutions cannot use floating point between the convolutions. It must clamp the intermediate results to XIL_BYTE images. An alternative molecule would be:

cast;8->f,convolve;f,convolve;f,cast,f->8

See Appendix B, "XIL Atomic Functions, " for information on the syntax of atomic functions.

Unusual Effects of Deferred Execution

One effect of deferred execution is that in some cases source code may not accurately reflect the actual operations done. Consider the following case, where im2 is not set to be synchronous.

for (i=0; i<N; i++) { a[0] = i; xil_add_const(im1, a, im2); } xil_copy(im2, display_image);

In the XIL library, only one add (the last one) is done as a result of this code, since the earlier results are obscured by the later ones. If the final copy were not called, no evaluation of the add would take place at all. In normal code, such cases rarely arise, but one must be careful in benchmarking the library. This is not unlike the situation that occurs with optimizing compilers.

Consider another case where only the final decompress is executed.

while (xil_cis_has_frame(cis)) { xil_decompress(cis,im2); } xil_copy(im2,display_image);

Each call to xil_decompress() schedules a frame from cis to be decompressed into image im2. This destination image is not used until the decompress loop is exited. The last decompressed frame is copied to a display image; this is the only operation that is evaluated.

XIL GPI Layer

The GPI layer is the interface for device-dependent code. In general, porting a device to the XIL library requires subclassing one or more of the base device classes defined below, and then configuring the resulting object files so that they can be loaded at run-time by the library. In addition to enabling third parties to port hardware, the functions and device access in the standard XIL release are provided through this interface as well.

Table 1-3 lists the classes that are defined in the GPI layer.

Table 1-3

Class Name	Definition
GPI LAYER DEVICE CLASSES
XilDeviceManager	Is the base class for the device type object
XilDeviceManagerIO	Is the abstract class for I/O devices
XilDeviceIO	Is the device-specific base class for I/O
XilDeviceManagerCompute	Is the abstract class for compute devices
XilDeviceManagerCompression	Is the abstract class for compression devices
XilDeviceCompression	Is the device-specific class for compression devices
XilDeviceManagerStorage	Is the abstract class for storage devices

Table 1-3 (Continued)

Class Name	Definition
XilDeviceStorage GPI LAYER SUPPORTING CLASSES	Is the device-specific base class for storage
XilBox	Represents the area to be processed
XilBoxList	Represents a list of destination areas and their corresponding source area
XilCondVar	Contains wrappers for conditional variables
XilConvexRegionList	Contains information for representing a list of convex regions.
XilFunctionInfo	Holds the information for a device to describe a function to the XIL library
XilMutex	Contains wrappers for mutex locks
XilOp	Holds the information required to store the operation on the DAG
XilRectList	Contains information for generating a rectangular list
XilScanlineList	Contains information representing a scanline list
XilTile	Contains the information representing a tile
XilTileList	Contains a list of tiles

GPI Layer Device Classes

The XIL library has the concept of devices--software and hardware--which are represented by the device handler modules. More than one instance of a device may be created. In this case, information that is common to all instances of a device should be held in the XilDeviceManager class.

The XilDeviceManager Class

XilDeviceManager is an abstract class, containing the general information needed at this level.

The XilDeviceManager class is defined in the _XilDeviceManager.hh header file.

XilDeviceManager SubClasses The XIL library subclasses XilDeviceManager for each kind of device that is supported. Devices combine with the appropriate XilDeviceManager subclasses to implement all pipelines. Table 1-4 lists the subclass for each device type and the header file in which each is defined.

Table 1-4 XilDeviceManager

Subclass	Header File
XilDeviceManagerIO	_XilDeviceManagerIO.hh
XilDeviceManagerCompute	_XilDeviceManagerCompute.hh
XilDeviceManagerCompression	_XilDeviceManagerCompression.hh
XilDeviceManagerStorage	_XilDeviceManagerStorage.hh

Device-Specific Base Classes Table 1-5 lists the device-specific base class for each device type and the header file in which each is defined.

Table 1-5

Device-Specific Class	Header File
XilDeviceIO	_XilDeviceIO.hh
XilDeviceCompression	_XilDeviceCompression.hh
XilDeviceStorage	_XilDeviceStorage.hh

GPI Layer Supporting Classes

The XilBox Class

The XilBox class holds all the information needed to represent the area of an image that is to be processed.

The class contains member functions to retrieve the coordinates of an image area from the box, however most routines will simply pass an XIL box on as arguments to other functions.

The XilBox class is defined in the _XilBox.hh header file.

The XilBoxList Class

The XilBoxList class holds all the information needed to represent a destination area and its corresponding source areas for processing.

The class contains member functions to retrieve all the boxes from the list, one set at a time, until all boxes are processed.

The XilBoxList class is defined in the _XilBoxList.hh header file.

The XilCondVar Class

The XilCondVar class provides support for thread control within a compute routine.

The XilCondVar class is defined in the _XilCondVar.hh header file.

The XilConvexRegionList Class

The XilConvexRegionList class contains information for representing a list of convex regions when backward mapping from a destination image to a source image generates non-rectangular regions (such as in an affine operation). For more information on convex regions, see the subsection entitled "Affine" on page 112 in "Geometric Operations."

The XilConvexRegionList class is defined in the _XilConvexRetion.hh header file.

The XilFunctionInfo Class

The XilFunctionInfo class contains member functions that store the descriptions of device function capabilities. It is set when adding a function via addFunction().

The XilFunctionInfo class is defined in the _XilFunctionInfo.hh header file.

---

Note - It is recommended that device providers use the xilcompdest.pl script, which takes care of describing functions to the XIL library. For more information, see "Registering Operations With the XIL Library" on page 73.

---

The XilMutex Class

The XilMutex class provides support for thread locking within a compute routine.

The XilMutex class is defined in the_XilMutex.hh header file.

The XilOp Class

The XilOp class contains all the information representing a specific XIL operation. The class contains all the information to define a particular imaging function including but not limited to:

• Operations such as ROI manipulation
• Backward mapping from a destination point to a point in the source
• Whether an operation can be forward mapped
• Forward mapping from a point in the source to a point in the destination
• A pointer to a list of other operations if this operation is part of a sequence

The XilOp class describes an operation completely. Any deviation from what is described for an operation in an XilOp class is, by definition, a distinct op.

Atomic operations may have up to three source images and one destination image. However, the interface is generalized to support more diverse atomic operations. You can extract the source and destination images or CISs as well as the other parameters of an XIL operation--all of which are stored in an XilOp object--by using XilOp member functions. See Appendix A, "XilOp Object," for a list of all the source and destination images and parameters for each XIL operation and an description of how to use XilOp member functions to extract this information from an XilOp object.

A molecule is a chain of atomic operations. For a molecule, you must follow the chain properly to extract in a logical order the parameters and images from the XilOp object. The op passed to the routine is the op associated with the

last operation in the chain (the operation that writes its output to a destination image). It contains a pointer to an ordered list of XilOp objects, which allow you to pick up parameters for previous ops in the chain.

For more information on molecules and operation chains, see "Operation Prototype: Molecule" on page 62.

The XilOp class is defined in the _XilOp.hh header file.

The XilRectList Class

The XilRectList class contains information for generating a rectangular list. For more information on using XilRectList objects, see "Geometric Operations" on page 109.

The XilRectList class is defined in the _XilRectList.hh header file.

The XilScanlineList Class

The XilScanlineList class contains information representing a scanline list. An XilScanlineList object provides a convenient way for geometric operations to turn a convex region into a list of scanlines. For more information on using XilScanlineList, see "Geometric Operations" on page 109.

The XilScanlineList object is defined in the _XilScanlineList.hh header file.

The XilTile Class

The XilTile class contains information representing a tile.

The XilTile class is defined in the _XilTile.hh header file.

The XilTileList Class

The XilTileList class contains a list of tiles.

The XilTileList class is defined in the _XilTileList.hh header file.

Writing Device Handlers

Chapter 2, "More on Writing Device Handlers," discusses information that generally applies to all devices. Chapters 3 through 6 discuss information specific to each device type.

I/O Devices

I/O devices include any devices that can produce or display images, such as scanners, frame grabbers, image files, and displays. Configured I/O devices appear as "device images" to XIL applications, and may be used as sources and destinations for all XIL imaging operations. These devices are described in Chapter 3, "I/O Devices."

Compute Devices

Compute handlers contain the device-dependent implementation of one or more atoms or molecules. For example, a compute device might implement the geometric operators accelerated by an add-on card, or might provide a combination of frequently used functions in the form of a molecule. A compute device may be hardware specific, or may be a software-only implementation of a superior algorithm. Compute handlers are loaded during the first call to xil_open(). These handlers are described in Chapter 4, "Compute Devices."

Compression Devices

Compression devices contain most of the utility functions for implementing a method of compression and decompression, even though the actual compress and decompress functions are provided in an associated compute device handler. The compression device performs buffer management and implements the semantics of the XilCis object. A compression device for a specified compressor is loaded when xil_cis_create() is called. Compression devices are discussed in Chapter 5,

"Compression/Decompression."

Storage Devices

Storage devices allow images to reside in other places besides host CPU memory. Such a device is typically associated with a compute device, allowing an accelerator to take advantage of image data remaining local to the accelerator during sequential function calls.

The handlers for storage devices are responsible for allocating, deallocating, and describing the data format of the storage on their devices. They are also responsible for data conversion between storage devices. In addition, it is useful to have the storage handler perform single-pixel access for xil_get_pixel() and xil_set_pixel() to avoid having to convert image data in those cases.

Typically, a compute device handler causes the storage device handler for the device to be loaded when it first tries to create an image on the device. The CPU memory storage handler is loaded at the time of the first image creation. Storage devices are discussed in detail in Chapter 6, "Storage Devices."