XNoise(3Xext)

NAME
XNoiseQueryExtension, XNoiseQueryVersion, XNoiseEnable, XNoiseCreate, XNoiseReset, XNoiseDestroy, XNoiseAppend, XNoisePlay, XNoiseInfo, XNoiseBestSample - the Acorn-Noise extension

SYNTAX
#include <X11/extensions/noise.h>

Bool
XNoiseQueryExtension(display, error_base)
      Display *display;
      int *error_base;

XNoiseQueryVersion(display, major_version, minor_version)
      Display *display;
      int *major_version;
      int *minor_version;

XNoiseEnable(display, mode)
      Display *display;
      int mode;

Noise
XNoiseCreate(display, sample_rate)
      Display *display;
      int sample_rate;

XNoiseReset(display, noise_id, sample_rate)
      Display *display;
      Noise noise_id;
      int sample_rate;

XNoiseDestroy(display, noise_id)
      Display *display;
      Noise noise_id;

XNoiseAppend(display, noise_id, sample, sample_size, length)
      Display *display;
      Noise noise_id;
      void *sample;
      int sample_size;
      int length;

XNoisePlay(display, noise_id, volume)
      Display *display;
      Noise noise_id;
      int volume;

XNoiseInfo(display, noise_info)
      Display *display;
      NoiseInfoPtr noise_info;

unsigned int
XNoiseBestSample(display, sample_rate)
      Display *display;
      unsigned int sample_rate;

ARGUMENTS

display
    Specifies the connection to the X server

error_base
    This is set to the error number for the first error for the extension.

major_version
    Set to the major version number of the extension.

minor_version
    Set to the minor version number of the extension.

mode
    Specifies the mode of the Noise extension. This can be NoiseOn, NoiseOff or NoiseBell.

sample_rate
    Specifies the sample rate in Hertz.

noise_id
    Specifies the noise ID for the sample, as returned by XNoiseCreate.

sample
    This is a pointer to the sample data.

sample_size
    This is the size of a sample unit in bits, which should be 8, 16 or 32.

length
    This is the length of the sample in sample units.

volume
    Specifies the volume to play the sound at, as a percentage.

noise_info
    Pointer to the record in which to return the sound system information.

DESCRIPTION
Acorn X servers support a new sound extension, known as Acorn-Noise. This extension lets X client programs access the sound interface in the kernel through an X connection. Sound capabilities are limited to playing samples. The routines described here are the X library extensions used to access the extension.

The include file <X11/extensions/noise.h> defines the constants and data structures required by the extension.

QUERYING THE NOISE EXTENSION
The function will return True if the Acorn-Noise extension is supported by the server, otherwise it will return False. If the extension is supported then error_base will be set to the error number for the first and only error generated by this extension. This error is BadNoise which is generated when an invalid noise id is passed to any of the relevant functions.

The function determines the major and minor version numbers for the noise extension on display. The numbers are placed in the result parameters.

ENABLING THE NOISE EXTENSION
turns the extension on and off. The mode must be one of the constants NoiseOn, NoiseOff or NoiseBell which are defined in noise.h. An invalid mode will cause a BadValue error to be generated. If mode is NoiseOn then the extension will be enabled. On systems where the sound device can only be used by one process at any one time the server will have exclusive use of the device until the extension is disabled. If the enable fails (perhaps because another process is using the sound device) then BadAlloc is generated. If mode is NoiseOff then exclusive use of the sound device is relinquished and the server will not be able to make any sounds. If mode is NoiseBell and more than one process can use the sound device then the server may implement this as NoiseOn. If the sound device allows limited access by all processes then the server may still be able to make simple bell sounds. If it has no other way of producing sounds then this will be implemented as NoiseOff. The server will implement this option so that it can make the widest variety of noises without retaining exclusive use of the sound device.

XNoiseEnable can generate BadValue and BadAlloc errors.

INTERNAL NOISES
By default, the first two noise identification numbers are reserved for the internal bell and key click noises. These can be used in the same manner as any other noise id. To use the internal noises pass either InternalBell or InternalKeyclick as the noise id parameter in any of the appropriate functions.

