File and compression routines

The following routines implement a fast buffered file I/O system, which supports the reading and w), title="Starts recording in the specified format.">start_sound_input, get_sound_input_cap_parm, get_sound_input_cap_rate, get_sound_input_cap_stereo.

int get_sound_input_cap_stereo();

Checks whether the current audio input driver is capable of stereo recording.

Return value: Returns non-zero if the driver is capable of stereo recording.

See also: start_sound_input, get_sound_input_cap_parm, get_sound_input_cap_bits, get_sound_input_cap_rate.
int get_sound_input_cap_rate(int bits, int stereo);

Returns the maximum possible sample frequency for recording in the specified format, or zero if these settings are not supported. The bits parameter is the number of bits of the audio, and stereo is a boolean parameter. Pass zero for mono, non-zero for stereo input. Example:
      int max_freq;
      ...
      /* What frequency can we record 8 bits mono at? */
      max_freq = get_sound_input_cap_rate(8, 0);
      if (max_freq > 22000) {
         /* Ok, 22KHz and above is good enough. */
      }
See also: start_sound_input, get_sound_input_cap_parm, get_sound_input_cap_bits, get_sound_input_cap_stereo.
int get_sound_input_cap_parm(int rate, int bits, int stereo);

Checks whether the specified recording frequency, number of bits, and mono/stereo mode are supported (and how) by the current audio driver.

Return value: The function returns one of the following possible values:

      0  = It is impossible to record in this format.
      1  = Recording is possible, but audio output
           will be suspended.
      2  = Recording is possible at the same time as
           playing other sounds (full duplex soundcard).
      -n = Sampling rate not supported, but rate 'n'
           would work instead.
See also: start_sound_input, get_sound_input_cap_bits, get_sound_input_cap_rate, get_sound_input_cap_stereo.
int set_sound_input_source(int source);

Selects the audio input source. The parameter should be one of the values:
      SOUND_INPUT_MIC
      SOUND_INPUT_LINE
      SOUND_INPUT_CD

Return value: The function returns zero on success, or -1 if the hardware does not provide an input select register (ie. you have no control over the input source).

See also: start_sound_input.
int start_sound_input(int rate, int bits, int stereo);

Starts recording in the specified format, suspending audio playback as necessary if the card is not full duplex.

Return value: Returns the buffer size in bytes if successful, or zero on error.

See also: install_sound_input, read_sound_input, stop_sound_input, digi_recorder, set_sound_input_source, get_sound_input_cap_parm, get_sound_input_cap_bits, get_sound_input_cap_rate, get_sound_input_cap_stereo.
void stop_sound_input();

Stops audio recording, switching the card back into the normal playback mode.
See also: start_sound_input.
int read_sound_input(void *buffer);

Retrieves the most recently recorded audio buffer into the specified location. The buffer size can be obtained by checking the return value from start_sound_input(). You must be sure to call this function at regular intervals during the recording (typically around 100 times a second), or some data will be lost. If you are unable to do this often enough from the mainline code, use the digi_recorder() callback to store the waveform into a larger buffer of your own.

Note: many cards produce a click or popping sound when switching between record and playback modes, so it is often a good idea to discard the first buffer after you start a recording. The waveform is always stored in unsigned format, with stereo data consisting of alternate left/right samples.

Return value: The function will return non-zero if a buffer has been copied or zero if no new data is yet available (you were too fast checking the input).

See also: start_sound_input.
extern void (*digi_recorder)();

If set, this function is called by the input driver whenever a new sample buffer becomes available, at which point you can use read_sound_input() to copy the data into a more permanent location. It runs in an interrupt context, so it must execute very quickly, the code and all memory that it touches must be locked, and you cannot call any operating system routines or access disk files. This currently works only under DOS.
See also: install_sound_input, start_sound_input.
extern void (*midi_recorder)(unsigned char data);

If set, this function is called by the MIDI input driver whenever a new byte of MIDI data becomes available. It runs in an interrupt context, so it must execute very quickly and all the code/data must be locked. This currently works only under DOS and Windows.
See also: install_sound_input, midi_out.

Back to contents
./usr/share/doc/liballegro-doc/html/alleg030.html0000644000000000000000000021327110434113023020406 0ustar rootroot Allegro Manual: File and compression routines

