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

displaySpecifies the connection to the X server

error_baseThis 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.

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

sample_rateSpecifies the sample rate in Hertz. 

noise_idSpecifies the noise ID for the sample, as returned by XNoiseCreate. 

sampleThis is a pointer to the sample data. 

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

lengthThis is the length of the sample in sample units. 

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

noise_infoPointer 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 XNoiseQueryExtension 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 XNoiseQueryVersion 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

XNoiseEnable 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 XNoiseCreate. 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 XNoiseReset. 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 XNoiseDestroy 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 XNoiseAppend, 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 XNoisePlay. 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 XNoiseInfo. 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 intmin_rate;
unsigned intmax_rate;
unsigned intbest_rate;
unsigned charbest_format;
unsigned charrate_mismatch;
unsigned charoverlap;
unsigned charstatus;

} NoiseInfoRec, ∗NoiseInfoPtr;

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

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

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

best_formatThis 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.

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

NoiseBlockThe 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.

NoiseMergeThe requested noise is merged with the noise being played. 

statusThis 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 XNoiseBestSample. 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. 

X Version 11  —  Release 4