Version 1.3.1 and above
=======================

1.1 Overview
1.2 Obtaining libshjpeg
1.3 libjpeg Licensing
1.4 Application Requirements
1.5 Build System Requirements
1.6 Target System Requirements
2.1 Compilation
2.2 Compilation Examples
3.1 Memory Allocation
3.2 Running Tests
4.1 Supported Features
5.1 Usage
6.1 Limitations
6.2 libjpeg62 Application Workaround
7.1 Errors, Warnings, Information messages

1.1 Overview
============
Using this version of libshjpeg with the libjpeg compatibility enabled will 
allow programs designed for use with libjpeg to transparently use the hardware 
acceleration capabilities of Renesas's SH7772/4 SoC provided JPU 
(Jpeg Processing Unit).  The application and system requirements are listed below.

1.2 Obtaining libshjpeg
=======================
The source files for libshjpeg can be found online at http://github.com/dhobsong/libshjpeg (version tag v1.3.1) where they may be downloaded in a tarball or using git.  

1.3 libjpeg Licensing
=====================
With the addition of libjpeg compatibility, this software is based in part on
the work of the Independent JPEG Group.  No source files from the libjpeg 
library are distributed with this software although they are necessary for 
compilation of a libjpeg compatible libshjpeg.

The Independent JPEG Group's most recent library versions (currently 8b) can be
obtained from their archive at http://www.ijg.org/files/

1.4 Application Requirements
============================

No application code needs to be changed, however, the application must be 
re-linked to use this library instead of libjpeg (i.e. change -ljpeg to 
-lshjpeg in your compilation scripts)

1.5 Build System Requirements
=============================

In order to successfully create the libjpeg wrapper, then build system should 
have a copy of the libjpeg source for the version that you wish to use on the 
target system.  

1.6 Target System Requirements
==============================

Since this library will automatically fall back to use libjpeg functions when 
the hardware acceleration cannot handle the conversion, a working version of 
libjpeg must exist on the target system as a SHARED library. In particular, 
for libjpeg version 6b, this means configuring your build with 
	./configure --enable-shared 
before compiling.

2.1 Compilation
===============

 * Ensure that the libjpeg library is installed and properly working on your
   target platform.  libjpeg can be downloaded from several sources including
   http://www.ijg.org/files/  older versions may be archived at other sites,
   such as http://sourceforge.net.  A example of how to compile libjpeg
   follows in the Compilation Example section

 * execute 'autoreconf -vif' to generate a configure file

 * execute 'configure' with any desired options.  The path to the libjpeg
   library headers used in compilation can be changed with
   --with-libjpeg-path=<path>

 * execute 'make' to build the library and test programs and 'make install'
   to install them

  *libjpeg-62 and earlier releases.
   -------------------------------
   This library has been tested with libjpeg versions 62 and 80.  Earlier 
   versions may or may not work without modification.  It is likely that 
   some kind of modifications would be necessary. Version 80 can be used 
   as is with libshjpeg, but the following points must be 
   observed when using version 62. 

   *NOTE1: decoding files with large amounts of EXIF or other metadata may
    fail.  This is an omission in the earlier versions of libjpeg that
    version 80 users need not worry about.
    There are two options to fix this problem.
    Option 1:  Update application code
	See "libjpeg62 Application Workaround" section
    Option 2:  Patch libjpeg62
	The libjpeg code can be patched using the included file 
	and the patch command a follows.

	    patch -p1 < libjpeg6_skipfix.patch

	The libjpeg62 will then need to be recompiled and re-installed to 
	be of use

   *NOTE2: The --host cross-compilation option for configue in libjpeg-6b
    does not function correctly.  Instead, the CC option should be used
    to specify the cross compiler

    CC=arm-linux-gnueadi-gcc ./configure --enable-shared

2.2 Compilation Examples
========================
The following examples show the commands necessary to compile libshjpeg and
the libjpeg settings that are necesary. Either libjpeg-6b or libjpeg-8b must
be compied BEFORE libshjpeg can be compiled.

libjpeg-6b (option 1)
---------------------
Assuming that the libjpeg-6b source files are located in <path>/jpeg-6b and
the libshjpeg source files are located in <path>/shjpeg

/# cd <path>/jpeg-6b
<path>/jpeg-6b# cp <path>/shjpeg/libjpeg6_skipfix.patch .
<path>/jpeg-6b# patch -p1 < libjpeg6_skipfix.patch
<path>/jpeg-6b# CC=arm-linux-gnueabi-gcc ./configure --enable-shared
<path>/jpeg-6b# make
<path>/jpeg-6b# make install

libjpeg-8b (option 2)
---------------------
Assuming that the libjpeg-8b source files are located in <path>/jpeg-8b

/# cd <path>/jpeg-8b
<path>/jpeg-8b# ./configure --host=arm-linux-gnueabi
<path>/jpeg-8b# make
<path>/jpeg-8b# make install