File and compression routines

The following routines implement a fast buffered file I/O system, which supports the reading and w), title="Starts recording in the specified format.">start_sound_input, get_sound_input_cap_parm, get_sound_input_cap_rate, get_sound_input_cap_stereo.

int get_sound_input_cap_stereo();

Checks whether the current audio input driver is capable of stereo recording.

Return value: Returns non-zero if the driver is capable of stereo recording.

See also: start_sound_input, get_sound_input_cap_parm, get_sound_input_cap_bits, get_sound_input_cap_rate.
int get_sound_input_cap_rate(int bits, int stereo);

Returns the maximum possible sample frequency for recording in the specified format, or zero if these settings are not supported. The bits parameter is the number of bits of the audio, and stereo is a boolean parameter. Pass zero for mono, non-zero for stereo input. Example:
      int max_freq;
      ...
      /* What frequency can we record 8 bits mono at? */
      max_freq = get_sound_input_cap_rate(8, 0);
      if (max_freq > 22000) {
         /* Ok, 22KHz and above is good enough. */
      }
See also: start_sound_input, get_sound_input_cap_parm, get_sound_input_cap_bits, get_sound_input_cap_stereo.
int get_sound_input_cap_parm(int rate, int bits, int stereo);

Checks whether the specified recording frequency, number of bits, and mono/stereo mode are supported (and how) by the current audio driver.

Return value: The function returns one of the following possible values:

      0  = It is impossible to record in this format.
      1  = Recording is possible, but audio output
           will be suspended.
      2  = Recording is possible at the same time as
           playing other sounds (full duplex soundcard).
      -n = Sampling rate not supported, but rate 'n'
           would work instead.
See also: start_sound_input, get_sound_input_cap_bits, get_sound_input_cap_rate, get_sound_input_cap_stereo.
int set_sound_input_source(int source);

Selects the audio input source. The parameter should be one of the values:
      SOUND_INPUT_MIC
      SOUND_INPUT_LINE
      SOUND_INPUT_CD

Return value: The function returns zero on success, or -1 if the hardware does not provide an input select register (ie. you have no control over the input source).

See also: start_sound_input.
int start_sound_input(int rate, int bits, int stereo);

Starts recording in the specified format, suspending audio playback as necessary if the card is not full duplex.

Return value: Returns the buffer size in bytes if successful, or zero on error.

See also: install_sound_input, read_sound_input, stop_sound_input, digi_recorder, set_sound_input_source, get_sound_input_cap_parm, get_sound_input_cap_bits, get_sound_input_cap_rate, get_sound_input_cap_stereo.
void stop_sound_input();

Stops audio recording, switching the card back into the normal playback mode.
See also: start_sound_input.
int read_sound_input(void *buffer);

Retrieves the most recently recorded audio buffer into the specified location. The buffer size can be obtained by checking the return value from start_sound_input(). You must be sure to call this function at regular intervals during the recording (typically around 100 times a second), or some data will be lost. If you are unable to do this often enough from the mainline code, use the digi_recorder() callback to store the waveform into a larger buffer of your own.

Note: many cards produce a click or popping sound when switching between record and playback modes, so it is often a good idea to discard the first buffer after you start a recording. The waveform is always stored in unsigned format, with stereo data consisting of alternate left/right samples.

Return value: The function will return non-zero if a buffer has been copied or zero if no new data is yet available (you were too fast checking the input).

See also: start_sound_input.
extern void (*digi_recorder)();

If set, this function is called by the input driver whenever a new sample buffer becomes available, at which point you can use read_sound_input() to copy the data into a more permanent location. It runs in an interrupt context, so it must execute very quickly, the code and all memory that it touches must be locked, and you cannot call any operating system routines or access disk files. This currently works only under DOS.
See also: install_sound_input, start_sound_input.
extern void (*midi_recorder)(unsigned char data);

If set, this function is called by the MIDI input driver whenever a new byte of MIDI data becomes available. It runs in an interrupt context, so it must execute very quickly and all the code/data must be locked. This currently works only under DOS and Windows.
See also: install_sound_input, midi_out.

Back to contents
./usr/share/doc/liballegro-doc/html/alleg030.html0000644000000000000000000021327110434113023020406 0ustar rootroot Allegro Manual: File and compression routines

