API - libpac Manual

— Function: int pac_init (long rate, int bits, int channels);

Initialize libpac. Call this function before calling anything other than pac_test or pac_exit.
The arguments specify the format of the audio data that libpac will generate. rate must be between PAC_RATE_MIN (currently 4000) and PAC_RATE_MAX (currently 48000), bits must be 8, 16, or 32 and channels must be 1 or 2.
Return 0 on success or -1 on failure. On failure, errno is set to PAC_EALREADY if the library is already initialized or PAC_EINVAL if an invalid argument was passed.

— Function: void pac_exit (void);

Free all resources used by libpac. This includes all modules opened by pac_open that has not been closed by pac_close. You do not have to call pac_init before calling this function.

— Function: int pac_test (const char *filename);

Return true if filename seems to be a PAC module. Note that even if this function returns true there's no guarantee that pac_open will succeed. However, if this function fails so will pac_open.
On failure, errno is set to PAC_EFORMAT if the file is not a PAC module. Otherwise it is set to some system specific error code. See pac_perror and pac_strerror.

— Function: struct pac_module * pac_open (const char *filename);

Open the PAC module pointed to by filename. Return pointer to the open module on success or NULL on failure. On failure, errno is set to PAC_EFORMAT if filename is not a valid PAC module. Otherwise it is set to some system specific error code.
If pac_test succeeded on filename but pac_open fails, try disabling PAC_STRICT_FORMAT. See pac_disable.

— Function: void pac_close (struct pac_module *module);

Close module and free all resources allocated to it. module may be NULL.

— Function: long pac_read (struct pac_module *module, void *buffer, long size);

Read at most size bytes from module into buffer. size is rounded down to the nearest multiple of the frame size. The frame size is the number of bytes required to represent one sample on all channels (one sample frame). 8-bit samples are stored as signed char and range from -127 to 127 while 16-bit samples are stored as short and range from -32767 to 32767. 32-bit samples are stored as long and are read directly (no volume reduction or clipping performed) from the internal mixing buffer.
To read N seconds worth of audio you need to read N * rate * frame_size bytes. E.g., if you called pac_init (44100, 16, 2); the frame size is sizeof (short) * 2 bytes. N seconds worth of audio data is then N * 44100 * sizeof (short) * 2 bytes.
On success, the function returns the number of bytes read into buffer. This may be 0 if module has reached the end or if size was less than the frame size. It may be less than size if size was not a multiple of the frame size or module reached the end. The function returns -1 on failure.

— Function: long pac_seek (struct pac_module *module, long offset, int whence);

Seek offset frames into module. The whence argument can be one of SEEK_SET, SEEK_CUR, or SEEK_END. They have the same meaning as in the ISO C fseek function.
Return the new position on success. Return -1 on failure and set errno to PAC_ENOTSUP if module is not seekable or PAC_EINVAL if offset is out of range or whence is invalid. On failure the current position is left unchanged.

— Function: long pac_tell (const struct pac_module *module);

Return the current read position, in frames, for module.

— Function: int pac_eof (const struct pac_module *module);

Return true if module has reached the end. This occur after reading the last sample frame.

— Function: long pac_length (const struct pac_module *module);

Return the total length, in frames, of module. If the length cannot be determined or is too long, the function returns 0. This also means that seeking is not available.

— Function: const char * pac_title (const struct pac_module *module);

Return a pointer to the module song title. The length is at most PAC_NAME_MAX (currently 40), not including the null character.

— Function: void pac_enable (int flags);

Enable libpac options. These options affect how modules are loaded by pac_open and read by pac_read. flags can be any combination of the following:

`PAC_GUS_EMULATION'
Emulate Gravis UltraSound hardware volume ramping. It only affects version 1.4 PAC modules using the note-off effect (Cxy).
`PAC_ENDLESS_SONGS'
Songs that do not explicitly stop will play forever. pac_length always returns the length of the song as if this option was disabled. This also means that pac_tell and pac_seek operate within this length. When the song “wraps”, pac_tell will begin at 0 again.
`PAC_INTERPOLATION'
Linear interpolation for slightly better sample-rate conversion.
`PAC_VOLUME_REDUCTION'
Reduce the mixing volume to avoid excessive clipping. This option is disabled when reading 32-bit data (see pac_init and pac_read).
`PAC_STRICT_FORMAT'
Fail pac_open if non-critical errors are encountered such as missing sounds, channel settings, invalid loop points, etc. Disable this option to allow reading these files. They may or may not play correctly.
`PAC_NOSOUNDS'
Enable this option to prevent pac_open from loading and allocating storage for the sounds. You can still play the module but it will, ofcourse, be inaudible.
`PAC_MODE_DEFAULT'
The default mode, set by pac_init, is (PAC_GUS_EMULATION|PAC_INTERPOLATION|PAC_STRICT_FORMAT|PAC_VOLUME_REDUCTION).

You can call pac_enable (0xff) to enable all options.

— Function: int pac_isenabled (int flags);

Query libpac options. Return true if one or more of the bits in flags is set. See pac_enable for a description of the available options.

— Function: void pac_disable (int flags);

Disable libpac options. See pac_enable for a description of the available options.
You can call pac_disable (0xff) to disable all options.

— Function: void pac_perror (const char *string);

Print string to stderr followed by a colon and a blank, then a string describing the last error encountered. If string is NULL or *string is '\0' then only the error string is printed. If errno is not a libpac error code, the function calls perror.

2 API