CREATING AND MANIPULATING NOISES
To create a new noise use This function allocates space in the server for a new noise and returns the id of the noise which is created. The sample rate provided remains fixed for this noise and can only be changed by the XNoiseReset function. If the server can not allocate enough space for the sound then a BadAlloc error is generated. If the sample rate is out of range then BadValue will be generated (the valid range is specified by the min_rate and max_rate fields in the NoiseInfoRec returned by XNoiseInfo). The created noise is initially empty and will create no sound when played.

XNoiseCreate can generate BadAlloc and BadValue errors.

To reset a noise use This is the equivalent of an XNoiseCreate call while maintaining the same noise id. The sample rate provided remains fixed for this noise and can only be changed by another XNoiseReset call at which point all of the associated noise data will be lost. The reset noise is initially empty and will create no sound when played. This function has been provided mainly so that the internal noises can be altered. If the sample rate is out of range then BadValue will be generated (the valid range is specified by the min_rate and max_rate fields in the NoiseInfoRec returned by XNoiseInfo).

XNoiseReset can generate BadNoise and BadValue errors.

The function causes the server to deallocate the space being used for the specified noise. The noise_id is no longer valid after this function has been called. If an internal noise is specified then this function will set the specified internal noise to its default.

XNoiseDestroy can generate a BadNoise error.

To append sample data to a noise, use which appends sample data to the end of an existing noise. The specified noise may be empty. The internal noises can be written to in the same manner as other noises. The sample is assumed to have the same sample rate as the specified noise. If sample_size is not one of 8, 16 or 32 then BadValue will be generated. If the sample is too large to fit in one protocol request then the data will be automatically split into separate append requests.

XNoiseAppend can generate BadNoise, BadValue and BadAlloc errors.

PLAYING NOISES
To play a specific sound use This function will play the specified sound at the specified volume. The volume must be in the range 0 to 100 - it is a percentage volume at which to play the noise. If it is not in this range then a BadValue error will be generated. The action taken if a noise is already being played depends on the overlap flag returned in the NoiseInfoRec by XNoiseInfo.

XNoisePlay can generate BadNoise and BadValue errors.

NOISE INFORMATION
To determine the optimal values for the sound system parameters use This function writes the optimal values for various sound system parameters into the NoiseInfoRec provided. This structure is defined in noise.h and looks like this:

typedef struct {
    unsigned int	min_rate;
    unsigned int	max_rate;
    unsigned int	best_rate;
    unsigned char	best_format;
    unsigned char	rate_mismatch;
    unsigned char	overlap;
    unsigned char	status;
} NoiseInfoRec, *NoiseInfoPtr;

min_rate
    This is the minimum sample rate supported by the system (in Hz).

max_rate
    This is the maximum sample rate supported by the system (in Hz).

best_rate
    This is the optimum sample rate for the implementation (in Hz).

best_format
    This is the best sample format for the system (8, 16 or 32 bits).

rate_mismatch
    This is a flag which specifies how the system handles rate mismatches. This can be one of:

    NoiseNearest
        The nearest sample rate is used.

    NoiseInterpolate
        The sample is interpolated to the actual sample rate.

overlap
    This is a flag which specifies how the system handles overlapping play requests. This can be one of:

    NoiseBlock
        The server will hang until the requested noise has been played. This means that there will never be any overlapping play requests.

    NoiseDiscard
        The play request is discarded if a noise is already playing.

    NoiseSequence
        The noise which is to be played is placed in a queue of noises and will be played at an unspecified time in the future.

    NoiseMerge
        The requested noise is merged with the noise being played.

status
    This is a flag which specifies whether the sound system is enabled or disabled. This can be one of NoiseOff, NoiseBell or NoiseOn.

To determine the best sample rate that the system will use when a given sample rate is requested use This function returns the sample rate which the system will use when the given sample rate is used in an XCreateNoise or XResetNoise function call.

SAMPLE FORMAT
The sample format used by the extension is a signed little-endian one. Sample units are 8, 16 or 32 bits long. These are converted automatically in the X server to VIDC format.

SEE ALSO
xnoise(1)

AUTHORS
Steve Cormie, Acorn Computers Ltd. - Specification
Steve Hunt, Acorn Computers Ltd. - Implementation

COPYRIGHT
Copyright (c) 1990 Acorn Computers Ltd.