|
www.riscos.com Technical Support: |
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.
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.
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 is split into two parts:
At the time of going to press, Part 2 was still in draft stage.
You may also find these references useful:
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:
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.
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:
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.
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.
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.
R0 = flags for desired operation:
RETURN DIMENSIONS_ CLEAR don't return dimensionsR0 = returned information flags:
GREYSCALE IMAGE_ CLEAR colour image TRANSFORMED PLOTS NOT SUPPORTED_ CLEAR supported PIXEL DENSITY IS A SIMPLE RATIO_ CLEAR pixel density is in dpi
no additional extra workspace required)
Interrupt status is undefined
FIQs are enabled
Processor is in SVC mode
Not defined
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.
None
Gives information on a JPEG image held in a file
R0 = flags for desired operation:
RETURN DIMENSIONS_ CLEAR don't return dimensionsR0 = returned information flags:
GREYSCALE IMAGE_ CLEAR colour image TRANSFORMED PLOTS NOT SUPPORTED_ CLEAR supported PIXEL DENSITY IS A SIMPLE RATIO_ CLEAR pixel density is in dpi
no additional extra workspace required)
Interrupt status is undefined
FIQs are enabled
Processor is in SVC mode
Not defined
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.
Decompresses, scales, and plots on the screen a JPEG image held in a buffer
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:
dither output when plotting 24 bit JPEG at 16bpp or below dithering (if any) is full error diffused when plotting at 8bppR0 - R5 preserved
Interrupt status is undefined
FIQs are enabled
Processor is in SVC mode
Not defined
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.
None
Decompresses, scales, and plots on the screen a JPEG image held in a file
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:
dither output when plotting 24 bit JPEG at 16bpp or below dithering (if any) is full error diffused when plotting at 8bppR0 - R4 preserved
Interrupt status is undefined
FIQs are enabled
Processor is in SVC mode
Not defined
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.
Decompresses, transforms, and plots on the screen a JPEG image held in a buffer
R0 = pointer to buffer holding JPEG image
R1 = flags:
R2 = pointer to destination coordinate block, else to matrix dither output when plotting 24 bit JPEG at 16bpp or below dithering (if any) is full error diffused when plotting at 8bppR0 - R3 preserved
Interrupt status is undefined
FIQs are enabled
Processor is in SVC mode
Not defined
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.
None
Decompresses, transforms, and plots on the screen a JPEG image held in a file
R0 = pointer to pathname of JPEG file, control character terminated
R1 = flags:
R2 = pointer to destination coordinate block, else to matrix dither output when plotting 24 bit JPEG at 16bpp or below dithering (if any) is full error diffused when plotting at 8bppR0 - R2 preserved
Interrupt status is undefined
FIQs are enabled
Processor is in SVC mode
Not defined
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.
Requests that SpriteExtend passes on all calls to JPEG plotting SWIs
R0 = flags:
PASS ON PLOTTING CALLS_ CLEAR don't pass on plotting calls USE TRANSLATION TABLES_ CLEAR don't use translation tablesR0 = previous intercept state
Interrupt status is undefined
FIQs are enabled
Processor is in SVC mode
Not defined
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.
JPEG_PlotScaled, JPEG_PlotFileScaled JPEG_PlotTransformed, JPEG_PlotFileTransformed