Site Tools


documentation:file_formats:sdk:dsp

Description of the 3DO Portfolio OS Audio Folio “.dsp” file format.

Structure

“dsp” files are IFF files (Interchange File Format) which store the DSP program and metadata.

IFF files are made up of “chunks.” A chunk is made up of an id (4 chars), size (32bit signed int), and data (byte array). In C/C++ a chunk structure would look like this:

typedef char iff_id_t[4];

typedef struct iff_chunk_s iff_chunk_t;
struct iff_chunk_s
{
  iff_id_t id;
  int32_t  size;
  uint8_t  data[0];
};

Syntax definitions from the original IFF document:

Chunk    ::= ID #{ UBYTE* } [0]

Property    ::= Chunk

FORM    ::= "FORM" #{ FormType (LocalChunk | FORM | LIST | CAT)* }
FormType    ::= ID
LocalChunk    ::= Property | Chunk

CAT    ::= "CAT " #{ ContentsType (FORM | LIST | CAT)* }
ContentsType    ::= ID    -- a hint or an "abstract data type" ID

LIST    ::= "LIST" #{ ContentsType PROP* (FORM | LIST | CAT)* }
PROP    ::= "PROP" #{ FormType Property* }

In this extended regular expression notation, the token "#" represents
a ckSize LONG count of the following {braced} data bytes. Literal
items are shown in "quotes", [square bracketed items] are optional,
and "*" means 0 or more instances. A sometimes-needed pad byte is
shown as "[0]".

More information:

Chunks

Details in part taken from the SDK documentation.

IDDescription
FORM.3INS3DO Instrument
FORM.3INS.NAMEThe original filename
FORM.3INS.FORMDSP file info
FORM.3INS.FORM.DSPPDSP program
FORM.3INS.FORM.DSPP.DHDRDSP program header

16 bytes. 4 32bit words.

word[0] =
word[1] =
word[2] =
word[3] =
FORM.3INS.FORM.DSPP.DCODDSP code plus chunk

The beginning of the DCOD chunk contains a table with entries for each subchunk, as follows:

int32 dcod_Type;
int32 dcod_Offset;
int32 dcod_Size;

There are three possible values for dcod_Type:

DCOD_INIT_DSPP () = initialization code for DSP
DCOD_RUN_DSPP () = run time DSP code
DCOD_ARGS () = TagArgs with null terminator
FORM.3INS.FORM.DSPP.DRSCA DRSC chunk consists of an array of resource requests, as follows:

int32 drsc_Type
int32 drsc_Many
various drsc_Allocated /* Filled when allocated */
int32 drsc_References /* Count for exported references */

The following types are supported are:

DRSC_EN_MEM = EN Memory for DSPP programs
DRSC_EI_MEM = EI Input Memory for knobs
DRSC_I_MEM = I Memory
DRSC_EO_MEM = EO Output Memory for debugging
DRSC_RBASE4 = RBASE with 4 I regs
DRSC_RBASE8 = RBASE with 8 I regs
DRSC_INFIFO
DRSC_OUTFIFO
DRSC_TICKS = CPU cycles in DSPP
FORM.3INS.FORM.DSPP.DRLCRelocation

A DRLC chunk is an array of relocation commands consisting of the following:

uchar drlc_Attribute /* of resource */
uchar drlc_Flags
uchar drlc_Width /* of field to update */
uchar drlc_Bit /* bit position of LSB of field*/
int32 drlc_CodeIndex /* Index of subchunk in DCOD */
int32 drlc_RsrcIndex /* Index of entry in Resource Chunk */
int32 drlc_CodeOffset /* Offset within subchunk */

Some important fields are discussed in the following table

DLRC chunk fields.

DLRC_Attribute: Used to calculate the relocation value from the allocated value. An example would be the STATUS address for a FIFO as opposed to the normal FIFO address.

DRLC_ADD: Adds allocated value to current contents of word pointed to by CodeOffset instead of simply setting contents. Generally used for relocating branchesby referencing EN Resource. When the EN instruction space isallocated, the new base address is added to the offset currently compiled for each branch.

DRLC_LIST: The CodeOffset points to a singly linked list of fields to be set to the allocated value. This field should not be set if DRLC_ADD is set.

DRLC_32: 32-bit data are relocated. Offsets are indexes into uint32 instead of ushort arrays.
FORM.3INS.FORM.DSPP.DNMSPacked Resource Names

A DNMS chunk is a packed array of Forth/Pascal style strings. Resources without names have a 0-byte placeholder.
FORM.3INS.FORM.DSPP.DKNBThe DKNB Chunk is an array of knob declarations used to control DSP programs, typically through the EI stack. Knobs may require single or double precision EI space or they may be virtual knobs that control ARM parameters and require no EI space.

int32 dknb_Next /* offset in chunk of next knob */
int32 dknb_Min
int32 dknb_Max
int32 dknb_Nominal
int32 dknb_NumResources
char dknb_Name[AF_MAX_NAME_SIZE]
arrayof
int32 dknr_RsrcIndex
int32 dknr_CalcType
int32 dknr_Data1
int32 dknr_Data2

The CalcType (see the table below) determines how the knob parameters are converted.

CALC_LINEAR = knob_value * Data1 + Data2
CALC_INVERT = (Data1/knob_value) + Data2
CALC_LINEAR_FP = knob_value * Data1 + Data2 /* fixed point */
CALC_SIN = sin(knob_value * Data1) * Data2
documentation/file_formats/sdk/dsp.txt · Last modified: 2022/10/02 19:55 by 127.0.0.1