The Image File Renderer


Contents


Introduction and Overview

A number of graphics formats are supported natively by RISC OS. JPEG, DrawFiles and Sprites are directly renderable, and PNGs are supported through a number of conversion calls. Each of these formats, however, is rendered using slightly different calls. The ImageFileRender module simplifies rendering these (and potentially other third party) image files.

All graphics formats have two things in common :

  • They cover a region (even empty files must say what space they cover).
  • They have a resolution at which they are drawn.

The region they cover is known as the 'bounding box'. For many graphics formats, this will be aligned with the origin - for example a bitmap graphic. For others, this bounding box may be elsewhere in the image - for example vector formats such as DrawFiles.

The resolution at which they have been drawn describes how accurately the images is stored. Usually this is stored in 'dots per inch' (DPI) along with the image itself. Screen resolution is usually - this depends on the eigenfactors for the screen mode in use - treated as 90 DPI. Some formats may use much more accurate internal representations than this; for example DrawFiles are stored at 2048 DPI.

For the purposes of rendering the image file, we ignore the colour depth because the rendering process will generate its results in the most accurate manner possible for output depth.

Images may be rendered using a number of transformation types, allowing them to be rendered to fit a region, to a scale, or using a more general transformation.

Within each image file there may be a number of individual images. These can be accessed by a sequence number which indicates their logical location within the file. The images may be related - as would be the case with frames of an animation - or they may be unrelated - as would be the case with a collection of resources.

When accessing images, additional information may be provided to the renderer which may perform specific operation on the image. This extra data is specific to the renderer and cannot be handled generically.


Technical Details

Sequence numbers

Graphics files may contain multiple logical images which may either be frames of an animation, alternate versions, or other image resources. These images are accessed through a sequence number which must be supplied to all images. A sequence number of 0 will render the 'default' image within the file. This may be the first image in some formats, the last in others, or some arbitrary image. A sequence number higher than that of the last image should be treated as the last image. A sequence number of 1 indicates the first image should be processed.

Rendering quality

Image files may contain data which is more accurate than can be represented by the display. This is usually the case for bitmap images at high colour depths and almost always the case for bitmap images. In order to allow some control over the quality of the rendered image (and usually the rendering speed) a 'quality' parameter can be provided to the renderer. This is a value from 1 to a renderer specific limit (with a maximum of 15) and will be bounded to the maximum that the renderer supports. Thus, if the highest quality is required, a value of 15 should be supplied. If the lowest quality is required, a value of 1 should be supplied. In the majority of cases, however, the 'default' will be required. This is a value which the renderer feels is suitable for most operations and does not require excessive processing to complete. To request the default quality, a value of 0 should be specified as the quality.

Transformation types

Graphics files may be transformed in a number of ways. This allows us to provide a simpler interface for rendering based on the requirements of the application. At present, there are three transformation types provided by the module:

ValueMeaning
0Render to fit
1Render scaled
2Render transformed

For all rendering types an x and y origin are supplied from which all operations will be based. This allows the same details to be used for the fit, scale or transform regardless of the images location on the screen.

Render to fit

When rendering to fit, a width and height must be supplied by the application. The image file will be scaled to fit within this region. In addition, a border and angle may be provided to specify an area around the image which should be left clear, and to specify the angle through which the image should be rotated.

Rotation is performed anti-clockwise. The centre of the rotation is not strictly relevant to this operation because the image is always scaled to fit the width and height supplied.

The 'fit' block has the following structure:

OffsetContents
+0width (in OS units)
+4height (in OS units)
+8border (to apply to all edges)
+12angle (in degrees clockwise, as a 16.16 fixed point value)

As the shape is scaled to fit the size specified, the point about which rotation occurs is not important. It can be considered to be the centre of the image.

Render scaled

When rendering scaled, a pair of multiplication and division factors should be supplied which describe the scale at which the image should be rendered. The scale block is a standard RISC OS scale block (as used by SpriteExtend)

The scaling block has the following structure :

