Admin: Created page with "Sound Datatype NAME sound.datatype -- root data type for sounds. FUNCTION The sound.datatype is the super-class for any sound related classes. METHODS ..."

2016-08-30T22:11:12Z

Created page with "Sound Datatype NAME sound.datatype -- root data type for sounds. FUNCTION The sound.datatype is the super-class for any sound related classes. METHODS ..."

New page

Sound Datatype

NAME

sound.datatype -- root data type for sounds.

FUNCTION

The sound.datatype is the super-class for any sound related
classes.

METHODS

OM_NEW -- Create a new sound object.

OM_GET -- Obtain the value of an attribute.

OM_SET -- Set the values of multiple attributes.

OM_UPDATE -- Update the values of multiple attributes.

OM_DISPOSE -- Dispose of a sound object.

GM_LAYOUT -- Layout the object and notify the application of the title and size.

GM_HITTEST -- Determine if the object has been hit with the mouse.

GM_GOACTIVE -- Tell the object to go active. On SELECTDOWN, the sound will start playing.

GM_HANDLEINPUT -- Handle input. Currently input (other than SELECTDOWN) doesn't affect the sound.

GM_RENDER -- Cause the graphic to render.

DTM_TRIGGER -- Cause an event to occur.

Possible events are:

STM_PLAY -- Causes the sound to start playing.

STM_STOP -- Causes the currently playing sound to stop and reset.

STM_PAUSE -- Causes the currently playing sound to stop.

STM_RESUME -- Causes the currently paused sound to resume.

STM_LOCATE -- Causes the current sound to seek to position.

NOTE: Subclasses which support streaming data access may support more than just these events.

NOTE: For V53.23, STM_PLAY and STM_LOCATE take a parameter of type
ULONG which represents the offset in milliseconds to seek
to. The default STM_LOCATE implementation will process all
samples up til the seek time and update the SDTA_Position value.
Subclasses may override this behavious but should OM_NOTIFY
the SDTA_Position value when complete. The standard methods
controlling playback are best called from a Process as these
may invoke DOS calls for file-based streams; unfortunately
button clicks are made on an Intuition task which means they
are often invoked from a Task. Provision must be made for
this scenario.

DTM_COPY -- Copy the entire sound to the clipboard as 8SVX.

NOTE: Up to and including V40 sound.datatype never stored a valid VoiceHeader with the file. This was fixed in V44.

Subclasses which support streaming data access may not support this method.

DTM_WRITE -- Write the entire sound to a file as 8SVX.

NOTE: Up to and including V40 sound.datatype never stored a valid VoiceHeader with the file. This was fixed in V44.

Subclasses which support streaming data access may not support this method.

NOTE: Beware using DTM_WRITE with a large continuous stream.
The entire sample is processed in memory in order to write
discrete channels efficiently in the 8SVX format. If
no replay period is available, the stream will not be
written and the operation will fail.

SDTM_FETCH -- Read the next n bytes of PCM data.

NOTE: New for V53.23, reads the next block of data into a buffer
supplied by the caller using the sdtFetch structure.
Typically only used by the playback loop but client
applications may use this on non-playing sounds to obtain
the decoded sample data; the default format may be overridden
by supplying required format arguments in the sdtf_AttrList
field. Flags include an option to retrieve a set number of
samples instead of bytes, using SDTFF_SAMPLES.

TAGS

SDTA_VoiceHeader (struct VoiceHeader *) *OBSOLETE*

Set and get the base information for the sound.
VoiceHeader is defined in <datatypes/soundclass.h>.

NOTE: Up to and including V40 sound.datatype never returned
a valid VoiceHeader for OM_GET and the VoiceHeader data
was ignored in the OM_NEW/OM_SET cases. This was fixed
in V44.