libshjpeg
---------
Assuming that the libshjpeg source files are located in <path>/shjpeg

/# cd <path>/shjpeg
<path>/shjpeg# autoreconf -vif
<path>/shjpeg# ./configure --host=arm-linux-gnueabi 
<path>/shjpeg# make
<path>/shjpeg# make install

To compile with a different libjpeg version that the system default, change 
the above ./configure command to:

<path>/shjpeg# ./configure --host=arm-linux-gnueabi --with-libjpeg-path=<path
    to libjpeg headers>
<path>/shjpeg# make clean



3.1 Memory Allocation
=====================
The JPU can only decode files up to a size that will fit in a continuous
memory chunk.  A memory chunk can be assigned to the JPU by specifying
'memchunk.jpu=<size>m' (e.g. memchunk.jpu=8m for an 8MiB chunk) in the kernel
boot cmdline.

3.2 Running Tests
=================
The test file libjpegtest is included with this distribution.
To execute the test perform the following:

$ export LD_LIBRARY_PATH=/usr/local/lib (if not already set)
$ libjpegtest <input>.jpg

to decode and re-encode a jpeg file.  The other options supported by
libjpegtest can be seen from the command line by typing.
$ libjpegtest -h

4.1 Supported Features
======================

API
---

The functions listed as being "ignored" will not have any effect on the encoded
or decoded output. "supported" functions can be used to control the coding
process and retrieve information about the source/destination jpeg. Any API not
listed in the table is not supported and should not be used with libshjpeg.

------------------------+---------------+------------+---------------------
API function            |   supported   |   ignored  |     comment
------------------------+---------------+------------+---------------------
jpeg_create_decompress 	|       ○       |            |
------------------------+---------------+------------+---------------------
jpeg_create_compress    |       ○       |            |
------------------------+---------------+------------+---------------------
jpeg_std_error          |       ○  	|	     |
------------------------+---------------+------------+---------------------
jpeg_std_dest           |       ○  	|            |
------------------------+---------------+------------+---------------------
jpeg_std_src            |       ○       |            |
------------------------+---------------+------------+---------------------
jpeg_mem_dest           |       ○       |            | API only present in
                        |               |            | libjpeg versions >=
                        |               |            | libjpeg-8b
------------------------+---------------+------------+---------------------
jpeg_mem_src            |       ○       |            | API only present in
                        |               |            | libjpeg versions >=
                        |               |            | libjpeg-8b
------------------------+---------------+------------+---------------------
jpeg_set_defaults       |       ○       |            |
------------------------+---------------+------------+---------------------
jpeg_set_colorspace     |               |     ○      | Always encode YCbCr 4:2:0
------------------------+---------------+------------+---------------------
jpeg_default_colorspace |               |     ○      | Always encode YCbCr 4:2:0
------------------------+---------------+------------+---------------------
jpeg_set_quality        |               |     ○      | Only default image
                        |               |            | quality supported
------------------------+---------------+------------+---------------------
jpeg_set_linear_quality |               |     ○      | Only default image
                        |               |            | quality supported
------------------------+---------------+------------+---------------------
jpeg_default_qtables    |               |     ○      | Only default image
                        |               |            | quality supported
                        |               |            | (version >= libjpeg-8b)
------------------------+---------------+------------+---------------------
jpeg_add_quant_table    |               |     ○      | Only default image
                        |               |            | quality supported
------------------------+---------------+------------+---------------------
jpeg_quality_setting    |               |     ○      | Only default image
                        |               |            | quality supported
------------------------+---------------+------------+---------------------
jpeg_simple_progression |               |     ○      | Progressive jpeg encoding
                        |               |            | not supported
------------------------+---------------+------------+---------------------
jpeg_suppress_tables    |               |     ○      | Only default quantization
                        |               |            | supported
------------------------+---------------+------------+---------------------
jpeg_alloc_quant_table  |               |     ○      | Only default quantization
                        |               |            | supported
------------------------+---------------+------------+---------------------
jpeg_alloc_huff_table   |               |     ○      | Only default quantization
                        |               |            | supported
------------------------+---------------+------------+---------------------
jpeg_start_compress     |       ○       |            |
------------------------+---------------+------------+---------------------
jpeg_write_scanlines    |       ○       |            |
------------------------+---------------+------------+---------------------
jpeg_finish_compress    |       ○       |            |
------------------------+---------------+------------+---------------------
jpeg_calc_jpeg_dimension|　             |     ○      | JPEG scaling is not
                        |               |            | supported so may return
                        |               |            | invalid values 
                        |               |            | (version >= libjpeg-8b)
------------------------+---------------+------------+---------------------
jpeg_core_output_dimensions　           |     ○      | JPEG scaling is not
                        |               |            | supported so may return
                        |               |            | invalid values
                        |               |            | (version >= libjpeg-8b)
