RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

JPEG images


Introduction and Overview

The SpriteExtend module has been extended in RISC OS 3.6 to support JPEG images through a SWI interface.

JPEG is an international standard data format for the lossy compression of photographic data, capable of encoding colour images at screen resolutions using about 1½ - 2½ bits per pixel.

Because of the compression used, many of the operations you can perform on uncompressed bitmaps - such as sprites - are difficult or impossible to perform on JPEG images. This includes operations such as adding or deleting rows or columns, and arbitrary transformations. The support provided for JPEG images is therefore restricted in RISC OS 3.6 to providing information on them, and simple scaled plotting and printing.

The CompressJPEG module

A separate CompressJPEG module provides SWIs with which you can compress raw data into a JPEG image. See the chapter CompressJPEG for details both of the compression and decompression algorithms used with JPEGs, and of the SWIs it provides.

Technical details

SWI naming and numbering

Although the SpriteExtend module provides the JPEG SWIs, they use their own SWI chunk (base number &49980) and SWI name prefix ('JPEG_'). The SWIs are described below, from SWI Calls onwards.

The JPEG standard

The JPEG standard is split into two parts:

  • ISO DIS 10918-1, Digital Compression and Coding of Continuous-tone Still Images, Part 1: Requirements and guidelines.
  • ISO DIS 10918-2, Digital Compression and Coding of Continuous-tone Still Images, Part 2: Compliance testing.

At the time of going to press, Part 2 was still in draft stage.

You may also find these references useful:

  • The JPEG Still Picture Compression Standard / Gregory K Wallace
    in
    IEEE Transactions on Consumer Electronics, December 1991.
  • JPEG Still Image Data Compression Standard / William B. Pennebaker; Joan L. Mitchell. - New York, USA: Van Nostrand Reinhold, 1993.

JFIF files

The JPEG standard is wide-ranging in its scope, and allows many bizarre parameters and combinations. To limit these to more reasonable proportions various subsets of the standard have been defined. By far the most popular of these is the JFIF (JPEG File Interchange Format) standard, defined by C-Cube. This is widely used for the simple interchange of JPEG data; indeed, when people talk about 'JPEG files', they usually mean JFIF files.

The code in RISC OS modules only supports images that conform to version 1.02 or earlier of the JFIF standard. JFIF files are allocated the file type &C85; the textual equivalent is 'JPEG'. The sprite for this file type is included in the Wimp sprite pool.

Documentation of the JFIF standard is available as follows:

  • JPEG File Interchange Format (JFIF) / Eric Hamilton - version 1.02 - C-Cube Microsystems, 1778 McCarthy Blvd, Miltipas, CA 95035.

ChangeFSI and JPEG files

ChangeFSI can output JPEG files; these all conform to the JFIF standard.

ChangeFSI also accepts JPEG files as input. If a file only uses the JFIF subset of the JPEG standard, ChangeFSI fully understands it, and so correctly processes it. If a file uses features that are excluded from the JFIF subset, about which ChangeFSI does not know, it will make assumptions. Sometimes these will be correct, and so the file will be correctly processed; otherwise the file will be incorrectly processed.

Hence you cannot use ChangeFSI to test for JFIF-conformance. Some images that ChangeFSI correctly processes may be faulted by the SpriteExtend JPEG SWIs as not conforming to the JFIF standard.

Dithering of JPEGs

When you call the JPEG plotting SWIs you can set bit flags to request that when plotting to a shallow screen mode the output is dithered, with or without error diffusion. Three types of dithering are used:

Ordered dither

This is the simplest form of dithering available; it displays colours that are unavailable by using small patterns made up of the closest available colours. This is the default form of dithering, used in most cases when the dithering bit is set.

YUV error diffused dither

However, when decompressing a JPEG image into an 8bpp mode with the standard palette, an optimised mode is used. This uses a limited error diffusion technique directly on the YUV data in the JPEG, which vastly improves the appearance of the image. This technique will only work on JPEG images which have been compressed using an X and Y sample size of 2, as created both by the official Independent Group's software and by versions 1.03 onwards of ChangeFSI.

