Bitblit Users Guide

Introduction

This package is written to provide low-level 2D blitting/blending graphics acceleration services support on DM6446, OMAP3530 and OMAP-L137. The graphics operations are accelerated using the 64x+ or 674x DSP on the SoC. The package also provides an easy to use ARM side library so the ARM application writer doesn't need to make direct Codec Engine calls, but rather simple APIs, such as bb_copy(), bb_blendover(), etc.

The raw BITBLIT DSP algorithm functions have been wrapped into a XDAIS algorithm. In order for the algorithm to be used within Codec Engine the IUNIVERSAL API was implemented. A test program is included (bitblit_test) which tests each of the supported functions. The output frames can be displayed to an LCD and/or written to bitmap files.

The source for this is provided under a BSD license and can be downloaded from here, note that currently you must use SVN to obtain the sources. Use the following command to check out the version of bitblit that you want, replacing tag_name with the appropriate name.

svn co https://gforge.ti.com/svn/bitblit/tags/tag_name

Directory Structure

After you have obtained the sources, the directory structure will look as follows:

bitblit_<version>                
|-- docs                         // Documentation files for Bitblit
`-- packages                     // Your XDC path should include this dir
    `-- ti
        `-- sdo
            |-- algos
            |   `-- bitblit      // The bitblit DSP algorithm
            |
            |-- apps
            |   `-- bitblit_test // Test application
            |
            |-- library
            |   `-- bitblit      // ARM-side bitblit library
            `-- servers
                |-- bitblit_unitserver_evm3530       // Location of DSP executable for OMAP3530 EVM
                |-- bitblit_unitserver_evmdm6446     // Location of DSP executable for DM6446 EVM
                `-- bitblit_unitserver_evmomapl137   // Location of DSP executable for OMAP-L137 EVM

Installation, Build and Usage

1. Edit bitblit_<version>/Makefile to include your DVSDK’s Rules.make and C6x Code Generation Tools. Note that this implies that you should have a properly building DVSDK including the C6x CGT and BIOS, thus you should go through your DVSDK's Getting Started Guide before attempting this.
   1. If you want information printed to the terminal, set Profile = DEBUG. Otherwise, comment out this variable.
   2. The application can write the output to the display using DMAI, a utility layer which assists in writing to the frame buffer. An alternative option is to write the output display to a series of bitmap files. If you wish not to use DMAI and instead output a series of bitmaps, comment out the line DISPLAY=DMAI
2. From the bitblit_<version> directory, type make all followed by make install. If you have not set your PLATFORM in Rules.make you can type e.g. make PLATFORM=dm6446 all
3. Boot your target. Make sure to set the memory correctly depending on your target:

DM6446: mem=118M

OMAP3530: mem=99M

OMAP-L137: mem=32M

1. From the serial prompt, execute the loadmodules.sh script.
2. Still at the serial prompt, execute the application, using the following format:

./remote_ti_platforms_<platform>_bitblit.xv5T [OPTIONS]

Options:

 -x                  Use the hardware resizer (available on 
                     OMAP3530 and DM6446, but not OMAPL137) 
                     instead of memcpy on ARM
 -d [directory name] The directory where the output images will
                     be stored.  If no directory is specified,
                     the current directory will be used.
 -i1 [image file]    Image 1 with a .bin format and dimensions
                     of 720x576.  If no file is specified,
                     bluemarble_apollo17_720x576_rgb.bin will be
                     used from the testData directory.
 -i2 [image file]    Image 2 with a .bin format and dimensions
                     of 500x200.  If no file is specified,
                     flicker_500x200_rgb.bin will be used
                     from the testData directory.
 -i3 [image file]    Image 3 with a .bin format and dimensions
                     of 203x152.  If no file is specified,
                     icon_203x152_rgb.bin will be used  from
                     the testData directory.
 -i4 [image file]    Image 4 with a .bmp format and dimensions
                     of 360x480.  If no file is specified,
                     scenery.bmp will be used  from the testData
                     directory.

Alternatively, use the "demo.sh" script to run the application.

Using Images Other Than the Ones Provided

To create images that can be used with this application, see the README in the bitblit_x_xx/tools directory. If you provide images with sizes that do not match those specified, there will unexpected results, though the app demonstrates how to use images of different sizes.

Using Bitblit

Bitblit Basics

A discussion on the basics of what a Bit Blit (Bit-Block (Image) Transfer) can be found on Wikipedia here, basically Bitblit will take arrays of image data and mix them together for a display. Because of this we will need to know a few things, primarily dimensions and data types. For dimensions we need to know both the height and width of the source data, and the height and width of the destination location (as Bitblit will scale for you). For data types we need to know how to process the data arrays we are provided so knowing the data is RGB565 or RGB888 will be very useful. Knowing the types of information needed by Bitblit to work you can probably guess what the structures you pass into a Bitblit call will be, but to be specific the two main structure types for Bitblit data are given in the sections below.

