IFFChunk: Coerce to and create IFFChunk objects

In AmigaFFH: Commodore Amiga File Format Handler

Coerce to and create IFFChunk objects

Description

Convert IFF.ANY objects (created with interpretIFFChunk()) into IFFChunk() objects. A basic IFFChunk() can also be created with this method by providing the chunk type name.

Usage

IFFChunk(x, ...)

## S3 method for class 'character'
IFFChunk(x, ...)

## S3 method for class 'IFF.FORM'
IFFChunk(x, ...)

## S3 method for class 'IFF.BODY'
IFFChunk(x, ...)

## S3 method for class 'IFF.ANNO'
IFFChunk(x, ...)

## S3 method for class 'IFF.AUTH'
IFFChunk(x, ...)

## S3 method for class 'IFF.CHRS'
IFFChunk(x, ...)

## S3 method for class 'IFF.NAME'
IFFChunk(x, ...)

## S3 method for class 'IFF.TEXT'
IFFChunk(x, ...)

## S3 method for class 'IFF.copyright'
IFFChunk(x, ...)

## S3 method for class 'IFF.CHAN'
IFFChunk(x, ...)

## S3 method for class 'IFF.VHDR'
IFFChunk(x, ...)

## S3 method for class 'IFF.8SVX'
IFFChunk(x, ...)

## S3 method for class 'IFF.ILBM'
IFFChunk(x, ...)

## S3 method for class 'IFF.CMAP'
IFFChunk(x, ...)

## S3 method for class 'IFF.BMHD'
IFFChunk(x, ...)

## S3 method for class 'IFF.CAMG'
IFFChunk(x, ...)

## S3 method for class 'IFF.CRNG'
IFFChunk(x, ...)

## S3 method for class 'IFF.ANIM'
IFFChunk(x, ...)

## S3 method for class 'IFF.ANHD'
IFFChunk(x, ...)

## S3 method for class 'IFF.DLTA'
IFFChunk(x, ...)

## S3 method for class 'IFF.DPAN'
IFFChunk(x, ...)

Arguments

x	An S3 class IFF.ANY object that needs to be coerced into an IFFChunk-class() object. IFF.ANY objects are created with the interpretIFFChunk() method. x can also be a character string of a IFF chunk type (e.g., "FORM" or "BMHD"). In that case an IFFChunk() object of that type is created with some basic content.
...	Arguments passed onto methods underlying the interpretation of the specific IFF chunks. Allowed arguments depend on the specific type of IFF chunk that x represents.

Details

IFF data is stored in a IFFChunk-class() object when read from an IFF file (read.iff()). These objects reflect the file structure well, but the data is stored as raw information. IFF files can contain a wide variety of information types, ranging from bitmap images to audio clips. The raw information stored in IFFChunk() objects can be interpreted into more meaningful representations that can be handled in R. This is achieved with the interpretIFFChunk() method, which returns IFF.ANY objects.

These IFF.ANY objects are a less strict representation of the IFF Chunk, but are easier to handle in R. The interpretation method is lossy and may not preserve all information in the IFF.ANY object. The IFFChunk-method() can coerce IFF.ANY back to the more strictly defined IFFChunk-class() objects. Be careful with conversions between IFFChunk-class() and IFF.ANY objects and vice versa, as information may get lost.

More detailed information about IFF chunks can be found in the IFF chunk registry (see references).

• IFF.FORM represents a FORM chunk, which is a container that can hold any kind of chunk. When interpreted, it is represented as a list, where each element is an interpreted chunk nested inside the FORM.

• IFF.BODY represents the actual data in an IFF file. However, without context this chunk cannot be interpreted and is therefore interpreted as a vector of raw data.