OffsetContents
+0X multiplication factor
+4Y multiplication factor
+8X division factor
+12Y division factor

Render transformed

Rendering images through a transformation matrix is the most flexible method of rendering that the ImageFileRender module provides. Transformation matrices are provided in standard RISC OS tranformation blocks (as used by SpriteExtend, Draw, DrawFile and others).

The transformation has the following structure:

OffsetContents
+0m00
+4m10
+8m01
+12m11
+16m20
+20m21

where the matrix is constructed:

{ m00, m01, 0 }

{ m10, m11, 0 }

{ m20, m21, 1 }

m00, m01, m10, and m11 are 16.16 fixed point values.

m20 and m21 are 24.8 fixed point values.

Arbitrary transformations

Not all image formats support arbitrary transformations. Because of this, certain formats will be unable to render when a complex transformation is in use. A typical example of such limitations is that of JPEGs. The internal renderer can only render JPEGs as a scaled object. If rotation, or other complex transformations are applied to files which are not capable of those transformations, an error will be returned.

Clipping

All images will be clipped to the standard graphics rectangles. If an image must not pass outside a region, a graphics window should be used. This can be set through a VDU 24 sequence.

Image file origins

Whilst most images are based at the origin, some images will have a bounding box which are not. When the image is rendered 'to fit', the image origin is implicitly ignored. When scaling and transforming however, the origin is maintained and will be scaled with the image itself. Because this can make manipulating such images more complex, this origin offset can be negated by the ImageFileRender module. In this mode, the image can be treated as if it does not have any offset from the origin.

Colour mapping

In order to provide highlighting and other colour manipulation on the image, the ImageFileRender module can use colour mapping functions (as used by SpriteExtend, DrawFile, and ColourTrans). These allow the colours in the image to be manipulated to provide effects such as highlighting or shading.

Extensions for more complex colour mapping

The operations that can be provided in a generic manner by the ImageFileRender module do not cover the full range of operations that might be applied to every image file format. Because of this, extension data may be provided which is specific to the renderer in use. Because each renderer may provide specific data to enable it to render images, and there may be multiple providers of rendering facilities, a 'magic' identifier is allocated to each renderer. This is ensures the the renderer is not given data in a form which it does not understand.

Where a magic identifier is supplied and a suitable renderer is available, it will be used. If no suitable renderer can be found, the last registered renderer will be used. This ensures that the where extension data is used it is passed to the appropriate renderer, and falls back to using the most recent renderer installed.

The extension data block must be word aligned, and the first word contains the magic identifier for the render that it is intended for. The remainder of the extension data block is specific to the renderer in use.

The magic identifier may be any 32bit value, but we recommend that these are registered with RISCOS Ltd to ensure that there are no duplicated identifiers. At present, allocations are of the form &6699ccii, where cc indicates the company or individual producing the renderer, and ii is some image format number at the company or individual's discretion.

Sprite file extensions

When rendering sprite files, by default the first sprite is rendered from the file. This covers the majority of the situations that it will be required, but where different sprites are required, the extension block describes which to use. The identifier for the RISCOS Ltd sprite renderer is &66990101. The named sprite will only be used when the sequence number is left as 'default'.

OffsetContents
+0&66990101
+4Sprite name, up to 12 characters

Renderers

Custom renderers

Custom renderers may be registered with the ImageFileRender module. These renderers can provided additional rendering facilities for third party filetypes, or provide additional facilities over those of the standard renderers.

Renderers have four components:

  1. A routine which calculates the bounding box and resolution of an image
  2. A routine which renders an image
  3. A routine which declares fonts in a document (may be omitted)
  4. A routine which returns information about an image

In addition, they provide a number of informational fields which describe the renderer's capabilities:

  • The filetype that the renderer applies to
  • The name of the renderer (including the version and author)
  • A flags word that describes the renderers capabilities
  • The renderers 'magic' identifier (or 0 if it provides no special operations)

Renderer name

