CHAPTER 7

XIL Acceleration on the Creator Graphics Accelerator

This chapter describes the XIL functions that are specific to the Creator and Creator3D Graphics Accelerators.

XIL is Sun's foundation imaging and video library. Several important XIL functions have been accelerated for the Ultra platforms using the UltraSPARC Visual Instruction Set (VIS) and the Creator Graphics Accelerator.

XIL Data Types

XIL supports a very general image structure, but not all types of XIL images are accelerated using VIS and Creator. The XIL data types supported in the VIS port are:

• 1-, 2-, 3-, and 4-banded unsigned byte images
• 1-, 2-, 3-, and 4-banded signed short images
• Band-aligned child images
• All regions of interest
• XIL_PIXEL_SEQUENTIAL type images

Accelerated Functions

TABLE 7-1 shows the XIL functions accelerated using VIS. Note that display molecules are defined for one- and three-banded XIL_BYTE images.

TABLE 7-1

Function	VIS Acceleration 8-bit	16-bit	Molecules Display	Other	Comments
xil_absolute		1 - 4 bands
xil_add	1 - 4 bands	1 - 4 bands	x
xil_add_constant	1 - 4 bands	1 - 4 bands	x
xil_affine	1 - 4 bands	1 - 4 bands	x		See Note 6
xil_and	1 - 4 bands	1 - 4 bands	x
xil_and_constant	1 - 4 bands	1 - 4 bands	x
xil_band_combine	1 - 4 bands	1 - 4 bands
xil_blend	1 - 4 bands	1 - 4 bands
xil_cast . 8 Æ 16 . 16 Æ 8	1 - 4 bands 1 - 4 bands	1 - 4 bands 1 - 4 bands	x
xil_convolve	1 - 4 bands	1 - 4 bands	x		See Note 1
xil_copy	1 - 4 bands	1 - 4 bands	x
xil_decompress					See Notes 2, 5
xil_get_pixel					See Note 4
xil_lookup	1 - 4 bands	1 - 4 bands	x	x	See Note 5
xil_max	1 - 4 bands	1 - 4 bands	x
xil_min	1 - 4 bands	1 - 4 bands	x
xil_multiply	1 - 4 bands	1 - 4 bands	x
xil_multiply_constant	1 - 4 bands	1 - 4 bands	x
xil_not	1 - 4 bands	1 - 4 bands	x
xil_or	1 - 4 bands	1 - 4 bands	x
xil_or_constant	1 - 4 bands	1 - 4 bands	x
xil_rescale	1 - 4 bands	1 - 4 bands	x	x	See Notes 3, 5

TABLE 7-1 (Continued)

Function	VIS Acceleration 8-bit	16-bit	Molecules Display	Other	Comments
xil_rotate	1 - 4 bands	1 - 4 bands	x		See Note 6
xil_scale	1 - 4 bands	1 - 4 bands	x	x	See Note 5, 6
xil_set_pixel			x		See Note 4
xil_set_value	1 - 4 bands	1 - 4 bands	x
xil_subtract	1 - 4 bands	1 - 4 bands	x
xil_subtract_const	1 - 4 bands	1 - 4 bands	x
xil_subtract_from_const	1 - 4 bands	1 - 4 bands	x
xil_tablewarp			x		See Note 4
xil_threshold	1 - 4 bands	1 - 4 bands	x	x	See Notes 3, 5
xil_transpose	1 - 4 bands	1 - 4 bands	x
xil_xor	1 - 4 bands	1 - 4 bands	x
xil_xor_const	1 - 4 bands	1 - 4 bands	x

Notes to Table 7-1

Note 1: xil_convolve is accelerated for 3 . 3, 5 . 5, and 7 . 7 kernels.

Note 2: xil_decompress is accelerated for the following cases:

• xil_decompress + color_convert (JPEG compressed image or sequence and MPEG1 compressed sequence)
• xil_decompress + color_convert + display (JPEG compressed image or sequence and MPEG1 compressed sequence)
• xil_decompress + color_convert + scale + display (MPEG1 compressed sequence)

This decoder adheres to full-precision 24-bit CCIR 601 YCC to RGB709 color space conversion.

There are a few instances when decompression of streams will not be accelerated.

• Decompression of JPEG or MPEG1 streams which are not in one contiguous buffer in memory is not accelerated. For example, streams split up using xil_cis_put_bits_ptr might not be accelerated.
• If one frame in a stream is not accelerated for some reason (e.g. the decompressor encountered invalid data in the frame), subsequent frames in the stream will not be accelerated.

• Acceleration is also disabled if one tries to seek backwards or forwards in a stream.

Note 3: xil_rescale + xil_threshold + xil_threshold + display molecule is accelerated using the Creator depth-cueing hardware. However, some restrictions apply, as follows:

