add dox to posix.h;
pre-existing dox have been converted to /* */; added "KEEP IN SYNC WITH WIKI" warning This was SVN commit r1993.
This commit is contained in:
parent
f1f945c2fa
commit
1b2527c49e
@ -1,3 +1,52 @@
|
||||
// POSIX definitions
|
||||
// Copyright (c) 2002-5 Jan Wassenberg
|
||||
//
|
||||
// This program is free software; you can redistribute it and/or
|
||||
// modify it under the terms of the GNU General Public License as
|
||||
// published by the Free Software Foundation; either version 2 of the
|
||||
// License, or (at your option) any later version.
|
||||
//
|
||||
// This program is distributed in the hope that it will be useful, but
|
||||
// WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||||
// General Public License for more details.
|
||||
//
|
||||
// Contact info:
|
||||
// Jan.Wassenberg@stud.uni-karlsruhe.de
|
||||
// http://www.stud.uni-karlsruhe.de/~urkt/
|
||||
|
||||
/*
|
||||
|
||||
[KEEP IN SYNC WITH WIKI]
|
||||
|
||||
this header makes available commonly used POSIX (Portable Operating System
|
||||
Interface) definitions, e.g. thread, file I/O and socket APIs.
|
||||
on Linux and OS X we just include the requisite headers; Win32 doesn't really
|
||||
support POSIX (*), so we have to implement everything ourselves.
|
||||
|
||||
rationale: this is preferable to a wrapper for several reasons:
|
||||
- less code (implementation is only needed on Win32)
|
||||
- no lock-in (the abstraction may prevent not-designed-for operations
|
||||
that the POSIX interface would have allowed)
|
||||
- familiarity (many coders already know POSIX)
|
||||
|
||||
if a useful definition is missing, feel free to add it!
|
||||
|
||||
implementation reference is the "Single Unix Specification v3"
|
||||
(http://www.unix.org/online.html) - it's similar to the POSIX standard
|
||||
(superset?) and freely available.
|
||||
|
||||
|
||||
* Win32 does have a POSIX subsystem (mandated by a government contract),
|
||||
but it is crippled. only apps with the PE header 'subsystem' field set to
|
||||
"POSIX" can use the appendant DLL, and then they can't call the regular
|
||||
Windows APIs. this is obviously unacceptable - GDI is needed to set up OpenGL.
|
||||
|
||||
we therefore need to emulate POSIX functions using the Win32 API.
|
||||
fortunately, many POSIX functions are already implemented in the VC CRT and
|
||||
need only be renamed (e.g. _open, _stat).
|
||||
|
||||
*/
|
||||
|
||||
#ifdef _WIN32
|
||||
|
||||
@ -25,4 +74,4 @@
|
||||
#include <netinet/tcp.h>
|
||||
#include <arpa/inet.h>
|
||||
|
||||
#endif // #ifdef _WIN32 else
|
||||
#endif // #ifdef _WIN32
|
||||
|
||||
@ -225,6 +225,8 @@ extern void h_mgr_shutdown(void);
|
||||
|
||||
/*
|
||||
|
||||
[KEEP IN SYNC WITH WIKI]
|
||||
|
||||
introduction
|
||||
------------
|
||||
|
||||
|
||||
@ -18,50 +18,65 @@
|
||||
|
||||
#include "handle.h"
|
||||
|
||||
/*
|
||||
|
||||
// overview:
|
||||
// this module provides a moderately high-level sound interface. basic usage
|
||||
// is opening a sound and requesting it be played; it is closed automatically
|
||||
// when playback has finished (fire and forget).
|
||||
// any number of sound play requests may be issued; the most 'important' ones
|
||||
// are actually played (necessary due to limited hardware mixing capacity).
|
||||
// 3d positional sounds (heard to emanate from a given spot) are supported.
|
||||
// active sound instances are referenced by Handles, so changing volume etc.
|
||||
// during playback is possible (useful for fadeout).
|
||||
//
|
||||
// sound setup:
|
||||
// OpenAL provides portable access to the underlying sound hardware, and
|
||||
// falls back to software mixing if no acceleration is provided.
|
||||
// we allow the user to specify the device to use (in case the default
|
||||
// has problems) and maximum number of sources (to reduce mixing cost).
|
||||
//
|
||||
// performance:
|
||||
// much effort has been invested in efficiency: all sound data is cached,
|
||||
// so every open() after the first is effectively free. large sound files are
|
||||
// streamed from disk to reduce load time and memory usage. hardware mixing
|
||||
// resources are suballocated to avoid delays when starting to play.
|
||||
// therefore, the user can confidently fire off hundreds of sound requests.
|
||||
// finally, lengthy initialization steps are delayed until the sound engine
|
||||
// is actually needed (i.e. upon first open()). perceived startup time is
|
||||
// therefore reduced - the user sees e.g. our main menu earlier.
|
||||
//
|
||||
// terminology:
|
||||
// "hardware voice" refers to mixing resources on the DSP. strictly
|
||||
// speaking, we mean 'OpenAL source', but this term is more clear.
|
||||
// voice ~= source, unless expensive effects (e.g. EAX) are enabled.
|
||||
// note: software mixing usually doesn't have a fixed 'source' cap.
|
||||
// "gain" is quantified volume. 1 is unattenuated, 0.5 corresponds to -6 dB,
|
||||
// and 0 is silence. this can be set per-source as well as globally.
|
||||
// "position" of a sound is within the app's coordinate system,
|
||||
// the orientation of which is passed to snd_update.
|
||||
// "importance" of a sound derives from the app-assigned priority
|
||||
// (e.g. voiceover must not be skipped in favor of seagulls) and
|
||||
// distance from the listener. it's calculated by our prioritizer.
|
||||
// "virtual source" denotes a sound play request issued by the app.
|
||||
// this is in contrast to an actual AL source, which will be mixed
|
||||
// into the output channel. the most important VSrc receive an al_src.
|
||||
// "sound instances" store playback parameters (e.g. position), and
|
||||
// reference the (centrally cached) "sound data" that will be played.
|
||||
[KEEP IN SYNC WITH WIKI]
|
||||
|
||||
overview
|
||||
--------
|
||||
|
||||
this module provides a moderately high-level sound interface. basic usage
|
||||
is opening a sound and requesting it be played; it is closed automatically
|
||||
when playback has finished (fire and forget).
|
||||
any number of sound play requests may be issued; the most 'important' ones
|
||||
are actually played (necessary due to limited hardware mixing capacity).
|
||||
3d positional sounds (heard to emanate from a given spot) are supported.
|
||||
active sound instances are referenced by Handles, so changing volume etc.
|
||||
during playback is possible (useful for fadeout).
|
||||
|
||||
|
||||
sound setup
|
||||
-----------
|
||||
|
||||
OpenAL provides portable access to the underlying sound hardware, and
|
||||
falls back to software mixing if no acceleration is provided.
|
||||
we allow the user to specify the device to use (in case the default
|
||||
has problems) and maximum number of sources (to reduce mixing cost).
|
||||
|
||||
|
||||
performance
|
||||
-----------
|
||||
much effort has been invested in efficiency: all sound data is cached,
|
||||
so every open() after the first is effectively free. large sound files are
|
||||
streamed from disk to reduce load time and memory usage. hardware mixing
|
||||
resources are suballocated to avoid delays when starting to play.
|
||||
therefore, the user can confidently fire off hundreds of sound requests.
|
||||
finally, lengthy initialization steps are delayed until the sound engine
|
||||
is actually needed (i.e. upon first open()). perceived startup time is
|
||||
therefore reduced - the user sees e.g. our main menu earlier.
|
||||
|
||||
|
||||
terminology
|
||||
-----------
|
||||
|
||||
"hardware voice" refers to mixing resources on the DSP. strictly
|
||||
speaking, we mean 'OpenAL source', but this term is more clear.
|
||||
voice ~= source, unless expensive effects (e.g. EAX) are enabled.
|
||||
note: software mixing usually doesn't have a fixed 'source' cap.
|
||||
"gain" is quantified volume. 1 is unattenuated, 0.5 corresponds to -6 dB,
|
||||
and 0 is silence. this can be set per-source as well as globally.
|
||||
"position" of a sound is within the app's coordinate system,
|
||||
the orientation of which is passed to snd_update.
|
||||
"importance" of a sound derives from the app-assigned priority
|
||||
(e.g. voiceover must not be skipped in favor of seagulls) and
|
||||
distance from the listener. it's calculated by our prioritizer.
|
||||
"virtual source" denotes a sound play request issued by the app.
|
||||
this is in contrast to an actual AL source, which will be mixed
|
||||
into the output channel. the most important VSrc receive an al_src.
|
||||
"sound instances" store playback parameters (e.g. position), and
|
||||
reference the (centrally cached) "sound data" that will be played.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
//
|
||||
|
||||
Loading…
Reference in New Issue
Block a user