It is thus possible that two apparently similar JPEG images can give quite different display qualities because they are compressed differently, and so RISC OS can only apply YUV error diffusion to one of them.

Full error diffused dither

If you set both the dithering and error diffusion bits, then this slower but more accurate form of dithering is used. Speed and space considerations mean that the output image will still not be quite so high a quality as ChangeFSI can produce.

Under RISC OS 3.6 full error diffused dithering can only be used when plotting to an 8bpp screen mode.

SWI Calls


JPEG_Info
(SWI &49980)

Gives information on a JPEG image held in a buffer

On entry

R0 = flags for desired operation:

bit 0 set => RETURN DIMENSIONS_ CLEAR => don't return dimensions
all other bits reserved (must be zero)
R1 = pointer to buffer holding JPEG image
R2 = length of JPEG image, in bytes

On exit

R0 = returned information flags:

bit 0 set => GREYSCALE IMAGE_ CLEAR => colour image
bit 1 set => TRANSFORMED PLOTS NOT SUPPORTED_ CLEAR => supported
bit 2 set => PIXEL DENSITY IS A SIMPLE RATIO_ CLEAR => pixel density is in dpi
R1 preserved
R2 = width, in pixels (if R0 bit 0 set on entry)
R3 = height, in pixels (if R0 bit 0 set on entry)
R4 = x pixel density
R5 = y pixel density
R6 = SpriteExtend's additional extra workspace requirements to plot JPEG
(0 => no additional extra workspace required)

Interrupts

Interrupt status is undefined
FIQs are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call gives information on a JPEG image held in a buffer in memory.

It checks the header enough to return the width and height, and does a partial validation of the data. It returns an error if the image appears to be invalid; if no error is returned you may assume that the data is a JPEG image.

This call is only available from RISC OS 3.6 onwards.

Related SWIs

JPEG_FileInfo

Related vectors

None


JPEG_FileInfo
(SWI &49981)

Gives information on a JPEG image held in a file

On entry

R0 = flags for desired operation:

bit 0 set => RETURN DIMENSIONS_ CLEAR => don't return dimensions
all other bits reserved (must be zero)
R1 = pointer to pathname of JPEG file, control character terminated

On exit

R0 = returned information flags:

bit 0 set => GREYSCALE IMAGE_ CLEAR => colour image
bit 1 set => TRANSFORMED PLOTS NOT SUPPORTED_ CLEAR => supported
bit 2 set => PIXEL DENSITY IS A SIMPLE RATIO_ CLEAR => pixel density is in dpi
R1 preserved
R2 = width, in pixels
R3 = height, in pixels
R4 = x pixel density
R5 = y pixel density
R6 = SpriteExtend's additional extra workspace requirements to plot JPEG (0 => no additional extra workspace required)

Interrupts

Interrupt status is undefined
FIQs are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call gives information on a JPEG image held in a file.

This call checks the header enough to return the width and height, and does a partial validation of the data. It returns an error if the image appears to be invalid; if no error is returned you may assume that the data is a JPEG image.

This call is only available from RISC OS 3.6 onwards.

Related SWIs

JPEG_Info

Related vectors

None


JPEG_PlotScaled
(SWI &49982)

Decompresses, scales, and plots on the screen a JPEG image held in a buffer

On entry

R0 = pointer to buffer holding JPEG image
R1 = x coordinate at which to plot
R2 = y coordinate at which to plot
R3 = pointer to scale factors (see Scale factors): 0 => no scaling
R4 = length of JPEG image, in bytes
R5 = flags:

bit 0 set => dither output when plotting 24 bit JPEG at 16bpp or below
bit 1 set => dithering (if any) is full error diffused when plotting at 8bpp
all other bits reserved (must be zero)
On exit

R0 - R5 preserved

Interrupts

Interrupt status is undefined
FIQs are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This SWI decompresses, scales, and plots on the screen a JPEG image held in a buffer in memory.

The functionality of this call for JPEGs is similar to that of OS_SpriteOp 52 (Put sprite scaled) for sprites. The scale factors and the coordinates have exactly the same meaning, and the scaling algorithms used are the same in both calls. However, this call only supports a direct plot (ie plot action 0 of OS_SpriteOp 52).