• The first threshold must have a high value of 255. The low and map values must be equal (any number N between 0 and 255.)
• The second threshold must have a low value of 0. The high and map values must be equal (any number M between 0 and N).
• The parameters for xil_rescale must be chosen such that y values of the line represented must span the range of values between N and M while the x values are within 0 and 255. See FIGURE 7-1.
• The images must be 1-banded XIL_BYTE images.

  Legal

  N

  Illegal

  M

  255

  x

The following code is an example of a correct call to invoke this molecule:

float scale[1] = 1.5; float offset[1] = -10; float t1_lo[1] = 255; float t1_hi[1] = 240; float t1_map[1] = 240; float t2_lo[1] = 0; float t2_hi[1] = 15; float t2_map[1] = 15; xil_rescale(src,tmp1,scale,offset); xil_threshold(tmp1,tmp2,t1_lo,t1_hi,t1_map); xil_threshold(tmp2,tmp3,t2_lo,t2_hi,t2_map); xil_display(tmp3,display);

However, if the same calling sequence is done with scale[1] = .40, the molecule will not be invoked because the line y = 0.40*x -10 only spans the range y = -10 to y = (255*0.40) - 10 = 92 between x = 0 and x = 255. For the molecule to execute, y must span at least the range y = 15 to y = 240 for x between 0 and 255.

Note 4: xil_get_pixel, xil_set_pixel, and xil_tablewarp are accelerated only as display molecules. For xil_tablewarp, only interpolation = "nearest" is accelerated.

Note 5: All the molecules (other than a single xil function + display) that are accelerated are as follows:

• xil_decompress + xil_colorconvert [+ display] ( for JPEG)
• xil_decompress + xil_colorconvert [+ display] ( for MPEG1)

· xil_decompress + xil_colorconvert + xil_scale + display ( for
  MPEG1)

· xil_threshold + xil_threshold [+ display]
· [xil_rescale] + [xil_threshold] + [xil_threshold] +
  [xil_cast] + display
· xil_scale + xil_lookup + display (the accelerated molecules are for 8- or
  16-bit bilinear scale followed by 8-to-8 bit or 16-to-8 bit lookup)

Note 6: There are some restrictions on the acceleration of xil_affine, xil_scale, and xil_rotate: xil_affine and xil_rotate are accelerated only for 1-, 3-, and 4-banded images with "nearest" interpolation, and only for 1-and 3-banded images with "bilinear" and "bicubic" interpolation. The restriction for xil_scale is that in the case of interpolation = "general" the size of the resampling kernels are limited to 8 . 8 for 8-bit images, and 8 . 4 for 16-bit images.

Double Buffer Support

XIL supports double buffers on hardware where double buffers are available (e.g. the Creator family). This section describes the double buffer support functions and their usage.

The functions are:

xil_create_double_buffered_window
xil_set_active_buffer
xil_get_active_buffer
xil_swap_buffers

If you want to use a display image as a double-buffered display image, then instead of using xil_create_from_window, use xil_create_double_buffered_window to create the image. Trying to use xil_create_double_buffered_window on hardware that does not support double buffers returns a NULL device. The developer must catch the failure and call xil_create_from_window instead.

If the image was created with xil_create_double_buffered_window and the hardware supports double buffers, then XilBufferId makes sense and can take two values, XIL_BACK_BUFFER and XIL_FRONT_BUFFER. For such a window, one of the buffers is considered to be active at any time, and all functions writing to the image will be writing the active buffer (for example a copy to the image will copy the pixels to the active buffer of the image). On the other hand, the front buffer is the one that is visible, i.e. displayed on the screen. At creation time, the active buffer is XIL_BACK_BUFFER.

To start using the display image as a double buffered image after it has been created by xil_create_double_buffered_window, you need to take no special action since the active buffer is XIL_BACK_BUFFER. If the active buffer has been set to XIL_FRONT_BUFFER, the image will not be used as a double-buffered image (although imaging operations will not fail). To start using it again as a double-buffered image, make a call like the following:

xil_set_active_buffer(dest,XIL_BACK_BUFFER)

which will cause output to go to the back buffer. Note that in this case, the content of the image will not be displayed (i.e., visible) without some action from the user. The action to take is a call like the following:

xil_swap_buffers(dest)

This will make the content of the image visible. When the image is not needed as a double-buffered image any longer, make a call like the following:

xil_set_active_buffer(dest,XIL_FRONT_BUFFER)

This ensures that the write and display buffers of the hardware are reset to their default values.

The following is a typical code segment for using double buffers:

dest = xil_create_double_buffered_window(state,display,dwindow); ... for (i=0; i<repeat; i++) { ... xil_lookup(src,dest,lut); xil_swap_buffers(dest); } xil_set_active_buffer(dest,XIL_FRONT_BUFFER);