@database "sound_dtc" @master "AMIDEV:NDK/Autodocs/sound_dtc.doc" @Node Main "sound_dtc.doc" @toc "Autodocs/AG/INDEX/Main" @{" sound.datatype() " Link "sound.datatype()"} @EndNode @Node "sound.datatype()" "sound.datatype/sound.datatype" @{b} NAME@{ub} sound.datatype -- root data type for sounds. @{b} FUNCTION@{ub} The sound.datatype is the super-class for any sound related classes. @{b} METHODS@{ub} @{"OM_NEW" Link "tabs_gc/OM_NEW"} -- Create a new sound object. @{"OM_GET" Link "tabs_gc/OM_GET"} -- Obtain the value of an attribute. @{"OM_SET" Link "tabs_gc/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" Link "tabs_gc/GM_LAYOUT"} -- Layout the object and notify the application of the title and size. @{"GM_HITTEST" Link "tabs_gc/GM_HITTEST"} -- Determine if the object has been hit with the mouse. @{"GM_GOACTIVE" Link "tabs_gc/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" Link "tabs_gc/GM_RENDER"} -- @{"Cause" Link "exec/Cause()"} the graphic to render. Currently the graphic for the sound is just a static icon. DTM_TRIGGER -- @{"Cause" Link "exec/Cause()"} an event to occur. Currently the only trigger event is STM_PLAY, which will cause the sound to start playing. NOTE: Subclasses which support streaming data access may support more than just the STM_PLAY event. DTM_COPY -- Copy the entire sound to the clipboard as 8SVX. NOTE: Up to and including V40 sound.datatype never stored a valid @{"VoiceHeader" Link "INCLUDE:datatypes/soundclass.h/Main" 113} with the file. This was fixed in V44. Subclasses which support streaming data access may not support this method. DTM_WRITE -- @{"Write" Link "dos/Write()"} the entire sound to a file as 8SVX. NOTE: Up to and including V40 sound.datatype never stored a valid @{"VoiceHeader" Link "INCLUDE:datatypes/soundclass.h/Main" 113} with the file. This was fixed in V44. Subclasses which support streaming data access may not support this method. @{b} TAGS@{ub} SDTA_VoiceHeader (struct @{"VoiceHeader" Link "INCLUDE:datatypes/soundclass.h/Main" 113} *) -- Set and get the base information for the sound. @{"VoiceHeader" Link "INCLUDE:datatypes/soundclass.h/Main" 113} is defined in @{"" Link "INCLUDE:datatypes/soundclass.h/Main" 0}. NOTE: Up to and including V40 sound.datatype never returned a valid @{"VoiceHeader" Link "INCLUDE:datatypes/soundclass.h/Main" 113} for @{"OM_GET" Link "tabs_gc/OM_GET"} and the @{"VoiceHeader" Link "INCLUDE:datatypes/soundclass.h/Main" 113} data was ignored in the @{"OM_NEW/OM_SET" Link "tabs_gc/OM_SET"} cases. This was fixed in V44. Applicability is (ISG). SDTA_Sample (BYTE *) -- 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" Link "rexxsupport/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" Link "rexxsupport/NULL"} (V44). Applicability is (ISG). SDTA_SampleLength (ULONG) -- Length of the sound data in bytes, for each channel. 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. NOTE: You must set this attribute *after* setting SDTA_BitsPerSample. Applicability is (ISG). SDTA_Period (UWORD) -- 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 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. Applicability is (ISG). SDTA_Volume (UWORD) -- 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 (ISG). SDTA_Cycles (UWORD) -- Set and get the number of cycles the sound will be played. Default for this tag is 1. Applicability is (ISG). The following tags are new for V40. SDTA_SignalTask (struct @{"Task" Link "INCLUDE:exec/tasks.h/Main" 23} *) -- @{"Task" Link "INCLUDE:exec/tasks.h/Main" 23} to signal when playback has completed, or if SDTA_Continuous is TRUE, when the next buffer is needed. Default for this tag is @{"NULL" Link "rexxsupport/NULL"}. Applicability is (IS). SDTA_SignalBit (ULONG) -- @{"Signal" Link "exec/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. 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 (IS). SDTA_Continuous (BOOL) -- Used to indicate that the sound datatype will be fed a continuous stream of data. Default for this tag is FALSE. Applicability is (I). The following tags are new for V44. SDTA_SignalBitMask (ULONG) -- @{"Signal" Link "exec/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 (IS). SDTA_SignalBitNumber (BYTE) -- @{"Signal" Link "exec/Signal()"} bit to use with SDTA_SignalTask or -1 to disable. Default for this tag is -1. Applicability is (IS). SDTA_SamplesPerSec (UWORD) -- 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 the 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. Applicability is (ISG). SDTA_ReplayPeriod (struct timeval *) -- 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 timeval tv_sec and tv_micro members will be set to 0. If the sample is to be played continuously, both timeval members will be set to 0xFFFFFFFF. Applicability is (G). SDTA_Pan (BYTE) -- 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 (IS). SDTA_FreeSampleData (BOOL) -- This tag controls whether sound.datatype will call @{"FreeVec()" Link "exec/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 (IS). SDTA_LeftSample (BYTE *) -- 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" Link "rexxsupport/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" Link "rexxsupport/NULL"} (V44). Applicability is (ISG). SDTA_RightSample (BYTE *) -- 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" Link "rexxsupport/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" Link "rexxsupport/NULL"} (V44). Applicability is (ISG). SDTA_SyncSampleChange (BOOL) -- 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" Link "INCLUDE:exec/tasks.h/Main" 23} 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 (IS). DTA_Immediate (BOOL) -- Select and query whether playback should start immediately after the object has passed the layout process. Default for this tag is FALSE. Applicability is (ISG). DTA_Repeat (BOOL) -- Select and query whether playback should loop indefinitely, regardless of the current SDTA_Cycles settings. Default for this tag is FALSE. Applicability is (ISG). SDTA_BitsPerSample (UBYTE) (V47) Set and get the actual bitrate of the sample which can be 8, 16, 24 or 32 bits. With this tag sound.datatype finally supports handling of samples >8 bits. This tag MUST be set for 16-, 24- or 32-bit sound data to get them (poorly) converted to 8-bit. NOTE: You must set this attribute *before* setting SDTA_SampleLength. Default for this tag is 8. Applicability is (ISG). @{b} NOTES@{ub} 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. The sound.datatype implementation has been cleaned up for V44 to allow for streaming subclasses to be written. Such subclasses will always return @{"NULL" Link "rexxsupport/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. @{b} BUGS@{ub} 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. @EndNode