In plotting the JPEG, the SpriteExtend module may claim extra workspace in a dynamic area to store tables etc. It keeps these cached until either it is asked to plot a different JPEG, or the user decreases the dynamic area's size. This speeds up successive replots of the same JPEG. You can find how much extra workspace SpriteExtend will require - if any - by first calling JPEG_Info or JPEG_FileInfo. You can hence ensure there is sufficient free memory before making this call.

This call returns an error if it cannot claim sufficient memory to plot the JPEG image, or if the image appears incomplete or corrupt in some way.

This call is only available from RISC OS 3.6 onwards.

Related SWIs

JPEG_Info, JPEG_FileInfo

Related vectors

None


JPEG_PlotFileScaled
(SWI &49983)

Decompresses, scales, and plots on the screen a JPEG image held in a file

On entry

R0 = pointer to pathname of JPEG file, control character terminated
R1 = x coordinate at which to plot
R2 = y coordinate at which to plot
R3 = pointer to scale factors (see Scale factors): 0 => no scaling
R4 = flags:

bit 0 set => dither output when plotting 24 bit JPEG at 16bpp or below
bit 1 set => dithering (if any) is full error diffused when plotting at 8bpp
all other bits reserved (must be zero)
On exit

R0 - R4 preserved

Interrupts

Interrupt status is undefined
FIQs are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This SWI decompresses, scales, and plots on the screen a JPEG image held in a file.

The functionality of this call for JPEGs is similar to that of OS_SpriteOp 52 (Put sprite scaled) for sprites. The scale factors and the coordinates have exactly the same meaning, and the scaling algorithms used are the same in both calls. However, this call only supports a direct plot (ie plot action 0 of OS_SpriteOp 52).

The file is loaded into memory for the duration of the call, but is not cached. This call therefore uses as much memory as loading the file into a buffer yourself and then calling JPEG_PlotScaled, and gives you no control over whether the image remains cached. Furthermore, although the mechanism exists to pass this call on to the printer drivers, they do not support it. We therefore strongly recommend that you use JPEG_PlotScaled in preference to this call.

As well as the memory to hold the file, the SpriteExtend module may claim extra workspace in a dynamic area to store tables etc. It keeps these cached until either it is asked to plot a different JPEG, or the user decreases the dynamic area's size. This speeds up successive replots of the same JPEG. You can find how much extra workspace SpriteExtend will require - if any - by first calling JPEG_Info or JPEG_FileInfo. You can hence ensure there is sufficient free memory before making this call: enough both to hold the file, and to provide any extra workspace required.

This call returns an error if it cannot claim sufficient memory to plot the JPEG image, or if the image appears incomplete or corrupt in some way.

This call is only available from RISC OS 3.6 onwards.

Related SWIs

JPEG_PlotScaled

Related vectors

None


JPEG_PlotTransformed
(SWI &49984)

Decompresses, transforms, and plots on the screen a JPEG image held in a buffer

On entry

R0 = pointer to buffer holding JPEG image
R1 = flags:

bit 0 set => R2 = pointer to destination coordinate block, else to matrix
bit 1 set => dither output when plotting 24 bit JPEG at 16bpp or below
bit 2 set => dithering (if any) is full error diffused when plotting at 8bpp
all other bits reserved (must be zero)
R2 = pointer to destination coordinate block (if R2 bit 0 set), or pointer to Draw-style transformation matrix (if R2 bit 0 clear)
R3 = length of JPEG image, in bytes

On exit

R0 - R3 preserved

Interrupts

Interrupt status is undefined
FIQs are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This SWI decompresses, transforms, and plots on the screen a JPEG image held in a buffer in memory.

The functionality of this call for JPEGs is similar to that of OS_SpriteOp 56 (Put sprite transformed) for sprites. The destination coordinate block and the transformation matrix have exactly the same meaning. However, this call only supports a direct plot (ie plot action 0 of OS_SpriteOp 56).

