home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.0 / NeXTSTEP3.0.iso / NextDeveloper / Headers / sound / performsound.h < prev    next >
Text File  |  1992-01-31  |  6KB  |  145 lines
  1.  
  2. /*
  3.  *    performsound.h - recording and playback of sound.
  4.  *    Copyright 1988-89 NeXT, Inc.
  5.  *
  6.  */
  7.  
  8. #import "soundstruct.h"
  9. #import "sounderror.h"
  10.  
  11. typedef int (*SNDNotificationFun)(SNDSoundStruct *s, int tag, int err);
  12. #define SND_NULL_FUN ((SNDNotificationFun)0)
  13. /*
  14.  * Notification functions are called when some event occurs in the sound 
  15.  * library, and are always explicitly given to the sound library (i.e. as
  16.  * arguments in SNDStartPlaying).
  17.  * They always take three arguments: the sound structure, the tag, and
  18.  * an error code.
  19.  * The integer returned is ignored.
  20.  */
  21.  
  22. int SNDStartPlaying(SNDSoundStruct *s, int tag, int priority, int preempt,
  23.             SNDNotificationFun beginFun, SNDNotificationFun endFun);
  24. /*
  25.  * Initiates the playing of the sound "s". This function returns
  26.  * immediately, and playing continues in the background until the
  27.  * the entire sound has been played.
  28.  * The tag is used for identification of the sound for the SNDStop, 
  29.  * SNDWait, and SNDSamplesProcessed routines. It must be unique.
  30.  * The priority is used to help resolve conflict if the sound cannot
  31.  * be immediately played. Higher priorities can cause interruption
  32.  * of lower priority sounds. Zero is defined to be lowest priority,
  33.  * and larger numbers are of higher priority. Negative priorities are
  34.  * reserved. When a sound is interrupted, it may not be resumed (i.e. an
  35.  * interruption is equivalent to an abort).
  36.  * The preempt flag, when non-zero, allows the sound to interrupt other
  37.  * sounds of equal or inferior priority. If preempt is zero, then the sound is
  38.  * enqueued for playback on a first-come-first-served basis (the priority is
  39.  * not used to determine when to play the sound, but rather only to determine
  40.  * what can interrupt it while it is playing).
  41.  * Both the beginFun and endFun are optional: when non-null, they call
  42.  * the given function with the soundstruct, tag, and an error code as
  43.  * arguments, when playback of the  sound begins and ends, respectively.
  44.  *BSdse functions are called in the context of a background thread. 
  45.  * This routine returns an error if the sound cannot be played.
  46.  */
  47.  
  48. int SNDWait(int tag);
  49. /*
  50.  * Return only when playback or recording of the sound matching the given tag 
  51.  * has completed. If several requests have the same tag, the last one is
  52.  * waited for.
  53.  * An error code is returned.
  54.  */
  55.  
  56. int SNDStop(int tag);
  57. /*
  58.  * Terminates the playback or recording of sound with the given tag.
  59.  * An error code is returned.
  60.  */
  61.  
  62. int SNDStartRecording(SNDSoundStruct *s, int tag, int priority, int preempt,
  63.              SNDNotificationFun beginFun, SNDNotificationFun endFun);
  64. /*
  65.  * Begins recording into the specified sound structure.
  66.  * The codec type, dsp_data types, and compressed types are supported.
  67.  */
  68.  
  69. int SNDStartRecordingFile(char *fileName, SNDSoundStruct *s,
  70.               int tag, int priority, int preempt,
  71.               SNDNotificationFun beginFun, SNDNotificationFun endFun);
  72. /*
  73.  * Same as SNDStartRecording() but writes directly to file fileName.  The sound data
  74.  * is NOT returned in "s".
  75.  */
  76.  
  77. int SNDSamplesProcessed(int tag);
  78. /*
  79.  * Return a count of the number of samples played or recorded in the sound 
  80.  * matching the given tag.
  81.  * A negative return value indicates an error.
  82.  */
  83.  
  84. int SNDModifyPriority(int tag, int new_priority);
  85. /*
  86.  * Modifies the priority of the sound matching the given tag.
  87.  * This could cause the sound to either be interrupted or played
  88.  * immediately.
  89.  * An error code is returned.
  90.  */
  91.  
  92. int SNDSetVolume(int left, int right);
  93. int SNDGetVolume(int *left, int *right);
  94. /*
  95.  * Get/set the volume of the sound for left and right channels.
  96.  * The line out jacks on the back of the monitor are not affected;
  97.  * only the speaker (if it is not muted) and the headphone levels
  98.  * are affected.
  99.  * An error code is returned.
  100.  *  
  101.  */
  102.  
  103. int SNDSetMute(int speakerOn);
  104. int SNDGetMute(int *speakerOn);
  105. /*
  106.  * Set/get the state of the monitor's built-in speaker. Zero indicates
  107.  * that the speaker is silent. This does not affect the line out jacks
  108.  * on the back of the monitor -- they are always enabled.
  109.  * An error code is returned.
  110.  */
  111.  
  112. int SNDSetCompressionOptions(SNDSoundStruct *s, int bitFaithful, int dropBits);
  113. int SNDGetCompressionOptions(SNDSoundStruct *s, int *bitFaithful, int *dropBits);
  114. /*
  115.  * Set/get the compression options for the sound "s."  SNDStartRecording(BSees
  116.  * these options when recording into the sound.  If bitFaithful is non-zero,
  117.  * the recorded sound can be decompressed exactly back to its original samples.
  118.  * Otherwise the decompressed sound will have some degradation.  The dropBits
  119.  * parameter specifys the number of bits to right shift off of each sample
  120.  * before compressing.  It ranges from 4 to 8 bits, with higher numbers
  121.  * giving more compression but less fidelity.  In bit faithful mode, dropBits
  122.  * may affect the amount of compression, but decompression will still be
  123.  * exact.
  124.  * If this function is not called before recording, bitFaithful defaults to
  125.  * true and dropBits defaults to 4.
  126.  * An error code is returned.
  127.  */
  128.  
  129. int SNDSetFilter(int filterOn);
  130. int SNDGetFilter(int *filterOn);
  131. /*
  132.  * Set/get the state of the low-pass filter. Zero indicates
  133.  * that the filter is off. The low-pass filter is used for
  134.  * playing back emphasized sounds.
  135.  * An error code is returned.
  136.  */
  137.  
  138. int SNDVerifyPlayable(SNDSoundStruct *s);
  139. /*
  140.  * Returns SND_ERR_NONE (0) if sound is in a playable format, or
  141.  * SND_ERR_CANNOT_PLAY if it requires format conversion in advance
  142.  * of playing (or if it is inherently unplayable such as format
  143.  * SND_FORMAT_DSP_CORE).
  144.  */
  145.