libshveu
===========

libshveu: A library for controlling the SH-Mobile VEU.

Copyright (C) 2009 Renesas Technology Corp.
Copyright (C) 2010 Renesas Electronics Corporation

The [SH-Mobile][0] processor series includes a hardware video engine unit (VEU)
that supports colorspace conversion, rotation and scaling.

This source archive contains:

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

libshveu API
------------

libshveu provides simple scale and rotate capability via the shveu_resize and
shveu_rotate blocking functions.
	veu = shveu_open()
	do {
		shveu_resize(veu, ...);
	} while (processing);
	shveu_close(veu);

For more flexibility, such as operating on a selection of a larger frame the
shveu_setup function can be used along with shveu_start and shveu_wait.
	veu = shveu_open()
	do {
		shveu_setup(veu, ...);
		shveu_start(veu);
		shveu_wait(veu);
	} while (processing);
	shveu_close(veu);

For low latency and reduced memory use, bundle mode is supported via the
shveu_start_bundle function. Using this mode requires that the input and output
buffer addresses are updated before the start of the next bundle.
	veu = shveu_open()
	do {
		shveu_setup(veu, ...);
		do {
			shveu_set_src(veu, ...);
			shveu_set_dst(veu, ...);
			shveu_start_bundle(veu, ...);
			end = shveu_wait(veu);
		} while (!end);
	} while (processing);
	shveu_close(veu);

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


shveu-convert
-------------

shveu-convert is a commandline program for converting raw image or video files.
It uses the SH-Mobile VEU to perform simultaneous colorspace conversion and
either rotation or scaling on each input frame.

    Usage: shveu-convert [options] [input-filename [output-filename]]
    Convert raw image data using the SH-Mobile VEU.
    
    If no output filename is specified, data is output to stdout.
    Specify '-' to force output to be written to stdout.
    
    If no input filename is specified, data is read from stdin.
    Specify '-' to force input to be read from stdin.
    
    Input options
      -c, --input-colorspace (RGB565, NV12, YCbCr420, YCbCr422)
                             Specify input colorspace
      -s, --input-size       Set the input image size (qcif, cif, qvga, vga, d1)
    
    Output options
      -o filename, --output filename
                             Specify output filename (default: stdout)
      -C, --output-colorspace (RGB565, NV12, YCbCr420, YCbCr422)
                             Specify output colorspace
    
    Transform options
      Note that the VEU does not support combined rotation and scaling.
      -S, --output-size      Set the output image size (qcif, cif, qvga, vga, d1)
                             [default is same as input size, ie. no rescaling]
      -r, --rotate           Rotate the image 90 degrees clockwise
    
    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
      .rgb    RGB565


shveu-display
-------------

shveu-display is a commandline program for displaying raw image or video files.
It uses the SH-Mobile VEU to perform simultaneous colorspace conversion and
scaling on each input frame. It allows the user to zoom in/out and pan the image.

    Usage: shveu-display [options] [input-filename]
    Processes raw image data using the SH-Mobile VEU and displays on screen.

    If no input filename is specified, a simple image will be created.

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

    Control keys
      +/-                    Zoom in/out
      Cursor keys            Pan
      =                      Reset zoom and 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
      .rgb    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
--------------------

libshveu uses the Linux kernel UIO support for the SH-Mobile VEU, which was
added in 2.6.27.

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

    memchunk.veu0=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.
