UsageApplication

Usage of console application

The console application gpujpeg uses libgpujpeg library to demonstrate it's functions. To build console application check Requirements and go to gpujpeg directory (where README and LICENSE files are placed) and run 'make' command. It builds libgpugjpeg library in subdirectory ./libgpujpeg/ and it creates executable file ./gpujpeg and run script ./gpujpeg.sh, which runs executable file linked to runtime library libgpujpeg.so (which is placed in ./libgpujpeg/ subdirectory).

Requirements

To be able to build and run libgpujpeg library and gpujpeg console application you need:

• CUDA Toolkit (http://developer.nvidia.com/cuda-toolkit) installed (which contains NPP libraray), default installation path is /usr/local/cuda. If you have the CUDA installed somewhere else, you need to specify it by environment variable CUDA_INSTALL_PATH or in Makefiles by CUDA_INSTALL_PATH variable.
• NVIDIA developer drivers
• CUDA enabled NVIDIA GPU

The libgpujpeg library uses NVIDIA Performance Primitives library, but it is included in CUDA toolkit. There were some build error in npp headers when using some specific versions of GCC and NPP library. If you encounter these kind of problem, try to use the newest version of CUDA toolkit or older version of GCC.

Usage

To encode image from raw RGB image file to JPEG image file use following command:

./gpujpeg.sh --encode --size=WIDTHxHEIGHT --quality=QUALITY \ 
          INPUT_IMAGE.rgb OUTPUT_IMAGE.jpg

You must specify input image size by --size=WIDTHxHEIGHT parameter. Optionally you can specify desired output quality by parameter --quality=QUALITY which accepts values 0-100. Console application accepts a few more parameters and you can list them by folling command:

./gpujpeg.sh --help

To decode image from JPEG image file to raw RGB image file use following command:

./gpujpeg.sh --decode OUTPUT_IMAGE.jpg INPUT_IMAGE.rgb

You can also encode and decode image to test the console application:

./gpujpeg.sh --encode --decode --size=WIDTHxHEIGHT --quality=QUALITY \
        INPUT_IMAGE.rgb OUTPUT_IMAGE.jpg

Decoder will create new decoded file OUTPUT_IMAGE.jpg.decoded.rgb and do not overwrite your INPUT_IMAGE.rgb file. Console application is able to load raw RGB image file data from .rgb files and raw YUV and YUV422 data from .yuv files. For YUV422 you must specify *.yuv file and use '--sampling-factor=4:2:2' parameter.

All supported parameters for console application are following:

• --help
  
  Prints console application help
• --size=1920x1080
  
  Input image size in pixels, e.g. 1920x1080
• --sampling-factor=4:4:4
  
  Input image sampling factor (supported are '4:4:4' and '4:2:2')
• --colorspace=rgb
  
  Input image colorspace (supported are 'rgb', 'yuv' and 'ycbcr-jpeg',
  where 'yuv' means YCbCr ITU-R BT.601), when *.yuv file is specified,
  instead of default 'rgb', automatically the colorspace 'yuv' is used
• --quality
  
  Set output quality level 0-100 (default 75)
• --restart=8
  
  Set restart interval for encoder, number of MCUs between
  restart markers
• --chroma-subsampling
  
  Produce chroma subsampled JPEG stream
• --interleaving
  
  Produce interleaved stream
• --encode
  
  Encode images
• --decode
  
  Decode images
• --device=0
  
  By using this parameter you can specify CUDA device id which will
  be used for encoding/decoding.

Restart interval is important for parallel huffman encoding and decoding. When '--restart=N' is used (default is 8), the coder can process each N MCUs independently, and so he can code each N MCUs in parallel. When '--restart=0' is specified, restart interval is disabled and the coder must use CPU version of huffman coder (because on GPU would run only one thread, which is very slow).

The console application can encode/decode multiple images by following command:

./gpujpeg.sh ARGUMENTS INPUT_IMAGE_1.rgb OUTPUT_IMAGE_1.jpg \
        INPUT_IMAGE_2.rgb OUTPUT_IMAGE_2.jpg ...