• IFF.ANIM represents an animation (ANIM) chunk. When interpreted, it will return a list where each element is an animation frame represented as an IFF.ILBM object. Each animation frame should be nested inside an ILBM chunk nested inside a FORM chunk, nested inside an ANIM chunk.

  • IFF.ANHD represents an ANimation HeaDer (ANHD) chunk. When interpreted, it returns a named list containing the following information:

    • operation is a character string indicating how the bitmap data for the animation frame is encoded. Can be one of the following: "standard", "XOR", "LongDeltaMode", "ShortDeltaMode", "GeneralDeltamode", "ByteVerticalCompression", "StereoOp5", or "ShortLongVerticalDeltaMode". Currently, only the ByteVerticalCompression is implemented in this package.

    • mask is a vector of 8 logical values. It is currently ignored.

    • w and h are positive numeric values, specifying the width and height of the frame (should be identical for all frames).

    • x and y are numeric values, specifying the plotting position for the frame.

    • abstime is a positive numeric value - currently unused - used for timing the frame relative to the time the first frame was displayed. In jiffies (1/60 sec).

    • reltime is a positive numeric value for timing the frame relative to time previous frame was displayed. In jiffies (1/60 sec).

    • interleave is currently unused. It should be set to 0.

    • pad0 is a padding byte (raw) for future use.

    • flags is a vector of 32 logical values. They contain information on how the bitmap data is stored.

    • pad1 are 16 padding bytes (raw) for future use.

  • IFF.DPAN represents an DPaint ANimation (DPAN) chunk. Some software will require this chunk to correctly derive the total number of frames in the animation. When interpreted, it will return a named list with the following elements:

    • version a numeric version number.

    • nframes a positive numeric value, indicating the number of frames in the animation.

    • flags a vector of 32 logical values. Ignored in this package as it was intended for future implementations.

  • IFF.DLTA represents a delta mode data chunk (DLTA). The first animation frame is stored as a normal InterLeaved BitMap (ILBM) image as described below. The following frames only store differences in bitmap data compared to the previous frames but is not interleaved. They are thus incorrectly embedded in an ILBM chunk (but is kept so for backward compatibility). When interpreted, a grDevices raster object is returned only showing the differences. It is not very meaningful to interpret these chunks on their own, but rather the entire parent ANIM chunk.

• IFF.ILBM represents InterLeaved BitMap (ILBM) chunks. It is interpreted here as a raster image (see grDevices::as.raster()). ILBM chunks are usually nested inside a FORM container.

  • IFF.BMHD represents the header chunk of a bitmap (BMHD), and should always be present (nested inside) an ILBM chunk. It is interpreted as a named list containing the following elements:

    • w and h are positive numeric values specifying the bitmap width and height in pixels. Note that the width can be any positive whole number, whereas the bitmap data always has a width divisible by 16.

    • x and y are numeric values specifying the plotting position relative to the top left position of the screen. Although required in the bitmap header. It is ignored in the interpretation of bitmap images.

    • nPlanes is a positive value indicating the number of bitplanes in the image. The number of colours in an image can be calculated as 2^nPlanes.

    • Masking indicates whether there are bitplanes that should be masked (i.e. are treated as transparent). It is a character string equalling any of the following: "mskNone", "mskHasMask", "mskHasTransparentColour", "mskLasso" or "mskUnknown". Only the first (no transparency) and third (one of the colours should be treated as transparent) id is currently interpreted correctly. The others are ignored. "mskUnknown" means that an undocumented mask is applied to the image.

    • Compression indicates whether the bitmap data is compressed. It is a character string that can equal any of the following: "cmpNone", "cmpByteRun1" or "cmpUnknown". The latter means an undocumented form of compression is applied and is currently ignored. In most cases bitmap data is compressed with the cmpByteRun1 algorithm (packBitmap()). In some cases, bitmap data is not compressed (cmpNone).

    • pad is a raw byte that is only used to align data. It is ignored in the interpretation.

    • transparentColour is a numeric value that indicates which colour number in the palette should be treated as fully transparent (when Masking equals "mskHasTransparentColour").

    • xAspect and yAspect or positive numeric values that indicate the aspect ratio of the pixels in the image. Amiga screen modes allowed for some extreme pixel aspect ratios. These values are used to stretch the image to their intended display mode.

    • pageWidth and pageHeight are positive numeric values indicating the size of the screen in which the image should be displayed. They are ignored in the interpretation of the image.

  • IFF.CMAP represents the colour map (CMAP) or palette of a bitmap image. Although common, the chunk is optional and can be omitted from the parent ILBM chunk. It is interpreted as a vector of colours (i.e., a character string formatted as '#RRGGBB' or named colours such as 'blue').

  • IFF.CAMG represents a chunk with information with respect to the display mode in which the bitmap image should be displayed. This information can be used to determine the correct pixel aspect ratio, or is sometimes required to correctly interpret the bitmap information. The IFF.CAMG chunk is interpreted as a named list containing the following elements:

    • monitor: a factor indicating the hardware monitor on which the image was created and should be displayed (see amiga_monitors()).

    • display.mode: a factor indicating the display mode in which the image should be displayed (see amiga_display_modes()).

  • IFF.CRNG is an optional chunk nested in an ILBM chunk. It represents a ‘colour range’ and is used to cycle through colours in the bitmap's palette in order to achieve animation effects. It is interpreted as a named list with the following elements. This chunk is currently not used with the interpretation of ILBM images.

    • padding are two raw padding bytes and are ignored when interpreted.

    • rate is a numeric value specifying the rate at which the colours are cycled. The rate is in steps per second.

    • flags is a flag that indicates how colours should be cycled. It is a character string that can equal any of the following: "RNG_OFF", "RNG_ACTIVE", "RNG_REVERSE" or "RNG_UNKNOWN". When equal to the first, colours are not cycled. When equal to the second, colours are cycled. When equal to the third, colours are cycled in reverse direction. When equal to the latter, an undocumented form of cycling is applied.

    • low and high are numeric indices of colours between which should be cycled. Only colour from index low up to index high are affected.