NOTE: Starting with V53.23 the VoiceHeader structure is considered
obsolete and should be avoided - it remains purely for
compatibility purposes. One issue affecting modern sound
formats is the limited sample rate stored using a UWORD
(up to 65535Hz) - which excludes working with, say,
96kHz audio. Use the SDTA_SamplesPerSec tag for full
exposure.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_SoundFormat (struct SoundFormat *) (V53.23)
Set and get the format of the PCM data for the sound class using
a structure rather than individual tags.

NOTE: When issuing OM_GET for this attribute, ti_Data MUST
contain a valid pointer to a structure pointer. That is:
(struct SoundFormat **).
The structure pointer itself may be NULL, in which case the
structure will be allocated and MUST be released by the caller
using FreeVec()

SDTA_Sample (APTR)

Set and get the sound data. Starting with V40 the sample data
does not need to be in CHIP memory.

Starting with V44 the sample data does not need to start
on a WORD-aligned address. Setting SDTA_Sample to NULL
will stop sound replay if sound.datatype was started
playing with a non-NULL SDTA_Sample parameter.

The SDTA_Sample parameter selects mono playback on any
sound channel that is currently available.

NOTE: For streaming sound playback, SDTA_LeftSample,
SDTA_RightSample, and SDTA_Sample will all be NULL (V44).

NOTE: Starting with V53.23 the semantic data type of this value
is APTR instead of int8*. Syntactically, it makes no
particular difference as it still points to a byte array,
but the samples therein might not be 8-bit. Internally,
no assumptions are made as to the contents of the buffer
until necessary and will be determined by the other
formatting tags. As such, the sound data provided via
this tag is only MONO if the channel settings are not
modified from their default values; where more channels
are specified, the buffer will contain the whole sample
(either interleaved or discrete).

Applicability is (OM_NEW, OM_SET)

SDTA_SampleLength (uint32)
Length of the sound data in bytes. Starting with V44 the
sample data does not need to be an even number of bytes.
Setting SDTA_SampleLength to 0 will stop sound replay.

The amount of sound data in bytes is calculated with the
simple formula: <number of samples> * <bytes per sample>

Note: Even for stereo samples where you specify both
SDTA_LeftSample and SDTA_RightSample, the SampleLength
still only describes the number of bytes for *one*
sample, as left and right sample must be of even size
anyway.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_Period (uint16) *OBSOLETE*
Set and get the period of the sound (in timing intervals
per sample). This attribute can be used to affect a playing
sound.

Please note that the Classic Amiga audio hardware does not
reliably support playback periods shorter than 124;
sound.datatype will limit the period to valid intervals (V44).

Default for this tag is 394.

NOTE: Starting with V53.23, the period setting is obsolete.
The period controlled the timing of Paula and can
be supported on newer systems through calculations
involving the sample rate. Supported as convenience
only - poorly.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_Volume (uint16)

Set and get the volume of the sound. This attribute can be
used to affect a playing sound.

Valid range is from 0 to 64.

Default for this tag is 64.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_Cycles (uint16)

Set and get the number of cycles the sound will be played.

Default for this tag is 1.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_SignalTask (struct Task *) (V40)

Task to signal when playback has completed, or if
SDTA_Continuous is TRUE, when the next buffer is needed.

Default for this tag is NULL.

Applicability is (OM_NEW, OM_SET)

SDTA_SignalBit (uint32) (V40) *OBSOLETE*

Signal mask to use with SDTA_SignalTask or 0 to disable.

NOTE: Due to a bug in sound.datatype V40 SDTA_SignalBit was
actually implemented as a signal mask as opposed to a
bit number. The documentation now reflects this and
recommends the use of SDTA_SignalBitMask instead. If you
intend to use a signal bit number instead of the mask,
use the new V44 tag SDTA_SignalBitNumber below.

Default for this tag is 0.

Applicability is (OM_NEW, OM_SET)

SDTA_Continuous (BOOL) (V40)

Used to indicate that the sound datatype will be fed a
continuous stream of data.

Default for this tag is FALSE.