The renderer name provides details about the renderer in order that diagnostics may be performed and information about the installed renderers is available. The renderer name consists of three, tab (ASCII 9) separated, fields:

  • The renderer name
  • The version number in the form x.xx
  • The authors (or publishers) name

Renderer flags

Not all renderers have the same capabilities, as stated earlier. The flags provide details to ImageFileRender of the capabilities of the renderer. This is a bit field, structured:

Bit(s)Meaning
0-1

Renderer transformation capabilities:

ValueMeaning
0Renderer cannot draw anything but identity scaling and translation
1Renderer can translate and scale, but scaling must be by identical factors
2Renderer can translate and scale by any values in both axes
3Renderer supports any form of transformation

These bits should be set to the capabilities of the renderer.

Attempts to render files of which the capabilities word indicates are not possible by the renderer will be faulted by ImageFileRender module.

2

Renderer supports colour mapping.

This bit should be set if the renderer can perform colour mapping. If unset, attempts to use colour mapping on this file type will be faulted by ImageFileRender.

3

Renderer can draw irregular shapes so must be called to calculate bounding boxes.

This bit should be set if transforming a shape using a complex matrix (eg skew or rotate) may result in a different bounding box than that which would be generated for a rectangular area. If unset, the renderer will be called to calculate the bounds of an identity transform only. ImageFileRender will perform the remainder of the calculations.

If a renderer can only render rectangular areas then leaving this bit clear simplifies the implementation.

4-7

Maximum number of 'quality' levels supported (1-15).

The highest quality level which is supported by the renderer.

If the quality level requested by a client exceeds this, the renderer will be called with this value.

8-11

Default 'quality' level to use (1-15).

Where quality settings are omitted (ie when 'default' quality is selected) the default quality will be passed to the renderer. A value of 0 means that quality levels are ignored.


Service calls


Service_ImageFileRender_Started
(Service &80D40)

ImageFileRenderer has initialised
On entry
R0=API version (102 at present)
R1=&80D40
On exit
None
Use

This service is issued after the ImageFileRender module has initialised. Renderers should register themselves with the module.

Related services
Service_ImageFileRender_Dying

Service_ImageFileRender_Dying
(Service &80D41)

ImageFileRenderer about to finalise
On entry
R0=API version (102 at present)
R1=&80D41
On exit
None
Use

This service is issued as the ImageFileRender module finalises to notify clients that it is no longer providing rendering facilities.

Related services
Service_ImageFileRender_Started

Service_ImageFileRender_RendererChanged
(Service &80D42)

A renderer has initialised or finalised
On entry
R0=API version (102 at present)
R1=&80D42
R2=Filetype affected
On exit
None
Use

This service is issued when a renderer registers or deregisters with the ImageFileRender module. Clients which have cached details of other renderers should re-read any renderer values necessary after checking whether the filetype matches those which they are interested in.

Related SWIs
ImageFileRender_Register

SWI calls


ImageFileRender_Render
(SWI &562C0)

Render an image
On entry
R0=Rendering flags:
Bit(s)Meaning
0-2Transformation type:
ValueMeaning
0Render to fit
1Render scaled
2Render transformed
3-7Reserved
3Colour mapping function supplied
4Ignore document origin
5Reserved, must be zero
6-9Quality to render at:
ValueMeaning
0Use default quality
1Lowest quality
2-14Renderer specific values
15Highest quality
10-16Reserved, must be zero
17-31Reserved, must be zero
R1=Filetype
R2=Pointer to data to render
R3=Length of data
R4=Pointer to extension data, or 0 if none
R5=Image sequence number, or 0 for default image
R6=X coord for origin
R7=Y coord for origin
R8=Transformation data:
ValueNameTransformation type in R0
0Pointer to sizeImage file origin is ignored
1Pointer to scale block
OffsetContents
+0X mult
+4Y mult
+8X div
+12Y div
2Pointer to transformation matrixStandard draw transformation matrix format
R9=Pointer to colour map descriptor
On exit
None
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use

