Extensions are a way to provide for future expansion of the &AL; API. Typically, extensions are specified and proposed by a vendor, and can be treated as vendor neutral if no intellectual property restrictions apply. Extensions can also be specified as, or promoted to be, ARB extensions, which is usually the final step before adding a tried and true extension to the core API. ARB extensions, once specified, have mandatory presence for backwards compatibility. The handling of vendors-specific or multi-vendor extensions is left to the implementation. The IA-SIG I3DL2 Extension is an example of multi-vender extensions to the current &AL; core API. To use an extension, the application will have to obtain function addresses and enumeration values. Before an extension can be used, the application will have to verify the presence of an extension using IsExtensionPresent(). The application can then retrieve the address (function pointer) of an extension entry point using GetProcAddress. Extensions and entry points can be Context-specific, and the application can not count on an Extension being available based on the mere return of an entry point. The application also has to maintain pointers on a per-Context basis. &bool; IsExtensionPresent const &ubyte; * extName Returns TRUE if the given extension is supported for the current context, FALSE otherwise. This function is inspired by the GLU addition, but placed in the core API as we intend to avoid a separate ALU. This function avoids potential string overflow and string parsing issues (strstr) raised by GetString( EXTENSIONS ). ]]> GetString( EXTENSIONS ) is supported as well, as it allows for easy archiving and priting of the list of supported extensions. ]]> &void;* GetProcAddress const &ubyte; * funcName Returns NULL if no entry point with the name funcName can be found. Implementations are free to return NULL if an entry point is present, but not applicable for the current context. However the specification does not guarantee this behavior. Applications can use GetProcAddress to obtain core API entry points, not just extensions. This is the recommended way to dynamically load and unload &AL; DLL's as sound drivers. Original spec required all addresses are Context independent. This matches the Linux &OGL; ABI specification, but imposes additional implementation constraints. For now, the specification does not guarantee this. ]]> To obtain enumeration values for extensions, the application has to use GetEnumValue of an extension token. Enumeration values are defined within the &AL; namespace and allocated according to specification of the core API and the extensions, thus they are context-independent. &uint; GetEnumValue const &ubyte; enumName Returns 0 if the enumeration can not be found. The presence of an enum value does not guarantee the applicability of an extension to the current context. A non-zero return indicates merely that the implementation is aware of the existence of this extension. Implementations should not attempt to return 0 to indicate that the extensions is not supported for the current context. The literal value 0 is guaranteed for a number of AL enums, such as FALSE, NONE, ZERO. As with GL applications might employ sloppy use of this identity. It also means that enums with zero value can not be queried through GetEnumValue, a minor flaw given the constraints of ABI backward compatibility. The recommended value to compare GetEnumValue results with is NONE. ]]> Extensions are required to use a postfix that separates the extension namespace from the core API's namespace. For example, an ARB-approved extension would use "_ARB" with tokens (ALenum), and "ARB" with commands (function names). A vendor specific extension uses a vendor-chosen postfix, e.g. Loki Extensions use "_LOKI" and "LOKI", respectively. There are no ARB Extensions defined yet, as the ARB has yet to be installed. For the time being this section will list externally proposed extensions, namely the extension based on the IASIG Level 2 guideline. The IA-SIG I3DL2 guideline defines a set of parameters to control the reverberation characteristics of the environment the listener is located in, as well as filtering or muffling effects applied to individual Sources (useful for simulating the effects of obstacles and partitions). These features are supported by a vendor neutral extension to &AL; (TBA). The IA-SIG 3D Level 2 rendering guideline provides related information. Do we need global setters for these: DIRECT_IASIG/DIRECT_HIGH_FREQUENCY_IASIG? ROOM_IASIG/ROOM_HIGH_FREQUENCY_IASIG? ]]> &Par; &Sig; &Val &Def; ENV_ROOM_EXT f [0.0, 1.0] 1.0f Description: ??? &Par; &Sig; &Val &Def; ENV_ROOM_HIGH_FREQUENCY_EXT f [0.0, 1.0] 0.1f ??? Description: ??? &Par; &Sig; &Val &Def; ENV_DECAY_TIME_EXT f [0.1, 20.0] 1.0f Description: ??? What's up with the defaults? Not a normalized range and a global Scale to set? &Par; &Sig; &Val &Def; ENV_DECAY_HIGH_FREQUENCY_RATIO_EXT f [0.1, 2.0] 0.5f Description: ??? What's up with the defaults? Not a normalized range and a global Scale to set? &Par; &Sig; &Val &Def; ENV_REFLECTIONS_EXT f [0.1, 3.0] 1.0f Description: ??? What's up with the defaults? Not a normalized range and a global Scale to set? &Par; &Sig; &Val &Def; ENV_REFLECTIONS_DELAY_EXT f [0.0, 0.3] 0.02f Description: ??? What's up with the defaults? Not a normalized range and a global Scale to set? &Par; &Sig; &Val &Def; ENV_REVERB_EXT f [0.0, 10.0] 1.0f Description: ??? What's up with the defaults? Not a normalized range and a global Scale to set? &Par; &Sig; &Val &Def; ENV_REVERB_DELAY_EXT f [0.0, 0.1] 0.04f Description: ??? What's up with the defaults? Not a normalized range and a global Scale to set? &Par; &Sig; &Val &Def; ENV_DIFFUSION_EXT f [0.0, 100.0] 100.0f Description: ??? What's up with the defaults? Not a normalized range and a global Scale to set? &Par; &Sig; &Val &Def; ENV_DENSITY_EXT f [0.0, 100.0] 100.0f Description: ??? What's up with the defaults? Not a normalized range and a global Scale to set? &Par; &Sig; &Val &Def; ENV_HIGH_FREQUENCY_REFERENCE_EXT f [20.0, 20000.0] 5000.0 Description: ??? What's up with the defaults? Not a normalized range and a global Scale to set? TBA. ]]> ]]> The extensions described have at one point been in use for experimental purposes, proof of concept, or short term needs. They are preserved for backwards compatibility. Use is not recommended, avialability not guaranteed. Most of these will be officially dropped by the time API revision 2.0 is released. &AL; currently does not provide a separate processing chain for multichannel data. To handle stereo samples, the following alternative entry point to BufferData has been defined. &void; BufferWriteData &uint; bufferName &enum; format &void;* data &sizei; size &uint; frequency &enum; internalFormat Valid formats for internalFormat are FORMAT_MONO8, FORMAT_MONO16, FORMAT_STEREO8, and FORMAT_STEREO16. Experimental implementation to append data to an existing buffer. Obsoleted by Buffer Queueing. TBA. It is possible that a consistent implementation of this extension will require distinguishing streaming from regular buffers at creation time, instead of making this distinction implied by the use of BufferData vs. BufferAppendData. ]]> Specify data to be filled into a streaming buffer. This takes the current position at the time of the call, and returns the number of samples written. ALsizei ALAPIENTRY alBufferAppendData( ALuint buffer, ALenum format, ALvoid* data, ALsizei size, ALuint freq ); ]]> Currently there is a function call on the Linux side, alGenStreamingBuffers(), which generates a Buffer intended for streaming. The intent of this function was the provide a clear creation point for streaming buffers, rather than the previous behaviour of a Buffer "magically" becoming streaming Buffer the first time BufferAppendData() was called on it. However, it's hard to believe this anomaly in the API can be any better. What about DelStreamingBuffers()? IsStreamingBuffer()? The design problem here is that we handle qualitatively different objects using the same API. Streaming and non-streaming buffers are fundamentally different. If we create an API that makes it easy to mistake one for the other, or worse, if we decide to quietly convert one type of object into another in some cases, we create a plethora of error cases for the implementation and the app coder to catch. Separating the Factory methods for the objects allows us to omit an specialization API that will accidentally be called more than once, and saves us handling different stages of "initialization state". AL should not have any notion of "partially initialized" or "incomplete" objects: misery and despair lie down that road. If necessary the entire API should be duplicated (after all, nobody handles 1D, 2D, and 3D textures using the same GL API hooks), but as the AL implementation has the ability to distinguish streaming and non-streamin buffers internally there might not be a need. Unless a concrete alternative is proposed to resolve the "anomaly" it will be the preferred method to avoid an API that is leaner at the expense of being more error-prone. ]]> Experimental implementation to allow the application to specify a decoding callback for compression formats and codecs not supported by &AL;. This is supposed to be used if full uncompression by the application is prohibited by memory footprint, but streaming (by queueing) is not desired as the compressed data can be kept in memory in its entirety. If mixing can be done from the compressed data directly, several sources can use the sample without having to be synchronized. For compression formats not supported by AL, however, partial decompression has to be done by the application. This extension allows for the implementation to "pull" data, using apllication provided decompression code. The use of this callback by the &AL; implementation makes sense only if late decompression (incremerntal, on demand, as needed for mixing) is done, as full early compression (ahead-of-time) inside the implementation would exact a similar memory footprint. TBA. This extension forces execution of third party code during (possibly threaded) driver operation, and might also require state management with global variables for decoder state, which raises issues of thread safety and use for multiple buffers. This extension should be obsolete as soon as &AL; supports a reasonable set of state of the art compression and encoding schemes. To support infinite looping, a boolean LOOP was introduced. With the introduction of buffer queueing and the request for support for a limited number of repetitions, this mechanism was redundant. This extension is not supported for buffer queue operations, attempts to use it will cause an ILLEGAL_OPERATION error. For backwards compatibility it is supported as the equivalent to Source( sName, PLAY_COUNT, MAX_INTEGER ) For the query LOOP==TRUE, the comparison PLAY_COUNT!=MAX_INTEGER has to be executed on the queue, not the current value which is decremented for a PLAYING Source. &Par; &Sig; &Val &Def; LOOP_LOKI b &TRUE; &FALSE; &FALSE; Description: &TRUE; indicates that the Source will perform an inifinite loop over the content of the current Buffer it refers to. The following has been obsoleted by explicit Source State query. hack. &Par; &Sig; &Val &Def; BYTE_LOKI ui n/a n/a Current byte for the buffer bound to the source interpreted as an offset from the beginning of the buffer. ]]> In external file now. ]]>