Though Bitblit supports several operations the primary operations used are blend and copy, where blend will take two image arrays (foregroundSurface & backgroundSurface) and blend them based on their alpha value (i.e. put one image on another), providing an output (dstSurface). Copy performs the basic blit just moving one image array (forgroundSurface) into (over) another image array (dstSurface), often the background.

Bitblit Surface

The IBITBLIT_Surface structure contains information about your surface, in other words this describes an array of image data that will be processed by Bitblit, including a pointer to the actual image data array. The width and height define how large the array of image data for the surface is. The stride values define the stride of the pixel data. The pixelFormat defines the type of pixel data being used in the surface, today you could use IBITBLIT_PIXELFORMAT_RGB565, IBITBLIT_PIXELFORMAT_RGB565A3, IBITBLIT_PIXELFORMAT_ARGB8888, IBITBLIT_PIXELFORMAT_ARGB8888_CLUT, or IBITBLIT_PIXELFORMAT_COLOR. The virtRgbFbPtr points to the array of image values and the virtAlphaFbPtr points to an array of alpha values (i.e. thickness/opaqueness of the image). The final CLUT entries are for color look up table images if you are using CLUT.

The structure given below is from the actual source code in /bitblit/packages/ti/sdo/algos/bitblit/ibitblit.h.

   typedef struct IBITBLIT_Surface {
       XDAS_Int32 width;
       XDAS_Int32 height;
       XDAS_Int32 strideRgb;
       XDAS_Int32 strideAlpha;
       IBITBLIT_PixelFormat pixelFormat;
       IBITBLIT_PixelColor srcChroma;  /* IBITBLIT_CHROMAKEY_NONE indicates no chroma */
       IBITBLIT_PixelColor argb;
       XDAS_UInt8 globalAlpha;
       Void   *virtRgbFbPtr;
       Void   *virtAlphaFbPtr;
       IBITBLIT_PixelColor *virtClutPtr;      /* Color lookup table pointer */
       XDAS_UInt32 clutSize;                  /* CLUT data size in bytes */
   } IBITBLIT_Surface;

Note the grey regions in the diagram above are indicating 0 alpha pixels, the area inside the dotted line is the region.

Bitblit Region

The IBITBLIT_Region structure contains information about the region you want to occupy with your surface, in otherwords this defines what Bitblit will do with your surface (in addition to the actual Bitblit operation given). The position is defined by xpos and ypos which are offsets from the upper left corner of your target region, this lets you place the surface anywhere in the target and enables effects like moving sprites with successive Bitblit calls. The size of your surface on the target is defined by the width and height parameters, this allows bit blit to scale the surface for you so your target region size can be independent of your surface's actual dimensions.

The structure given below is from the actual source code in /bitblit/packages/ti/sdo/algos/bitblit/ibitblit.h.

   typedef struct IBITBLIT_Region {
       XDAS_Int32 xpos;
       XDAS_Int32 ypos;
       XDAS_Int32 width;
       XDAS_Int32 height;
   } IBITBLIT_Region;

Note the grey regions in the diagram above are indicating 0 alpha pixels.

Bitblit Dimensions Summary

Using a BitBlit blend operation given the source surfaces given above in the region shown in the diagram here one can generate the image below.

Bitblit API

The graphics operations are executed through a process call. (Note that this process call is unique to the bitblit algorithm which is sepearte from the standard UNIVERSAL_process call.) The bitblit process call takes the form:

BITBLIT_process(handle, blitOperation, foregroundSurface, backgroundSurface, dstSurface, foregroundRegion, backgroundRegion, dstRegion, clipRegion)

Here, a surface is a structure describing an actual image, including its size and pointers to the pixel data. A region is simply a rectangle describing the location of its corresponding surface.

This function can be called directly from the application via bb_process(), but many times this structure is cumbersome. Thus commonly used functions have been created that marshals the arguments and then calls BITBLIT_process(). For a complete list of functions, including comments on what each function does, see bitblit/packages/ti/sdo/library/bitblit/bb.h.

The current list of functions available to the application from the bitblit library include:

• bb_process - wrapper for BITBLIT_process(), but not commonly used
• bb_clear - clears a surface
• bb_rectangle - clears a region within a surface
• bb_copy - copies a region from one surface into the region of another surface
• bb_blendover - blend background into foreground
• bb_blendin - blend foreground into background
• bb_blendalpha - blend foreground into background with alpha
• bb_alpharegion - clears the alpha part of a surface for a particular region
• bb_copy_flicker - like bb_copy but with anti-flicker enabled
• bb_compareRegions - compares two regions, if they don't match, return 0, else 1