Applicability is (OM_NEW)

SDTA_SignalBitMask (uint32) (V44)

Signal mask to use with SDTA_SignalTask or 0 to disable.
This tag is an alias for SDTA_SignalBit.

Default for this tag is 0.

Applicability is (OM_NEW, OM_SET)

SDTA_SignalBitNumber (int8) (V44)

Signal bit to use with SDTA_SignalTask or -1 to disable.

Default for this tag is -1.

Applicability is (OM_NEW, OM_SET)

SDTA_SamplesPerSec (uint32) (V53.23)

Set and get the replay frequency of a sound (in Hz). This
attribute can be used to affect a playing sound. Unlike the
SDTA_Period tag, which serves the same purpose, this tag
automatically takes the system clock value into account.
Please note that classic Amiga audio hardware does not reliably
support playback rates beyond 28,000 samples per second;
sound.datatype will limit the replay frequency to valid
intervals.

NOTE: Prior to V53.23, this value is treated as uint16 and
fails to support sample rates higher than 65kHz.
Starting with V53.23, the value is a full 32-bit number
unless accessed via the VoiceHeader by legacy dtypes.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_ReplayPeriod (struct TimeVal *) (V44)

Get the replay period, i.e. the time it takes for the
complete sound to be played.

If the sample size has not been set yet, the Seconds
and Microseconds members will be set to 0. If the sample
is to be played continuously, both TimeVal members will
be set to 0xFFFFFFFF.

New for V53.23, if SDTA_Continuous is TRUE, the subclass is expected
to override the getter of the attribute and supply a valid
number of Seconds and Microseconds, else the default of 0xFFFFFFFF
will be returned in each field. Failure to set a replay period
prevents the use of DTM_WRITE.

NOTE: The value returned by SDTA_ReplayPeriod may not match the
maximum value reached in SDTA_Position due to average bytes
per second calculations and block alignments. Expect
some drift or jitter in the playback clock.

Applicability is (OM_GET)

SDTA_Pan (int8) (V44)

Set the stereo panning; this must be set to
a number in the range of -64..64. A value of -64 will
pan the sound to the left channel, silencing the right
channel; a value of 64 will pan the sound to the right
channel and silence the left channel. To centre playback,
use a panning value of 0. The panning value only takes
effect if a stereo sound is being played.

Default for this tag is 0.

Applicability is (OM_NEW, OM_SET)

SDTA_FreeSampleData (BOOL) (V44)
This tag controls whether sound.datatype will call FreeVec()
on the sample data attached to an object. If the
SDTA_Continuous attribute was set to TRUE, sound.datatype will
never free any data attached to an object. It is safe to
attach the same sample to more than one channel as
sound.datatype will make sure that no sample data is
freed twice.

Default for this tag is TRUE.

Applicability is (OM_NEW, OM_SET)

SDTA_LeftSample (int8 *) (V44) *OBSOLETE*

Set and get the left channel sound data. The sample data does
not need to be in CHIP memory and does not need to start on a
WORD-aligned address.

Setting SDTA_LeftSample to NULL will stop sound replay if
sound.datatype was started playing with a non-NULL
SDTA_LeftSample parameter.

The SDTA_LeftSample parameter alone selects mono playback on
any left sound channel that is currently available. Used together
with the SDTA_RightSample parameter, stereo playback on any
available stereo channels is selected.

The SDTA_LeftSample parameter takes precedence over the
the SDTA_Sample parameter.

NOTE: For streaming sound playback, SDTA_LeftSample,
SDTA_RightSample, and SDTA_Sample will all be
NULL.

NOTE: Starting with V53.23, the explicit reliance on either mono
or stereo samples is removed to permit more channels.
Left and right sample tags are supported but should be
avoided and considered obsolete.

Applicability is (OM_NEW, OM_SET)

SDTA_RightSample (int8 *) (V44) *OBSOLETE*