This SWI is used to render an image file.

Related entry points
IFR_Render

ImageFileRender_BBox
(SWI &562C1)

Calculates an image's bounding box
On entry
R0=Rendering flags:
Bit(s)Meaning
0-2Transformation type:
ValueMeaning
0Render to fit
1Render scaled
2Render transformed
3-7Reserved
3Reserved, must be zero
4Ignore document origin
5Return in OS units (otherwise bounding box will be returned in draw units
6-31Reserved, must be zero
R1=Filetype
R2=Pointer to data to render
R3=Length of data
R4=Pointer to extension, or 0 if none
R5=Image sequence number, or 0 for default image
R6=Pointer to transformation data (see above)
R7=Pointer to bounding box to fill in
On exit
None
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use

This SWI is used to calculate the bounding box for a transformation operation.

Related entry points
IFR_BBox

ImageFileRender_Transform
(SWI &562C2)

Return transformation matrix for render operation
On entry
R0=Rendering flags:
Bit(s)Meaning
0-2Transformation type:
ValueMeaning
0Render to fit
1Render scaled
2Render transformed
3-7Reserved
3Reserved, must be zero
4Ignore document origin
5-31Reserved, must be zero
R1=Filetype
R2=Pointer to data to render
R3=Length of data
R4=Pointer to extension, or 0 if none
R5=Image sequence number
R6=Pointer to transformation data
R7=Pointer to output transformation block to fill in
On exit
None
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use

This SWI is used to calculate the transformation matrix that would be used for an operation without performing that operation. Where clients wish to combine a transform matrix with the operation applied by the scaling specified, this call can obtain the transformation matrix which ImageFileRender will use.

Related APIs
None

ImageFileRender_DeclareFonts
(SWI &562C3)

Declare fonts prior to printing
On entry
R0=Flags (reserved, must be 0)
R1=Filetype
R2=Pointer to data to render
R3=Length of data
R4=Pointer to extension data, or 0 if none
R5=Image sequence number
R6=Flags to pass to PDriver_DeclareFont
On exit
R0-6preserved
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use

This SWI should be used when printing images using the ImageFileRender module before any printing operations begin. Refer to the section 'Declare the fonts your document uses' in the chapter on Printing for more details.

Related entry points
IFR_DeclareFonts

ImageFileRender_Info
(SWI &56264)

Discover miscellaneous image information
On entry
R0=Flags (reserved, must be 0)
R1=Filetype
R2=Pointer to data to render
R3=Length of data
R4=Pointer to extension data, or 0 if none
R5=Image sequence number
R6=Query type:
ValueMeaning
&00000000Base details
&00000001-&00000FFFReserved for system use
&00001000-&0000FFFFReserved for developers
&00FF0000-&00FFFFFFReserved for private use
Others are reserved for future expansion.
R7=Pointer to query block
R8=Length of query block
On exit
R8=

If successful, R8 returns the length of block used.

If the block was too small, R8 returns a negative value showing how much space was required. If another error occurs, R8 will be positive.

Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use

This SWI should be used to find out information which is not provided by the generic APIs. It may be used (for example) to read the time between frames for a custom renderer, or to read additional information about the image which would otherwise not be available.

The base details query returns the following:

OffsetContents
+0Sequence number
+4X DPI
+8Y DPI
+12Colour type:
ValueMeaning
0Unspecified colour type (usually 'free' colour selection)
11bpp RGB
22bpp RGB
34bpp RGB
48bpp RGB
516bpp RGB
624bpp RGB
7CMYK
OthersReserved
+16Image flags:
Bit(s)Meaning
0If set, the image is solid and covers the entire bounding box described. If clear, the image may have sections which reflect the background colour.
1-31Reserved, must be zero

The base query is used to get generic information on an image in the file which was not necessary for the rendering of the file. This call is most commonly used to find the sequence number of the default and last logical image within a file. The sequence number may be set to &FFFFFFFF to indicate that the sequence number is not known. This might be the case if the format has no indication of the number of images present.

The image flags provide additional information about the image which might be useful to renderers. The only defined flag at present is that indicating if the image is 'solid' or not. This can be used by clients to decide whether drawing a background behind the image is neccessary or not.

Related entry points
IFR_Info

ImageFileRender_RendererInfo
(SWI &56265)

Discover information on the renderer
On entry
R0=Flags (must be 0)
R1=Filetype
R2=Magic identifier
On exit
R0=Pointer to renderer definition block (read only)
R1=Pointer to renderer name
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use

This SWI is used to return information about a renderer.

Related SWIs
ImageFileRender_EnumerateRenderers

ImageFileRender_Register
(SWI &56266)

Register a renderer
On entry
R0=Flags (reserved, must be 0)
R1=Pointer to definition (all will be copied):
OffsetContents
+0API version (102 at present)
+4Renderer flags
+8Filetype
+12Magic value, or 0 if none
+16Pointer to name to be copied, in the format: <name><tab><version x.xx><tab><author>
+20Workspace value for R12
+24Pointer to start entry point (IFR_Start)
+28Pointer to stop entry point (IFR_Stop)
+32Pointer to render entry point (IFR_Render)
+36Pointer to bounding box entry point (IFR_BBox)
+40Pointer to declare fonts entry point (IFR_DeclareFonts)
+44Pointer to information entry point (IFR_Info)

Or use 0 to get the current API version

On exit
R1=API version (even if an error occurred)
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use

This SWI is used to register a new renderer.

Related SWIs
ImageFileRender_Deregister

ImageFileRender_Deregister
(SWI &56267)

Deregister a renderer
On entry
R0=Flags (reserved, must be 0)
R1=Filetype
R2=Pointer to name used on registration
R3=Magic value to match (must be the same as when registered
On exit
R0-3preserved
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use

This SWI is used to deregister a renderer.

Related SWIs
ImageFileRender_Register

ImageFileRender_EnumerateRenderers
(SWI &56268)

Enumerate the active renderers
On entry
R0=Flags (reserved, must be 0)
R1=Last filetype, or -1 for first call
R2=Magic value, or 0 for first call
On exit
R0=Pointer to renderer definition block (read only)
R1=Filetype of this renderer, or -1 if there are no more
R2=Magic value of this renderer
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
SWI is re-entrant
Use

This SWI is used to enumerate the renderers which have been registered with the ImageFileRender module.

Related SWIs
ImageFileRender_RendererInfo

Error Messages


Error_IFR_BadTransformType
(Error &81A800)

Bad transform type
Use

This error is returned when the transformation type specified is invalid.


Error_IFR_Reserved
(Error &81A801)

Reserved flags set for ImageFileRender SWI
Use

This error is returned when a SWI has been called with flags set which have been defined as reserved. Where possible, this will be returned to allow clients to use new features when they are available, and to fall back to older methods where the features requested are not avialable.


Error_IFR_ReservedRendererFlags
(Error &81A802)

Reserved flags set for ImageFileRender renderer
Use

This error is returned during renderer registration when the flags specified in the renderer definition has flags set which have defined as reserved.


Error_IFR_Memory
(Error &81A803)

Not enough memory for ImageFileRender
Use

This error is returned when there is not enough memory for the rendering (or other) operation.


Error_IFR_NoSuchRendererToRemove
(Error &81A804)

Renderer not known
Use

This error is returned when the renderer being deregistered is not known to the ImageFileRender module.


Error_IFR_NoRenderr
(Error &81A805)

No renderer registered for that filetype
Use

This error is returned when an operation is attempted on a filetype for which no renderer has been registered.


Error_IFR_BadAPI
(Error &81A806)

Bad API version
Use

This error is returned when an operation is attempted for which the renderer API is not understood by the renderer. This will most likely not be seen by external clients. Clients who proxy their rendering through another renderer may see this if the APIs provided do not match between the proxy and the client.


Error_IFR_CantTransform
(Error &81A807)

Transformation type not supported by filetype
Use

This error is returned when the rendering operation cannot be performed because the renderer does not support the transformation requested by the client. The most likely cause for this error is attempted to skew or rotate a filetype which cannot be skewed or rotated (for example JPEGs).


Error_IFR_NoColourMap
(Error &81A808)

Colour mapping not supported by filetype
Use

This error is returned when a rendering operation cannot be performed because the renderer does not support colourmapping and colourmapping has been requested by the client.


Error_IFR_BadInfoQuery
(Error &81A809)

Query type not recognised
Use

This error is returned when the ImageFileRender_Info query type has not been recognised by the renderer.


Error_IFR_BadInfoLength
(Error &81A80A)

Bad query length
Use

This error is returned when the ImageFileRender_Info query type has been recognised by the renderer, but the length supplied was not understood.


Error_IFR_BadSpriteMode
(Error &81A810)

Bad sprite mode
Use

This error is returned by the sprite renderer when the image being rendered uses a mode which is not understood by the system.


Error_IFR_BadSpriteFile
(Error &81A811)

Sprite file corrupt or contains unrecognised data
Use

This error is returned by the sprite renderer when the image being rendered is malformed or contains data which is not understood.


Error_IFR_NoSuchSprite
(Error &81A812)

Sprite not found
Use

This error is returned by the sprite renderer when it cannot locate the sprite named in the extension data.


Entry Points


IFR_Start
(&0)

Initialisation routine for ImageFileRender
On entry
R0=API version * 100 (102 in this version)
R1=Pointer to image descriptor:
OffsetContents
+0Pointer to data to render
+4Length of data
+8Pointer to extension data, or 0 if no data
+12Image sequence number
+16Private image data, 0 initially
R2=0
R12=Workspace value on entry to ImageFileRender_Register
On exit
None
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Entry-point is re-entrant
Use

The 'start' routine is called before any operations are applied to an image. This allows clients to cache information relevant to the image such that subsequent calls do not have to re-read the data. If the image data is not recognised, it should be faulted. Errors should be reported by setting V and returning an error block in R0.

Clients may fill in the private word with cached data. Usually this is a pointer to some workspace specific to this image.

Related SWIs
ImageFileRender_Register, ImageFileRender_Deregister
Related entry points
IFR_Stop

IFR_Stop
(&1)

Finalisation routine for ImageFileRender
On entry
R0=API version * 100 (102 in this version)
R1=Pointer to image descriptor:
OffsetContents
+0Pointer to data to render
+4Length of data
+8Pointer to extension data, or 0 if no data
+12Image sequence number
+16Private image data
R2=0
R12=Workspace value on entry to ImageFileRender_Register
On exit
None
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Entry-point is re-entrant
Use

The 'stop' routine is called after all operations are applied to an image. This allows clients to release space allocated for cache information relevant to the image. If there is any internal error, the client should tidy up as best it can and return an error. Errors should be reported by setting V and returning an error block in R0.

Related SWIs
ImageFileRender_Register, ImageFileRender_Deregister
Related entry points
IFR_Start

IFR_Render
(&2)

Rendering routine for ImageFileRender
On entry
R0=API version * 100 (102 in this version)
R1=Pointer to image descriptor:
OffsetContents
+0Pointer to data to render
+4Length of data
+8Pointer to extension data, or 0 if no data
+12Image sequence number
+16Private image data
R2=Pointer to rendering descriptor:
OffsetContents
+0Flags :
Bit(s)Meaning
0-2Reserved, must be zero
3Colour mapping function supplied
4-5Reserved, must be zero
6-9Quality to render at:
ValueMeaning
0Use default quality
1Lowest quality
2-14Renderer specific values
15Highest quality
10-31Reserved, must be zero
+4-24Transformation matrix to apply (standard format)
+28Minimum X clipping rectangle in external coordinates
+32Minimum Y clipping rectangle in external coordinates
+36Maximum X clipping rectangle in external coordinates
+40Maximum Y clipping rectangle in external coordinates
+44Pointer to colour mapping routine
+48Workspace for colour mapping routine
R12=Workspace value on entry to ImageFileRender_Register
On exit
None
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Entry-point is re-entrant
Use

The rendering routine is called to render an image using a given transformation. If the image data is not recognised, it should be faulted. Errors should be reported by setting V and returning an error block in R0.

The clipping rectangle passed represents the graphics rectangle as external coorinates (OS units) which is currently in use. It is provided for information such that rendering can take advantage of fast rejection of regions which do not need to be redrawn.

Related SWIs
ImageFileRender_Register, ImageFileRender_Deregister, ImageFileRender_Render

IFR_BBox
(&3)

Bounding box function for ImageFileRenderer
On entry
R0=API version * 100 (102 in this version)
R1=Pointer to image descriptor:
OffsetContents
+0Pointer to data to render
+4Length of data
+8Pointer to extension data, or 0 if no data
+12Image sequence number
+16Private image data
R2=Pointer to bounding box descriptor:
OffsetContents
+0Flags (0)
+4-24Transformation matrix to apply (standard format)
+28Minimum X position in Draw coordinates
+32Minimum Y position in Draw coordinates
+36Maximum X position in Draw coordinates
+40Maximum Y position in Draw coordinates
On exit
None
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Entry-point is re-entrant
Use

The bounding box routine is called to calculate the bounding box for a given transformation. If the image data is not recognised, it should be faulted. Errors should be reported by setting V and returning an error block in R0. The bounding box should be returned in draw coordinates for the images extent. That is, OS units * 256. Resolution values should be provided for information. If no DPI information is available, 180 (the screen resolution) should be returned.

If bit 3 of the renderer flags was clear on registration, the transformation matrix will be an identity matrix and can effectively be ignored. The scaling to the clients required size will be performed by ImageFileRender module based on the bounding box returned.

Related SWIs
ImageFileRender_Register, ImageFileRender_Deregister, ImageFileRender_BBox

IFR_DeclareFonts
(&4)

Declare fonts function for ImageFileRenderer
On entry
R0=API version * 100 (102 in this version)
R1=Pointer to image descriptor:
OffsetContents
+0Pointer to data to render
+4Length of data
+8Pointer to extension data, or 0 if no data
+12Image sequence number
+16Private image data
R2=Pointer to declare fonts descriptor:
OffsetContents
+0Flags (0)
+4Flags to pass to PDriver_DeclareFont
On exit
None
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Entry-point is re-entrant
Use

The font declaration routine need only be provided by renderers which use fonts. The renderer should call PDriver_DeclareFont with the names of all fonts and the flags passed in R4. If the image data is not recognised, it should be faulted. Errors should be reported by setting V and returning an error block in R0.

Related SWIs
ImageFileRender_Register, ImageFileRender_Deregister, ImageFileRender_DeclareFonts

IFR_Info
(&5)

Information function for ImageFileRenderer
On entry
R0=API version * 100 (102 in this version)
R1=Pointer to image descriptor:
OffsetContents
+0Pointer to data to render
+4Length of data
+8Pointer to extension data, or 0 if no data
+12Image sequence number
+16Private image data
R2=Pointer to information descriptor:
OffsetContents
+0Query type
+4Query data length
+8Pointer to data block to take details from / fill in
On exit
R0=If V flag set, a pointer to an error block, or a special error code :
ValueMeaning
1Invalid query type - the query was not understood.
2Invalid query length - the query was understood but its length was invalid.
Interrupts
Interrupts are disabled
Fast interrupts are enabled
Processor mode
Processor is in SVC mode
Re-entrancy
Entry-point is re-entrant
Use

The information routine should be provided by renderers to query information about the images. The routine should fault invalid queries and invalid query lengths.

Related SWIs
ImageFileRender_Register, ImageFileRender_Deregister, ImageFileRender_Info

*Commands


*ImageFileRenderers

List renderers registered with ImageFileRender
Syntax
*ImageFileRenderers
Parameters
None
Use

*ImageFileRenderers is used to list the renderers known to the ImageFileRender module. This can be used to check which file formats are available for use with ImageFileRender from the command line.

Example
*ImageFileRenderers &695 00000000 ConvertGIF 0.08 RISCOS Ltd (via IFC)
&69c 00000000 ConvertBMP 0.05 RISCOS Ltd (via IFC)
&69e 00000000 ConvertPNM 0.02 RISCOS Ltd (via IFC)
&aff 00000000 ImageFileRender 0.25 RISCOS Ltd
&b60 00000000 ConvertPNG 0.09 RISCOS Ltd (via IFC)
&b61 00000000 ConvertXBM 0.06 RISCOS Ltd (via IFC)
&c85 00000000 ImageFileRender 0.25 RISCOS Ltd
&d94 00000000 IFR Artworks 0.08 RISCOS Ltd
&fc9 00000000 ConvertSun 0.05 RISCOS Ltd (via IFC)
&ff9 66990101 ImageFileRender 0.25 RISCOS Ltd
Related SWIs
ImageFileRender_EnumerateRenderers, ImageFileRender_Register

*ImageFileViewer

Sets the default viewer to use for files known to ImageFileRender
Syntax
*ImageFileViewer [<command>]
Parameters
None
Use

*ImageFileViewer is used to register a command which can be used to view files known to ImageFileRender. The Alias$@RunType_XXX variables will be set for filetypes known to ImageFileRender which have not already been set. If no parameter is passed to the command, the default viewer wil be cleared and all the variables will be unset.

The effect of issuing this command is that any files know to ImageFileRender which are not recognised by running applications when double-clicked in Filer (or run explicitly) will cause the command specified to be run, passing the filename of the file run as the first parameter.

Example
*ImageFileViewer /<ImgViewer$Dir>.!Run -file %*0
Related APIs
None

Document information

Maintainer(s):
History:
RevisionDateAuthorChanges
pre-1AMHPre-release
  • Converted from original text to XML
pre-2AMHPre-release
  • Modified ImageFileRender_BBox to add sequence number.
  • Modified service call names to Render rather than Renderer.
  • Updated the base details query.
pre-320 Nov 2002ROLValidated
  • XML validated.
  • Corrected sections which were undefined (IRQ, FIQ, Reentrancy).
pre-421 Jan 2003ROLMisc corrections
  • Corrected the DPI size given for drawfiles.
  • Added details of start and stop operations.
  • Finished off remaining undefined sections.
  • Added error message definitions.
pre-531 Jan 2003ROLAdded Enumerate SWI
  • Added documentation about EnumerateRenderers SWI.
pre-621 Jan 2003ROLMisc corrections
  • Correction for ImageFileRender_Transform description.
pre-715 Feb 2003ROLNew commands
  • Added documentation of ImageFileRenderers and ImageFileViewer commands.
pre-806 Apr 2003ROLMisc corrections
  • Added magic error values for IFR_Info.
  • Corrected documentation of IFR_BBox parameter block.
  • Added hyperlinks to ImageFileRender_Register and a few related references.
pre-801 May 2004ROLTable correction
  • ImageFileRender_Render's R8 table has been clarified.
117 Oct 2020GerphBackported text file changes
  • Backported changes from the text version.
  • Bitfields for the quality were incorrectly specified one bit short (should be bits 6-9)
  • Range for query types didn't actually match up consistently.
  • Renderer name wasn't specified in the documentation, although it was expected for presentation.
Disclaimer:

Part or all of this document has been worked upon by Andrew Hill of MH Software as part of the RISC OS Documentation Project.
Those portions are Copyright © MH Software, 2001-2003. They are to be distributed by RISC OS Ltd. with permission for publication on the select.riscos.com website and Select CD.
The remainder of this work retains the copyrights stated above. No responsibility will be borne by MH Software for the accuracy of this work, nor for any losses which may result from it.