• IFF.8SVX represents 8-bit sampled voice chunks (8SVX). The original Amiga supported 8-bit audio which could be stored using the IFF. 8SVX chunks can contain separate audio samples for each octave. 8SVX chunks are usually stored inside a FORM container. Its body chunk contains 8-bit PCM wave data that could be compressed. When the 8SVX chunk is interpreted with this package, a list is returned where each element represents an octave given as a tuneR::Wave() object. Possible chunks nested in 8SVX chunks and currently supported by this package are as follows.

  • IFF.VHDR represents voice header chunks (VHDR). It contains (meta-)information about the audio stored in the body of the parent 8SVX chunk. When interpreted, a named list is returned with the following elements:

    • oneShotHiSamples is a numeric value indicating how many samples there are in the audio wave of the first octave in the file, that should not be looped (repeated).

    • repeatHiSamples is a numeric value indicating how many samples there are in the audio wave of the first octave in the file, that should be looped (repeated).

    • samplesPerHiCycle is a numeric value specifying the number of samples per repeat cycle in the first octave, or 0 when unknown. The number of repeatHiSamples should be an exact multiple of samplesPerHiCycle.

    • samplesPerSec is a numeric value specifying the data sampling rate.

    • ctOctave a positive whole numeric value indicating how many octaves are included. In 8SVX files the audio wave is resampled for each octave. The wave data in the body starts with the audio sample in the highest octave (least number of samples). The data is then followed by each subsequent octave, where the number of samples increase by a factor of 2 for each octave.

    • sCompression is a character string indicating whether and how the wave data in the body is compressed. It can have one of the following values: "sCmpNone" (no compression), "sCmpFibDelta" (deltaFibonacciCompress()ion is applied), "sCmpUnknown" (an undocumented and unknown form of compression is applied).

    • volume is a numeric value between 0 (minimum) and 0x10000 (maximum) playback volume.

  • IFF.CHAN represents the channel chunk (CHAN). When interpreted it returns a named list with 1 named element: "channel". It's value can be one of the following character strings "LEFT", "RIGHT" or "STEREO". This indicates for how many (one or two) audio channels data is available in the body of the parent 8SVX chunk. It also indicates two which channels the audio should be played back.

• IFF.ANNO, IFF.AUTH, IFF.CHRS, IFF.NAME, IFF.TEXT and IFF.copyright are all unformatted text chunks that can be included optionally in any of the chunk types. Respectively, they represent an annotation, the author's name, a generic character string, the name of the work, generic unformatted text, and copyright text. They are interpreted as a character string.

Value

Returns an IFFChunk-class() representation of x.

References

https://wiki.amigaos.net/wiki/IFF_FORM_and_Chunk_Registry

Examples

## Not run: 
## load an IFF file
example.iff <- read.iff(system.file("ilbm8lores.iff", package = "AmigaFFH"))

## interpret the IFF file (in some cases information
## will get lost in this step):
example.itpt <- interpretIFFChunk(example.iff)

## now coerce back to a formal IFFChunk class object.
## Only information in the interpreted object is used
## The coerced object may therefore depart from the
## original read from the file.
example.coerce <- IFFChunk(example.itpt)

## and indeed the objects are not identical, as shown below.
## In this case the difference is not disastrous, the order
## of the colours in the palette have shifted. But be careful
## with switching between formal IFFChunk objects and
## interpreted IFF.ANY objects.
identical(example.iff, example.coerce)

## It is also possible to create simple IFFChunk objects
## by providing the desired chunk type identifier as a
## character string.

## This creates a basic bitmap header:
bmhd <- IFFChunk("BMHD")

## This creates a basic colour palette:
cmap <- IFFChunk("CMAP")

## End(Not run)

AmigaFFH documentation built on June 22, 2024, 11:03 a.m.