Set and get the right channel sound data.

The sample data does not need to be in CHIP memory and does
not need to start on a WORD-aligned address. Setting
SDTA_RightSample to NULL will stop sound replay if sound.datatype
was started playing with a non-NULL SDTA_RightSample parameter.

The SDTA_RightSample parameter alone selects mono playback on
any right sound channel that is currently available. Used
together with the SDTA_LeftSample parameter, stereo playback
on any available stereo channels is selected.

The SDTA_RightSample parameter takes precedence over the
the SDTA_Sample parameter.

NOTE: For streaming sound playback, SDTA_LeftSample,
SDTA_RightSample, and SDTA_Sample will all be
NULL.

NOTE: Starting with V53.23, the explicit reliance on either mono
or stereo samples is removed to permit more channels.
Left and right sample tags are supported but should be
avoided and considered obsolete.

Applicability is (OM_NEW, OM_SET)

SDTA_SyncSampleChange (BOOL) (V44)

If SDTA_Continuous was set to TRUE, sound.datatype will expect
a continuous stream of data to be played. By specifying
"SDTA_SyncSampleChange,TRUE" you request that new sound data
will be played only if the old data has been played completely
(otherwise, playback would restart immediately with the new sound).
If playback is currently in progress, the Task to change the
sample data will be made to wait until playback of the old sound
has finished.

Default for this tag is FALSE.

Applicability is (OM_NEW, OM_SET)

DTA_Immediate (BOOL) (V44)

Select and query whether playback should start immediately
after the object has passed the layout process.

Default for this tag is FALSE.

Applicability is (OM_NEW, OM_SET, OM_GET)

DTA_Repeat (BOOL) (V44)

Select and query whether playback should loop indefinitely,
regardless of the current SDTA_Cycles settings.

Default for this tag is FALSE.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_BitsPerSample (uint8) (V53.2)

Set and get the actual bitrate of the sample which can be 8,
16 or 32 bits.

With this tag sound.datatype finally supports handling of
samples >8bit.

If AHI isn't available this tag MUST be set for 16 or 32bit
sound data to get them (poorly) converted to 8bit.

Default for this tag is 8.

NOTE: Starting with V53.23, 24-bit samples are also supported.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_FrameLength (uint32) (V53.23)

Gets the size in bytes of a single sample frame. A single frame
contains one sample for each channel in a contiguous series of
bytes.

Default is number of channels x bytes per sample.

Applicability is (OM_GET)

SDTA_BlockAlign (uint32) (V53.23)
Sets the number of bytes in an elementary block of sound data.
The block length is the total number of bytes required to
store n-sample frames (n samples per channel) and will typically
fall on a natural boundary calculated as
channels x bytes per sample x samples per block

Default as shown above.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_SamplesPerBlock (uint32) (V53.23)

Specifies the number of sample frames within a block of data.
Typically this is one (1) to form a natural block alignment
for linear PCM streams but can be arbitrary. The number of
samples should not exceed the block alignment.

Defaults to one (1)

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_AverageBytesPerSec (uint32) (V53.23)

Calculate the average number of bytes per second that is processed
when playing the current sound format. This value is considered
valid only for uncompressed PCM data streams.

Defaults to SDTA_FrameLength x SDTA_SamplesPerSec.

Applicability is (OM_GET).

SDTA_ValidBitsPerSample (uint8) (V53.23)

Indicates the number of valid bits within the sample.

Defaults to SDTA_BitsPerSample.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_HighAligned (BOOL) (V53.23)

TRUE if the sample value is contained within the most high bits
of the sample value, otherwise FALSE. Partners with the tag
SDTA_ValidBitsPerSample to indicate how the value should be
interpreted.

Defaults to TRUE.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_LittleEndian (BOOL) (V53.23)

TRUE if the sample data is in little-endian (Intel) order.
Classic Amiga and OS4.x is big-endian so the data must be
reordered before use.