------------------------+---------------+------------+---------------------
jpeg_calc_output_dimensions     ○       |            |
------------------------+---------------+------------+---------------------
jpeg_start_decompress   |       ○       |            |
------------------------+---------------+------------+---------------------
jpeg_read_scanlines     |       ○       |            |
------------------------+---------------+------------+---------------------
jpeg_finish_decompress  |       ○       |            |
------------------------+---------------+------------+---------------------
jpeg_abort_decompress   |       ○       |            |
------------------------+---------------+------------+---------------------
jpeg_abort_compress     |       ○       |            |
------------------------+---------------+------------+---------------------
jpeg_abort              |       ○       |            |
------------------------+---------------+------------+---------------------
jpeg_destroy            |       ○       |            |
------------------------+---------------+------------+---------------------

No other API functions are supported.

Colorspace
----------

The following decode/encode colorspaces are supported by libshjpeg

-------------+---------------------+---------------------------------------
image format |    H/W Accelerated  |    notes 	
-------------+---------------------+---------------------------------------
RGB24        |        ○            |    handled by JPU
YUYV 	     |        ○ 	   |    handled by JPU + S/W
grayscale    |        × 	   |    pass-through
YCCK         |        ×            |    pass-through
CMYK         |        ×            |    pass-through 
-------------+---------------------+---------------------------------------

As well as the following when using the direct hardware interface (not
via libjpeg)

     * NV12
     * NV16

5.1 Usage
=========
 * libshjpeg has two interfaces to the access the JPU.  The traditional 
   interface (available until version 1.2) remains, and can be used directly.  
   The libjpeg compatible version shouldn't require any modification to any 
   code that currently runs using libjpeg.  There are however, some limitations 
   when in using the libjpeg compatible interface.  These are detailed in the 
   next section.

6.1 Limitations
===============

 * No parallel processing -  Only one JPEG can be compressed/decompressed 
   at a time.  
	This means that once a call to 'jpeg_start_decompress' or 
	'jpeg_start_compress' is issued using a given cinfo context, no other 
	library calls can be made using a different context until the first 
	compression/decompression cycle is completed with a call to 
	'jpeg_finish_decompress'/'jpeg_finish_compress', 'jpeg_abort', or 
	'jpeg_destroy'

 * libjpeg virtual array mechanism not supported.
	The major effect of this is that scanline order would have to be 
	manually reversed in order to change the image data from top-to-
	bottom order to bottom-to-top order.
 
 * forcing colour and quality conversion on output.
	Currently, output JPEGs are always generated in YCrCb color format.  
	There is no support to force color data to grayscale output yet. 
	Likewise all output compression level cannot be adjusted.

  * EXIF/metadata support with libjpeg-62
	Due to a bug in the implementation of libjpeg version 62, JPEG images
	containing large amounts of EXIF or other meta data may not be
	properly decoded through the libjpeg interface of libshjpeg.
	Upgrading to a newer version or recompiling libjpeg-62 with the 
	patch supplied in this package will enable the metadata support. 
	(See "Compilation" for details).  Applications can also be written 
	to bypass the offending code.  See "libjpeg62 Application Workaround" 
	for more details.

6.2 libjpeg62 Application Workaround
====================================
Applications can override the skip_input_data function callback in
the jpeg_source_mgr to point to a corrected version of the function.

The override is performed by 

	<code>
        jpeg_stdio_src(&cinfo, infile); (or custom jpeg_source_mgr init)
	...
	cinfo.src->skip_input_data = my_skip_input_data;
 	</code>

where my_skip_input_data is a pointer to a function such as:

	<code>
	void my_skip_input_data (j_decompress_ptr cinfo, long num_bytes)
	{
	  if (num_bytes > 0) {
    	    while (num_bytes > (long) cinfo->src->bytes_in_buffer) {
              num_bytes -= (long) cinfo->src->bytes_in_buffer;
              (void) cinfo->src->fill_input_buffer(cinfo);
            }
            cinfo->src->next_input_byte += (size_t) num_bytes;
            cinfo->src->bytes_in_buffer -= (size_t) num_bytes;
          }
        }
	</code>

where the important points are: 
   *  all state (eg. next_input_byte, bytes_in_buffer, etc) 
      is saved in the jpeg_source_mgr 
   *  file read is via the fill_input_buffer function registered 
      in the jpeg_source_mgr

Please see tests/libjpeg_test.c for a working example of this.

7.1 Errors, Warnings, Information messages
==========================================

The libjpeg interface of libshjpeg adds its information messages to the same 
mechanism used for libjpeg.  Messages are delivered either through
jpeg_std_error the user specified error handler in the same way that libjpeg
messages are.
Trace messages are dispatched at error message level 1 by default.
The direct JPU access interface delivers messages to stderr.  

