CompressJPEG

Contents

• Introduction and Overview
• Technical Details
  • How JPEG images are compressed
• SWI calls
  • CompressJPEG_Start
  • CompressJPEG_WriteLine
  • CompressJPEG_Finish
  • CompressJPEG_Comment
  • CompressJPEG_WriteLineExtended
• Example program

Introduction and Overview

The CompressJPEG module is available from RISC OS 3.6 onwards. It provides SWIs with which you can compress raw image data into a JPEG image. It is a port of release 5 of the Independent JPEG Group's software.

The module is not in the RISC OS 3.6 ROM, but is instead held in the System application. If you wish to use the module in a program, you should first use the following command to ensure it is loaded:

RMEnsure CompressJPEG 0.00 RMLoad System:Modules.JCompMod

To compress raw image data into a JPEG image, you start by calling CompressJPEG_Start, which sets up the compression environment. You then compress each row of the source image with a separate call to CompressJPEG_WriteLine, or multiple rows at once with CompressJPEG_WriteLineExtended. Finally you finish the compression by calling CompressJPEG_Finish.

Technical Details

How JPEG images are compressed

JPEG files encode colour pictures as YUV (Y = intensity, U and V are colour) data. Compressing involves the following steps:

1. Convert RGB data to YUV.
2. Throw away 3 out of 4 of the U and V pixels.
3. Convert 8 × 8 tiles of Y, U and V values through a Discrete Cosine Transform, into an 8 × 8 square of frequency coefficients.
4. Discard coefficients which are zero, or close to zero. This will tend to change the visual appearance of the picture very little.
5. Reduce the accuracy with which the remaining coefficients are held (known as 'quantisation'). Again, this changes the appearance very little. The amount by which this is done, controls the compression factor of the image. By now, most of the coefficients will be zero.
6. Reorder the 64 coefficients in a zig-zag order, which increases the average length of runs of zeros in the coefficient block.
7. Huffman-encode the resulting stream of values.

(Incidentally, decompression involves reversing these steps.)

SWI calls

---

CompressJPEG_Start
(SWI &4A500)

Starts the JPEG compression process, setting up various parameters for it

On entry

R0	=	pointer to buffer for JPEG data
R1	=	size of JPEG data buffer
R2	=	pointer to block of parameters: Offset Contents +0 width of image in pixels +4 height of image in pixels +8 quality value (0 - 100): lower quality results in a smaller image +12 number of 8 bit components in source: Components Meaning 1 24 bit colour 3 8 bit greyscale +16 horizontal DPI of image, or 0 if unknown +20 vertical DPI of image, or 0 if unknown
R3	=	pointer to workspace area, or 0 for the CompressJPEG module to allocate its own workspace from the RMA
R4	=	size of workspace area (if R3 <> 0)

On exit

R0	=	JPEG tag, to be passed to other CompressJPEG SWIs
R1-3	preserved

Interrupts

Interrupts are undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call starts the JPEG compression process, setting up various parameters for it.

The buffer for the JPEG data should be as large as possible, since the JPEG compression routines cannot guarantee to compress the image by a fixed amount.

If you wish to supply your own workspace area, its required size for a colour (24 bit) image is:

20000 + ((image width rounded up to a multiple of 16) × 30)

and its required size for a greyscale (8bit) image is:

20000 + ((image width rounded up to a multiple of 16) × 9)

An error is returned if the workspace area becomes full.

Related SWIs

CompressJPEG_WriteLine, CompressJPEG_WriteLineExtended, CompressJPEG_Finish

Example program

The pseudo-code below shows you how you might convert a 32 bpp sprite into a JPEG:

/* Pseudo C code for converting a 32bpp sprite to a JPEG */
JPEG_buffer      = <Allocate buffer for JPEG>;
workspace_buffer = <Allocate buffer for workspace>;

line_buffer      = <Allocate buffer for line of source pixels>;
argument_block arguments;
arguments.width          = sprite_width_in_pixels;
arguments.height         = sprite_height_in_pixels;
arguments.quality        = quality;
arguments.components     = 3;
arguments.horizontal_dpi = 0;
arguments.vertical_dpi   = 0;
sprite_pointer = start_of_data_within_sprite;
JPEG_tag = CompressJPEG_Start(JPEG_buffer,
                              JPEG_buffer_size,
                              arguments,
                              workspace_buffer,
                              workspace_buffer_size);
for loop = 1 to sprite_height_in_pixels
{
  convert_sprite_data_to_rgb(sprite_pointer, line_buffer);
  CompressJPEG_WriteLine(JPEG_tag, line_buffer);
  sprite_pointer += sprite_width_in_words;
}
CompressJPEG_Finish(JPEG_tag);

Document information

Maintainer(s):	RISCOS Ltd <developer@riscos.com>
History:	Revision Date Author Changes 1 ROL Initial version
Disclaimer:	Copyright © Pace Micro Technolgy plc, 2002. Portions copyright © RISCOS Ltd, 2002. Published by RISCOS Limited. No part of this publication may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, or stored in any retrieval system of any nature, without the written permission of the copyright holder and the publisher, application for which shall be made to the publisher.