To further examine the ARM-side API, we can decompose the BITBLIT_process() calls and evaluate the DSP algorithm itself. The BITBLIT_process() call takes an operation as an argument. There are 9 different blitOperations, which can be divided into 3 catagories: clear, blend, and supplemental operations. These naturally correspond to the ARM library functions but are listed here for completeness.

• Clear Operations – These operations clear part or all of dstSurface.
  • IBITBLIT_OPERATION_CLEAR – clears the entire dstSurface
  • IBITBLIT_OPERATION_RECTANGLE – clears the part of dstSurface located in dstRegion
  • IBITBLIT_OPERATION_ALPHAREGION – clears the alpha part of dstSurface located in dstRegion
• Blend Operations – These operations blend the foreground and background images and place the result in dstSurface.
  • IBITBLIT_OPERATION_BLEND_IN – Blend the foreground into the background. Place the result in dstSurface with scaling, if necessary.
  • IBITBLIT_OPERATION_BLEND – Blend the foreground and background surfaces. Place the result in dstSurface with scaling, if necessary.
  • IBITBLIT_OPERATION_ BLEND_OVER – Same as IBITBLIT_OPERATION_BLEND
  • IBITBLIT_OPERATION_BLEND_ADD_ALPHA – Blend the foreground surface into the background surface including the alpha region.
  • IBITBLIT_OPERATION_COPY – Copies the foregroundSurface to the dstSurface, with scaling, if necessary.
• Supplemental – These operations are used only in addition to one of the blend operations, which is done by performing a logical OR. For example, to use antiflicker with blend in, the blitOperation would be IBITBLIT_OPERATION_BLEND_IN | IBITBLIT_OPERATION_ANTIFLICKER.
  • IBITBLIT_OPERATION_ANTIFLICKER – Prevents flickering from being displayed in dstSurface
  • IBITBLIT_OPERATION_SRCCHROMA – Used to get pixel level alpha from foregroundSurface.

This table shows which arguments are needed for the various types of process calls.

Operation	fg surface	bg surface	dst surface	fg region	bg region	dst region	clip region
CLEAR	-	-	x	-	-	-	-
RECTANGLE	-	-	x	-	-	x	*
ALPHA_REGION	-	-	x	-	-	x	*
BLEND_IN	x	x	x	x	x	x	*
BLEND/BLEND_OVER	x	x	x	x	x	x	*
BLEND_ADD_ALPHA	x	x	x	x	x	x	*
COPY	x	-	x	x	-	x	*

x = required; - = NULL; * = if clip region is NULL, it will be the same as dstRegion

Bitblit Demo Application

A complex bitblit application was released as bitblit 1.0. This application does not include the use of the ARM-side bitblit library, but instead makes direct Codec Engine calls to access the DSP. Subsequent releases of bitblit are denoted 2.x. There are several reasons to use this version instead of the latest releases; primarily, there are a number of complicated test scenarios available which shows the full capability of the bitblit DSP algorithm. Unfortunately this makes the application code more complicated thus it may be more difficult to start your own development from this release. Additionally, this release has only been tested against earlier releases of the DVSDK stack (see its release notes for details) thus may not work with the latest DVSDK releases. Finally, the majority of bugs filed on bitblit will only be fixed in the latest available bitblit releases.

As a summary of the bitblit demo application, there are 13 different tests to choose from:

1. An image is blended with color bars while the display area shrinks.
2. An image is written to the display area in a horizontal pan.
3. Color bars are flashed at random locations on the display.
4. Color bars randomly fill the display, overlapping and blending with one another.
5. An image moves vertically along the center of the screen.
6. A large image is scaled up.
7. A small image is scaled up.
8. Two images and a yellow surface are blended together
9. Two images and a yellow surface are blended with a gradient transparency
10. The anti-flicker operation is demonstrated
11. This tests clipping and scaling. A single downscale is compared to a multi-region downscale, ensuring they are bit exact.
12. An image is moved horizontally across the screen, testing edge detection.
13. An image is moved horizontally across the screen while being scaled, testing edge detection.

The DSP-side algorithm has remained virtually the same for both 1.0 and 2.x releases, but the ARM-side has been refactored. The demo application has greater CMEM requirements, thus use the following kernel bootargs: DM6446: mem=96M, OMAP3530: mem=80M, OMAP-L137: mem=32M. Follow the above instructions to build (noting the versions of tools used for validation are on the release notes), and then run "loadmodules.sh" and "demo.sh" on the target.

Software dependency download links

BitBlit was validated against a baseline of: -

• DM6446 - DVSDK 2.0 based on MVL 5.0
• OMAP3 - DVSDK 3.0
• OMAP-L1 - SDK 1.0 GA based on MVL 5.0.