Action11

From GRFSpecs
Revision as of 19:01, 12 June 2011 by Orudge (talk | contribs) (11 revisions)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

Define new sound data

Action 11

Define new sound data

-=Description=-

This action allows the definition of binary included sound samples.

Action 11 may only appear at most once per .grf file.

The newly defined sounds will be numbered consecutively, starting from 73 (49h) (numbers 0..72 represent original sounds). When you need to refer to your new sounds, you will have to use this numbering.

Available since 2.0.1 alpha 57.

-=Format=-

The data looks as follows:

-+<sprite-number> * <length> 11 <number>+-

||Element|Size|Description

<sprite-number>|dec|A sequential sprite number

<length>|dec|The total numer of bytes in the action

11|B|Action 11

<number>|W|Number of binary include sprites that follow||

-=Filling in the terms=-

sprite-number

The current sprite number.

length

The total number of bytes in this action 11.

number

This defines the number of binary include sprites that follow.

These can only be added using GRFCodec 0.9.7 or later, using the following format:

-+   17 ** sounds/e67_horn.wav+-

-+   18 ** sounds/sheep.wav+-

All files included this way must be 8-bit mono sound files in WAV format, PCM encoding. There are two allowed frequencies: 11025 Hz and 22050 Hz. Due to some limitations of the GRF format, the file size cannot exceed 64KB.

For those need to know or are inordinately curious, the actual encoding of a binary include is the same as a pseudosprite:

-+<sprite-number> * <length> FF <name-len> <name> 00 <data>+-

||Element|Size|Description

<name-len>|B|The return value of strlen(<name>);

<name>|S|The name of the included file, with any leading directories stripped

00|B|Null byte terminating the string (not included in size)

<data>|variable|A byte-for-byte copy of the contents of the file||

Importing sound effects from other grf files

Since 2.0.1 alpha 61, it is possible to import sound effects from other grf files (or even the current file).  This does not copy the sound effect data (thus reducing memory usage), but does provide a new sound effect entry with its own action 0 properties.

This is a way of either combining useful sound effects in a single grf file and using them in several, or to duplicate sounds with different amplification or priority settings without doubling the memory usage.

The referenced grf file can be anywhere in newgrf(w).cfg and does not have to be active.  If it is not loaded, no sound will be played but that is not an error condition. This makes it possible to separate sound effects and graphics into two files, to allow people with little memory to not load the sound effects yet get working graphics.

The format of such an import sprite is the following (replacing a "**" binary sprite within the action 11 sprite block):

-+<sprite-number> * <length> FE 00 <grfid> <number>+-

||Element|Size|Description

<sprite-number>|dec|A sequential sprite number

<length>|dec|The total numer of bytes in the action

FE|B|Code to identify a non-binary sprite in an action 11 block

00|B|Code to identify a sound effect import

<grfid>|D|GRFID of grf file to import sound effect from, may be the current one too

<number>|W|Sound effect number to import||

Note that unlike most other reference to sound numbers, the number here is simply the number within the referenced grf file's action 11 block, and does not refer to TTD's samples for numbers 0..72. Also, when importing the sound effect, the action 0 properties are not imported and have to be set separately.

-=Example=-

Look at this tt-forums-page for how to add sounds to a train.

http://www.tt-forums.net/viewtopic.php?f=26&t;=5033&p;=735013#p735013