libshbeu
===========

libshbeu: A library for controlling the SH-Mobile BEU.

Copyright (C) 2010 Renesas Electronics Corporation

The [SH-Mobile][0] processor series includes a hardware blend engine unit (BEU)
that supports image overlay.

This source archive contains:

 * src/libshbeu: the libshbeu shared library
 * src/tools: commandline tools

libshbeu API
------------

libshbeu allows both synchronous and asynchronous access to the BEU. The
synchronous API provides a one-shot function shbeu_blend(). The asychronous API
replaces this with a similar but non-blocking function, shbeu_start_blend(),
and a corresponding shbeu_wait().

Please see doc/libshbeu/html/index.html for API details.


shbeu-display
-------------

shbeu-display is a commandline program for displaying raw image or video files.
It uses the SH-Mobile BEU to perform simultaneous colorspace conversion and
blending on each input frame. It allows the user to pan the foremost image.

	Usage: shbeu-display [options] -i <input file>
	Overlays raw image data using the SH-Mobile BEU and displays on screen.
	Options and input file can be specified for up to 3 inputs, e.g.
	  shbeu-display -s vga -i vga.yuv -s qvga -i qvga.rgb -s qcif -i qcif.rgb

	Input options
	  -c, --input-colorspace (RGB565, RGBx888, NV12, YCbCr420, NV16, YCbCr422)
		                     Specify input colorspace
	  -s, --input-size       Set the input image size (qcif, cif, qvga, vga, d1, 720p)

	Control keys
	  Space key              Read next frame
	  Cursor keys            Pan
	  =                      Reset panning
	  q                      Quit

	Miscellaneous options
	  -h, --help             Display this help and exit
	  -v, --version          Output version information and exit

	File extensions are interpreted as follows unless otherwise specified:
	  .yuv    YCbCr420
	  .420    YCbCr420
	  .422    YCbCr422
	  .rgb    RGB565
	  .565    RGB565
	  .x888   RGBx888


Testing
-------
The library has been tested on an MS7724 development board (SH7724 processor)
with an 800x480 LCD using the shbeu-display tool with the following command
lines:
	shbeu-display -s vga -i vga.rgb
	shbeu-display -s vga -i vga.yuv

	shbeu-display -s vga -i vga.rgb -s qvga -i qvga.rgb
	shbeu-display -s vga -i vga.rgb -s qvga -i qvga.yuv
	shbeu-display -s vga -i vga.yuv -s qvga -i qvga.rgb
	shbeu-display -s vga -i vga.yuv -s qvga -i qvga.yuv

	shbeu-display -s vga -i vga.rgb -s qvga -i qvga.rgb -s qcif -i qcif.rgb
	shbeu-display -s vga -i vga.rgb -s qvga -i qvga.rgb -s qcif -i qcif.yuv
	shbeu-display -s vga -i vga.rgb -s qvga -i qvga.yuv -s qcif -i qcif.rgb
	shbeu-display -s vga -i vga.rgb -s qvga -i qvga.yuv -s qcif -i qcif.yuv
	shbeu-display -s vga -i vga.yuv -s qvga -i qvga.rgb -s qcif -i qcif.rgb
	shbeu-display -s vga -i vga.yuv -s qvga -i qvga.rgb -s qcif -i qcif.yuv
	shbeu-display -s vga -i vga.yuv -s qvga -i qvga.yuv -s qcif -i qcif.rgb
	shbeu-display -s vga -i vga.yuv -s qvga -i qvga.yuv -s qcif -i qcif.yuv

	shbeu-display -s vga -i vga.422 -s qvga -i qvga.yuv
	shbeu-display -s vga -i vga.x888 -s qvga -i qvga.yuv

Note: The destination surface in all these cases is RGB565.


SH-Mobile
---------

The [SH-Mobile][0] processor series includes a hardware video engine unit that
supports colorspace conversion, rotation and scaling. Some models also include
support for camera capture, JPEG processing, and DSP instructions.

[0]: http://www.renesas.com/fmwk.jsp?cnt=sh_mobile_family_landing.jsp&fp=/products/mpumcu/sh_mobile/

Kernel configuration
--------------------

libshbeu uses the Linux kernel UIO support for the SH-Mobile BEU, this is not
in the mainline kernel. You will have to manually add this capability.

The following kernel boot option reserves physically contiguous memory for BEU
use:

    memchunk.beu0=4m

License
-------

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Library General Public License for more details.

You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA  02110-1301 USA

See the file COPYING for details.