Defaults to FALSE.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_FloatingPoint (BOOL) (V53.23)

TRUE if the samples are stored in floating point format. For
this to be valid, the SDTA_BitsPerSample value MUST be either
32 or 64 to indicate single or double precision respectively.

Defaults to FALSE.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_Channels (uint8) (V53.23)

Specifies the number of channels present within the sound data.
Prior to V53.23, the number of channels was either one (MONO) or
two (stereo) - which was intrinsically determined by the tags
supplying SDTA_Sample, SDTA_LeftSample and SDTA_RightSample.
Starting with V53.23, the number of channels has exploded to
ridiculous proportions.

Defaults to one (1)

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_ChannelLayout (uint32) (V53.23)

Presents the intrinsic layout of the sound in relation to its
channels and intended purpose. The intention of the layout
is to accomodate as many existing formats and encodings as is
possible. When set to SOUNDMAP_USE_MASK, the value in the
SDTA_ChannelMask is used to determine the channels and their
position in the sound.

Defaults to SOUNDMAP_USE_MASK.

NOTE: For V53.23 (initial release) use the nominally supported
value of SOUNDMAP_USE_MASK only. Future releases will
hopefully provide better support for channel mapping.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_ChannelMask (uint32) (V53.23)

Related to the SDTA_ChannelLayout tag, the value presented
here is only considered when the channel layout is set to
SOUNDMAP_USE_MASK. The bit mask presented identifies each
channel present in the sound data with the explicit reliance
on the channels also appearing in the order they occur in
the bitmask.

Defaults to SPEAKERF_MONO (1)

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_DiscreteChannels (BOOL) (V53.23)

TRUE when the channel data is separated into distinct blocks
and is not interleaved. For example, the 8SVX format stores
its sample data in disparate left and right channels, each
of length N; thus the data is presented as two independent
channels contained in one contiguous block:
L0, L1, L2, ..., LN-1 R0, R1, R2, ..., RN-1
In contrast, when FALSE, the sample data is interleaved into
a single block with each channel alternating as appropriate:
L0, R0, L1, R2, L2, R2, ..., LN-1, RN-1

Defaults to TRUE.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_Unsigned (BOOL) (V53.23)

TRUE to indicate that the sample data is unsigned numbers with
a range of [0..2^BitsPerSample]. When FALSE, the range changes
to [-2^BitsPerSample..2^BitsPerSample-1].

Defaults to FALSE.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_Position (struct TimeVal *) (V53.23)
Determines the elapsed time of playback.

Defaults to zero (0)

Applicability is (OM_GET)

SDTA_DefaultIconName (STRPTR) (V53.23)

Specifies the name of the default icon used by default to
render the datatype gadget. Useful for subclasses to show
appropriate file type information (e.g. "wav", "aiff")

Defaults to "sound"

Applicability is (OM_NEW)

GA_Image (struct Image *) (V53.23)

Specifies a custom image used to render the datatype gadget
imagery. Overrides SDTA_DefaultIconName when present. Useful
for app developers who may wish to show album art or other
graphical representation of the sound.

Defaults to NULL.

Applicability is (OM_NEW, OM_SET)

SDTA_Compression (UBYTE) (V53.23)

To provide a small amount of tag compatbility with the original
voice header, the SDTA_Compression tag maps its value to the
8SVX header. Compression algorithms currently supported is limited
to CMP_NONE, CMP_FIBDELTA, CMP_MSFT_ADPCM, CMP_CCIT_ULAW,
CMP_CCIT_ALAW and CMP_IMA_ADPCM. Be aware that the sound class will
honour the value provided in this tag or the voice header and attempt
to decode the audio supplied using SDTA_Sample only when SDTA_Compressed
is TRUE.

Defaults to CMP_NONE.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_Compressed (BOOL) (V53.23)

Convenience tag used to indicate that the sound data is
actually compressed despite appearances otherwise. Essentially
enables the decompression as indicated in SDTA_Compression.