File and compression routines

The following routines implement a fast buffered file I/O system, which supports the reading and w), title="Starts recording in the specified format.">start_sound_input, get_sound_input_cap_parm, get_sound_input_cap_rate, get_sound_input_cap_stereo.

int get_sound_input_cap_stereo();

Checks whether the current audio input driver is capable of stereo recording.

Return value: Returns non-zero if the driver is capable of stereo recording.

See also: start_sound_input, get_sound_input_cap_parm, get_sound_input_cap_bits, get_sound_input_cap_rate.
int get_sound_input_cap_rate(int bits, int stereo);

Returns the maximum possible sample frequency for recording in the specified format, or zero if these settings are not supported. The bits parameter is the number of bits of the audio, and stereo is a boolean parameter. Pass zero for mono, non-zero for stereo input. Example:
      int max_freq;
      ...
      /* What frequency can we record 8 bits mono at? */
      max_freq = get_sound_input_cap_rate(8, 0);
      if (max_freq > 22000) {
         /* Ok, 22KHz and above is good enough. */
      }
See also: start_sound_input, get_sound_input_cap_parm, get_sound_input_cap_bits, get_sound_input_cap_stereo.
int get_sound_input_cap_parm(int rate, int bits, int stereo);

Checks whether the specified recording frequency, number of bits, and mono/stereo mode are supported (and how) by the current audio driver.

Return value: The function returns one of the following possible values:

      0  = It is impossible to record in this format.
      1  = Recording is possible, but audio output
           will be suspended.
      2  = Recording is possible at the same time as
           playing other sounds (full duplex soundcard).
      -n = Sampling rate not supported, but rate 'n'
           would work instead.
See also: start_sound_input, get_sound_input_cap_bits, get_sound_input_cap_rate, get_sound_input_cap_stereo.
int set_sound_input_source(int source);

Selects the audio input source. The parameter should be one of the values:
      SOUND_INPUT_MIC
      SOUND_INPUT_LINE
      SOUND_INPUT_CD

Return value: The function returns zero on success, or -1 if the hardware does not provide an input select register (ie. you have no control over the input source).

See also: start_sound_input.
int start_sound_input(int rate, int bits, int stereo);

Starts recording in the specified format, suspending audio playback as necessary if the card is not full duplex.

Return value: Returns the buffer size in bytes if successful, or zero on error.

See also: install_sound_input, read_sound_input, stop_sound_input, digi_recorder, set_sound_input_source, get_sound_input_cap_parm, get_sound_input_cap_bits, get_sound_input_cap_rate, get_sound_input_cap_stereo.
void stop_sound_input();

Stops audio recording, switching the card back into the normal playback mode.
See also: start_sound_input.
int read_sound_input(void *buffer);

Retrieves the most recently recorded audio buffer into the specified location. The buffer size can be obtained by checking the return value from start_sound_input(). You must be sure to call this function at regular intervals during the recording (typically around 100 times a second), or some data will be lost. If you are unable to do this often enough from the mainline code, use the digi_recorder() callback to store the waveform into a larger buffer of your own.

Note: many cards produce a click or popping sound when switching between record and playback modes, so it is often a good idea to discard the first buffer after you start a recording. The waveform is always stored in unsigned format, with stereo data consisting of alternate left/right samples.

Return value: The function will return non-zero if a buffer has been copied or zero if no new data is yet available (you were too fast checking the input).

See also: start_sound_input.
extern void (*digi_recorder)();

If set, this function is called by the input driver whenever a new sample buffer becomes available, at which point you can use read_sound_input() to copy the data into a more permanent location. It runs in an interrupt context, so it must execute very quickly, the code and all memory that it touches must be locked, and you cannot call any operating system routines or access disk files. This currently works only under DOS.
See also: install_sound_input, start_sound_input.
extern void (*midi_recorder)(unsigned char data);

If set, this function is called by the MIDI input driver whenever a new byte of MIDI data becomes available. It runs in an interrupt context, so it must execute very quickly and all the code/data must be locked. This currently works only under DOS and Windows.
See also: install_sound_input, midi_out.

Back to contents
./usr/share/doc/liballegro-doc/html/alleg030.html0000644000000000000000000021327110434113023020406 0ustar rootroot Allegro Manual: File and compression routines

File and compression routines