Under RISC OS 3.6 this call only supports simple scaling, with no rotation or other transformation involved. Any unsupported transformation gives an appropriate error.

In plotting the JPEG, the SpriteExtend module may claim extra workspace in a dynamic area to store tables etc. It keeps these cached until either it is asked to plot a different JPEG, or the user decreases the dynamic area's size. This speeds up successive replots of the same JPEG. You can find how much extra workspace SpriteExtend will require - if any - by first calling JPEG_Info or JPEG_FileInfo. You can hence ensure there is sufficient free memory before making this call.

This call returns an error if it cannot claim sufficient memory to plot the JPEG image, or if the image appears incomplete or corrupt in some way.

This call is only available from RISC OS 3.6 onwards.

Related SWIs

JPEG_Info, JPEG_FileInfo, JPEG_PlotScaled

Related vectors

None


JPEG_PlotFileTransformed
(SWI &49985)

Decompresses, transforms, and plots on the screen a JPEG image held in a file

On entry

R0 = pointer to pathname of JPEG file, control character terminated
R1 = flags:

bit 0 set => R2 = pointer to destination coordinate block, else to matrix
bit 1 set => dither output when plotting 24 bit JPEG at 16bpp or below
bit 2 set => dithering (if any) is full error diffused when plotting at 8bpp
all other bits reserved (must be zero)
R2 = pointer to destination coordinate block (if R2 bit 0 set), or pointer to Draw-style transformation matrix (if R2 bit 0 clear)

On exit

R0 - R2 preserved

Interrupts

Interrupt status is undefined
FIQs are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This SWI decompresses, transforms, and plots on the screen a JPEG image held in a file.

The functionality of this call for JPEGs is similar to that of OS_SpriteOp 56 (Put sprite transformed) for sprites. The destination coordinate block and the transformation matrix have exactly the same meaning. However, this call only supports a direct plot (ie plot action 0 of OS_SpriteOp 56).

Under RISC OS 3.6 this call only supports simple scaling, with no rotation or other transformation involved. Any unsupported transformation gives an appropriate error.

The file is loaded into memory for the duration of the call, but is not cached. This call therefore uses as much memory as loading the file into a buffer yourself and then calling JPEG_PlotTransformed, and gives you no control over whether the image remains cached. Furthermore, although the mechanism exists to pass this call on to the printer drivers, they do not support it. We therefore strongly recommend that you use JPEG_PlotTransformed in preference to this call.

As well as the memory to hold the file, the SpriteExtend module may claim extra workspace in a dynamic area to store tables etc. It keeps these cached until either it is asked to plot a different JPEG, or the user decreases the dynamic area's size. This speeds up successive replots of the same JPEG. You can find how much extra workspace SpriteExtend will require - if any - by first calling JPEG_Info or JPEG_FileInfo. You can hence ensure there is sufficient free memory before making this call: enough both to hold the file, and to provide any extra workspace required.

This call returns an error if it cannot claim sufficient memory to plot the JPEG image, or if the image appears incomplete or corrupt in some way.

This call is only available from RISC OS 3.6 onwards.

Related SWIs

JPEG_PlotTransformed

Related vectors

None


JPEG_PDriverIntercept
(SWI &49986)

Requests that SpriteExtend passes on all calls to JPEG plotting SWIs

On entry

R0 = flags:

bit 0 set => PASS ON PLOTTING CALLS_ CLEAR => don't pass on plotting calls
bit 1 set => USE TRANSLATION TABLES_ CLEAR => don't use translation tables
all other bits reserved (must be zero)
On exit

R0 = previous intercept state

Interrupts

Interrupt status is undefined
FIQs are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This SWI is used by the printer drivers to request that SpriteExtend passes on all calls to JPEG plotting SWIs by itself calling PDriver_JPEGSWI. When SpriteExtend passes on these calls, it ignores them itself.

You must not make this call from your own applications.

The JPEG plotting SWIs (ie those that are passed on) are listed in Related SWIs below.

Related SWIs

JPEG_PlotScaled, JPEG_PlotFileScaled JPEG_PlotTransformed, JPEG_PlotFileTransformed

Related vectors

None

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015