Defaults to FALSE.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_DownmixQuality (uint32) (V53.23)

Starting with V53.23, the quality of downmixing of multichannel
sound to stereo is possible. Use SDTMIX_None for direct channel
output without mixing (excess channels are "lost") or use
SDTMIX_StereoSurround for mixing the front and surround left/right
channels to the front left and right speakers.

Defaults to SDTMIX_None.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_UpmixQuality (uint32) (V53.23)

Starting with V53.23, the quality of upmixing of multichannel
sound to stereo is possible. Use SDTMIX_None for direct channel
output without mixing or SDTMIX_StereoSurround for directing the
front left and right channels through the left and right surround
channels.

Defaults to SDTMIX_None.

Applicability is (OM_NEW, OM_SET, OM_GET)

SDTA_SignalHook (struct Hook *) (V53.23)

Starting with V53.23, a new streaming mechanism is provided in the
form of a callback hook. A subclass or client providing a hook
in combination with SDTA_Continuous will receive regular requests
for data using the hook specified. The function signature is:
int32 func( struct Hook *, Object *, struct sdtFetch * )
where the the object is the sound class instance causing the request
and buffer is empty with sdtb_Data as NULL. The subclass or client
will receive an allocated buffer and appropriate length as indicated
by SDTA_MinimumFetch and should return a positive value for success
indicating the number of data bytes in the buffer, zero for failure or
end of stream and negative numbers for error.

Supercedes SDTA_SignalTask and SDTA_SignalBit* where a combination
is specified.

Defaults to NULL.

Applicability is (OM_NEW)

SDTA_MinimumFetch (ULONG) (V53.23)

Starting with V53.23 for use with the STDA_SignalHook callback,
defines the minimum number of samples required to satisfy an
individual SDTM_FETCH call. This attribute is intended for class
implementors and not for general application use - it does not
guarantee that this number of samples will be returned, only that
the internal buffers should allow for it.

Defaults to 2048.

Applicability is (OM_NEW, OM_SET, OM_GET)

NOTES
You cannot switch between mono and stereo playback on the fly while
the sound is still playing. First, stop the sound, then change the
SDTA_Sample/SDTA_LeftSample/SDTA_LeftSample attributes. Starting
with V53.23 the same applies for any number of channels, not just mono
and stereo playback (although one would assume you understood this
was the case anyway!)

The sound.datatype implementation has been cleaned up for V44 to
allow for streaming subclasses to be written. Such subclasses will
always return NULL when their SDTA_LeftSample, SDTA_RightSample and
SDTA_Sample attributes are queried. However, they will never return
0 for the SDTA_SampleLength and SDTA_SamplesPerSec attributes since
these can be used to calculate the length of the entire sample.
Streaming subclasses will respond to the DTM_TRIGGER method, to
start, stop playback, etc. but may not support any other methods
which rely upon the entire sample to reside in memory.

The sound.datatype implementation has been completely rewritten for
V53.23 to allow better support for streaming and multichannel sounds.
Most other restrictions still apply from earlier versions unless
otherwise documented.

BUGS

The V44 autodocs stated that the default for the "SDTA_FreeSampleData"
tag was FALSE. This has never been the case. In fact, it always defaults
to TRUE.

Sound Datatype - Revision history

Admin at 22:17, 30 August 2016

Admin: Created page with "Sound Datatype NAME sound.datatype -- root data type for sounds. FUNCTION The sound.datatype is the super-class for any sound related classes. METHODS ..."

@@ Line 1: / Line 1: @@
 Sound Datatype
-    NAME
+=NAME=
 	sound.datatype -- root data type for sounds.
-    FUNCTION
+=FUNCTION=
 	The sound.datatype is the super-class for any sound related
@@ Line 12: / Line 12: @@
-    METHODS
+=METHODS=
 	OM_NEW -- Create a new sound object.