The following routines implement a fast buffered file I/O system, which supports the reading and w), title="Starts recording in the specified format.">start_sound_input, get_sound_input_cap_parm, get_sound_input_cap_rate, get_sound_input_cap_stereo.

int get_sound_input_cap_stereo();

Checks whether the current audio input driver is capable of stereo recording.

Return value: Returns non-zero if the driver is capable of stereo recording.

See also: start_sound_input, get_sound_input_cap_parm, get_sound_input_cap_bits, get_sound_input_cap_rate.
int get_sound_input_cap_rate(int bits, int stereo);

Returns the maximum possible sample frequency for recording in the specified format, or zero if these settings are not supported. The bits parameter is the number of bits of the audio, and stereo is a boolean parameter. Pass zero for mono, non-zero for stereo input. Example:
      int max_freq;
      ...
      /* What frequency can we record 8 bits mono at? */
      max_freq = get_sound_input_cap_rate(8, 0);
      if (max_freq > 22000) {
         /* Ok, 22KHz and above is good enough. */
      }
See also: start_sound_input, get_sound_input_cap_parm, get_sound_input_cap_bits, get_sound_input_cap_stereo.
int get_sound_input_cap_parm(int rate, int bits, int stereo);

Checks whether the specified recording frequency, number of bits, and mono/stereo mode are supported (and how) by the current audio driver.

Return value: The function returns one of the following possible values:

      0  = It is impossible to record in this format.
      1  = Recording is possible, but audio output
           will be suspended.
      2  = Recording is possible at the same time as
           playing other sounds (full duplex soundcard).
      -n = Sampling rate not supported, but rate 'n'
           would work instead.
See also: start_sound_input, get_sound_input_cap_bits, get_sound_input_cap_rate, get_sound_input_cap_stereo.
int set_sound_input_source(int source);

Selects the audio input source. The parameter should be one of the values:
      SOUND_INPUT_MIC
      SOUND_INPUT_LINE
      SOUND_INPUT_CD

Return value: The function returns zero on success, or -1 if the hardware does not provide an input select register (ie. you have no control over the input source).

See also: start_sound_input.
int start_sound_input(int rate, int bits, int stereo);

Starts recording in the specified format, suspending audio playback as necessary if the card is not full duplex.

Return value: Returns the buffer size in bytes if successful, or zero on error.

See also: install_sound_input, read_sound_input, stop_sound_input, digi_recorder, set_sound_input_source, get_sound_input_cap_parm, get_sound_input_cap_bits, get_sound_input_cap_rate, get_sound_input_cap_stereo.
void stop_sound_input();

Stops audio recording, switching the card back into the normal playback mode.
See also: start_sound_input.
int read_sound_input(void *buffer);

Retrieves the most recently recorded audio buffer into the specified location. The buffer size can be obtained by checking the return value from start_sound_input(). You must be sure to call this function at regular intervals during the recording (typically around 100 times a second), or some data will be lost. If you are unable to do this often enough from the mainline code, use the digi_recorder() callback to store the waveform into a larger buffer of your own.

Note: many cards produce a click or popping sound when switching between record and playback modes, so it is often a good idea to discard the first buffer after you start a recording. The waveform is always stored in unsigned format, with stereo data consisting of alternate left/right samples.

Return value: The function will return non-zero if a buffer has been copied or zero if no new data is yet available (you were too fast checking the input).

See also: start_sound_input.
extern void (*digi_recorder)();

If set, this function is called by the input driver whenever a new sample buffer becomes available, at which point you can use read_sound_input() to copy the data into a more permanent location. It runs in an interrupt context, so it must execute very quickly, the code and all memory that it touches must be locked, and you cannot call any operating system routines or access disk files. This currently works only under DOS.
See also: install_sound_input, start_sound_input.
extern void (*midi_recorder)(unsigned char data);

If set, this function is called by the MIDI input driver whenever a new byte of MIDI data becomes available. It runs in an interrupt context, so it must execute very quickly and all the code/data must be locked. This currently works only under DOS and Windows.
See also: install_sound_input, midi_out.

Back to contents
./usr/share/doc/liballegro-doc/html/alleg030.html0000644000000000000000000021327110434113023020406 0ustar rootroot Allegro Manual: File and compression routines

File and compression routines