[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [31210] branches/soc-2010-nexyon/intern/ audaspace/Python: Py API Docs:
Joerg Mueller
nexyon at gmail.com
Tue Aug 10 09:57:02 CEST 2010
Revision: 31210
http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=31210
Author: nexyon
Date: 2010-08-10 09:57:02 +0200 (Tue, 10 Aug 2010)
Log Message:
-----------
Py API Docs:
* Improved audaspace docs
* Added an epy parser to add epydoc documented modules to the sphinx docs
Modified Paths:
--------------
branches/soc-2010-nexyon/intern/audaspace/Python/AUD_PyAPI.cpp
branches/soc-2010-nexyon/intern/audaspace/Python/doc/pyparser.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/run.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/sphinxoutput.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/sphinxparser.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/templates/contents.rst
Added Paths:
-----------
branches/soc-2010-nexyon/intern/audaspace/Python/doc/epy/
branches/soc-2010-nexyon/intern/audaspace/Python/doc/epy/PhysicsConstraints.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/epy/VideoTexture.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/epy/__init__.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/epy/bgl.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/epy/geometry.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/epy/idprop.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/epyparser.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/examples/PhysicsConstraints.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/examples/VideoTexture.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/examples/aud.Factory.join.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/examples/aud.Factory.pingpong.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/examples/aud.Factory.sine.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/examples/bgl.Buffer.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/examples/bgl.glRasterPos.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/examples/bgl.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/examples/geometry.BoxPack2D.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/examples/geometry.PolyFill.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/examples/idprop.IDGroup.iteritems.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/examples/idprop.IDGroup.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/examples/idprop.IDGroup.values.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/examples/idprop.py
branches/soc-2010-nexyon/intern/audaspace/Python/doc/rst/
branches/soc-2010-nexyon/intern/audaspace/Python/doc/rst/bge.events.rst
branches/soc-2010-nexyon/intern/audaspace/Python/doc/rst/bge.logic.rst
branches/soc-2010-nexyon/intern/audaspace/Python/doc/rst/bge.render.rst
branches/soc-2010-nexyon/intern/audaspace/Python/doc/rst/bge.types.rst
Modified: branches/soc-2010-nexyon/intern/audaspace/Python/AUD_PyAPI.cpp
===================================================================
--- branches/soc-2010-nexyon/intern/audaspace/Python/AUD_PyAPI.cpp 2010-08-10 06:36:42 UTC (rev 31209)
+++ branches/soc-2010-nexyon/intern/audaspace/Python/AUD_PyAPI.cpp 2010-08-10 07:57:02 UTC (rev 31210)
@@ -127,10 +127,11 @@
PyDoc_STRVAR(M_aud_Factory_sine_doc,
"sine(frequency, rate=44100)\n\n"
- "Creates a sine sound wave.\n\n"
+ "Creates a sine factory which plays a sine wave.\n\n"
":arg frequency: The frequency of the sine wave in Hz.\n"
":type frequency: float\n"
- ":arg rate: The sampling rate in Hz.\n"
+ ":arg rate: The sampling rate in Hz. It's recommended to set this "
+ "value to the playback device's samling rate to avoid resamping.\n"
":type rate: int\n"
":return: The created :class:`Factory` object.\n"
":rtype: :class:`Factory`");
@@ -166,11 +167,14 @@
PyDoc_STRVAR(M_aud_Factory_file_doc,
"file(filename)\n\n"
- "Creates a sound object of a sound file.\n\n"
+ "Creates a factory object of a sound file.\n\n"
":arg filename: Path of the file.\n"
":type filename: string\n"
":return: The created :class:`Factory` object.\n"
- ":rtype: :class:`Factory`");
+ ":rtype: :class:`Factory`\n\n"
+ ".. warning:: If the file doesn't exist or can't be read you will "
+ "not get an exception immediately, but when you try to start "
+ "playback of that factory.");
static PyObject *
Factory_file(PyTypeObject* type, PyObject* args)
@@ -202,7 +206,8 @@
PyDoc_STRVAR(M_aud_Factory_lowpass_doc,
"lowpass(frequency, Q=0.5)\n\n"
- "Creates a second order lowpass filter.\n\n"
+ "Creates a second order lowpass filter based on the transfer "
+ "function H(s) = 1 / (s^2 + s/Q + 1)"
":arg frequency: The cut off trequency of the lowpass.\n"
":type frequency: float\n"
":arg Q: Q factor of the lowpass.\n"
@@ -244,8 +249,10 @@
PyDoc_STRVAR(M_aud_Factory_delay_doc,
"delay(time)\n\n"
- "Delays a sound by playing silence before the sound starts.\n\n"
- ":arg time: How many seconds of silence should be added before the sound.\n"
+ "Delays by playing adding silence in front of the other factory's "
+ "data.\n\n"
+ ":arg time: How many seconds of silence should be added before "
+ "the factory.\n"
":type time: float\n"
":return: The created :class:`Factory` object.\n"
":rtype: :class:`Factory`");
@@ -282,13 +289,13 @@
}
PyDoc_STRVAR(M_aud_Factory_join_doc,
- "join(sound)\n\n"
- "Plays two sounds in sequence.\n\n"
- ":arg sound: The sound to play second.\n"
- ":type sound: :class:`Factory`\n"
+ "join(factory)\n\n"
+ "Plays two factories in sequence.\n\n"
+ ":arg factory: The factory to play second.\n"
+ ":type factory: :class:`Factory`\n"
":return: The created :class:`Factory` object.\n"
":rtype: :class:`Factory`\n\n"
- ".. note:: The two sounds have to have the same specifications "
+ ".. note:: The two factories have to have the same specifications "
"(channels and samplerate).");
static PyObject *
@@ -327,7 +334,8 @@
PyDoc_STRVAR(M_aud_Factory_highpass_doc,
"highpass(frequency, Q=0.5)\n\n"
- "Creates a second order highpass filter.\n\n"
+ "Creates a second order highpass filter based on the transfer "
+ "function H(s) = s^2 / (s^2 + s/Q + 1)"
":arg frequency: The cut off trequency of the highpass.\n"
":type frequency: float\n"
":arg Q: Q factor of the lowpass.\n"
@@ -369,7 +377,7 @@
PyDoc_STRVAR(M_aud_Factory_limit_doc,
"limit(start, end)\n\n"
- "Limits a sound within a specific start and end time.\n\n"
+ "Limits a factory within a specific start and end time.\n\n"
":arg start: Start time in seconds.\n"
":type start: float\n"
":arg end: End time in seconds.\n"
@@ -410,16 +418,16 @@
PyDoc_STRVAR(M_aud_Factory_pitch_doc,
"pitch(factor)\n\n"
- "Changes the pitch of a sound with a specific factor.\n\n"
+ "Changes the pitch of a factory with a specific factor.\n\n"
":arg factor: The factor to change the pitch with.\n"
":type factor: float\n"
":return: The created :class:`Factory` object.\n"
":rtype: :class:`Factory`\n\n"
".. note:: This is done by changing the sample rate of the "
- "underlying sound, which has to be an integer, so the factor "
+ "underlying factory, which has to be an integer, so the factor "
"value rounded and the factor may not be 100 % accurate.\n\n"
".. note:: This is a filter function, you might consider using "
- "Handle.pitch instead.");
+ ":attr:`Handle.pitch` instead.");
static PyObject *
Factory_pitch(Factory* self, PyObject* args)
@@ -454,14 +462,14 @@
PyDoc_STRVAR(M_aud_Factory_volume_doc,
"volume(volume)\n\n"
- "Changes the volume of a sound.\n\n"
+ "Changes the volume of a factory.\n\n"
":arg volume: The new volume..\n"
":type volume: float\n"
":return: The created :class:`Factory` object.\n"
":rtype: :class:`Factory`\n\n"
".. note:: Should be in the range [0, 1] to avoid clipping.\n\n"
".. note:: This is a filter function, you might consider using "
- "Handle.volume instead.");
+ ":attr:`Handle.volume` instead.");
static PyObject *
Factory_volume(Factory* self, PyObject* args)
@@ -496,13 +504,15 @@
PyDoc_STRVAR(M_aud_Factory_fadein_doc,
"fadein(start, length)\n\n"
- "Fades a sound in.\n\n"
+ "Fades a factory in by raising the volume linearly in the given "
+ "time interval.\n\n"
":arg start: Time in seconds when the fading should start.\n"
":type start: float\n"
":arg length: Time in seconds how long the fading should last.\n"
":type length: float\n"
":return: The created :class:`Factory` object.\n"
- ":rtype: :class:`Factory`");
+ ":rtype: :class:`Factory`\n\n"
+ ".. note:: Before the fade starts it plays silence.");
static PyObject *
Factory_fadein(Factory* self, PyObject* args)
@@ -537,13 +547,16 @@
PyDoc_STRVAR(M_aud_Factory_fadeout_doc,
"fadeout(start, length)\n\n"
- "Fades a sound out.\n\n"
+ "Fades a factory in by lowering the volume linearly in the given "
+ "time interval.\n\n"
":arg start: Time in seconds when the fading should start.\n"
":type start: float\n"
":arg length: Time in seconds how long the fading should last.\n"
":type length: float\n"
":return: The created :class:`Factory` object.\n"
- ":rtype: :class:`Factory`");
+ ":rtype: :class:`Factory`\n\n"
+ ".. note:: After the fade this factory plays silence, so that "
+ "the length of the factory is not altered.");
static PyObject *
Factory_fadeout(Factory* self, PyObject* args)
@@ -578,12 +591,14 @@
PyDoc_STRVAR(M_aud_Factory_loop_doc,
"loop(count)\n\n"
- "Loops a sound.\n\n"
- ":arg count: How often the sound should be looped. "
+ "Loops a factory.\n\n"
+ ":arg count: How often the factory should be looped. "
"Negative values mean endlessly.\n"
":type count: integer\n"
":return: The created :class:`Factory` object.\n"
- ":rtype: :class:`Factory`");
+ ":rtype: :class:`Factory`\n\n"
+ ".. note:: This is a filter function, you might consider using "
+ ":attr:`Handle.loop_count` instead.");
static PyObject *
Factory_loop(Factory* self, PyObject* args)
@@ -617,13 +632,13 @@
}
PyDoc_STRVAR(M_aud_Factory_mix_doc,
- "mix(sound)\n\n"
- "Mixes two sounds.\n\n"
- ":arg sound: The sound to mix over the other.\n"
- ":type sound: :class:`Factory`\n"
+ "mix(factory)\n\n"
+ "Mixes two factories.\n\n"
+ ":arg factory: The factory to mix over the other.\n"
+ ":type factory: :class:`Factory`\n"
":return: The created :class:`Factory` object.\n"
":rtype: :class:`Factory`\n\n"
- ".. note:: The two sounds have to have the same specifications "
+ ".. note:: The two factories have to have the same specifications "
"(channels and samplerate).");
static PyObject *
@@ -661,7 +676,8 @@
PyDoc_STRVAR(M_aud_Factory_pingpong_doc,
"pingpong()\n\n"
- "Plays a sound forward and then backward.\n\n"
+ "Plays a factory forward and then backward.\n"
+ "This is like joining a factory with its reverse.\n\n"
":return: The created :class:`Factory` object.\n"
":rtype: :class:`Factory`");
@@ -693,11 +709,16 @@
PyDoc_STRVAR(M_aud_Factory_reverse_doc,
"reverse()\n\n"
- "Plays a sound reversed.\n\n"
+ "Plays a factory reversed.\n\n"
":return: The created :class:`Factory` object.\n"
":rtype: :class:`Factory`\n\n"
- ".. note:: The sound has have a finite length and be seekable. "
- "It's recommended to buffer sounds that should be played reversed.");
+ ".. note:: The factory has to have a finite length and has to be "
+ "seekable. It's recommended to use this only with factories with "
+ "fast and accurate seeking, which is not true for encoded audio "
+ "files, such ones should be buffered using :meth:`buffer` before "
+ "being played reversed.\n\n"
+ ".. warning:: If seeking is not accurate in the underlying factory "
+ "you'll likely hear skips/jumps/cracks.");
static PyObject *
Factory_reverse(Factory* self)
@@ -727,10 +748,15 @@
PyDoc_STRVAR(M_aud_Factory_buffer_doc,
"buffer()\n\n"
- "Buffers a sound into RAM.\n\n"
+ "Buffers a factory into RAM.\n"
+ "This saves CPU usage needed for decoding and file access if the "
+ "underlying factory reads from a file on the harddisk, but it "
+ "consumes a lot of memory.\n\n"
":return: The created :class:`Factory` object.\n"
":rtype: :class:`Factory`\n\n"
- ".. note:: Raw PCM data needs a lot of space, only buffer short sounds.");
+ ".. note:: Only known-length factories can be buffered.\n\n"
+ ".. warning:: Raw PCM data needs a lot of space, only buffer "
+ "short factories.");
static PyObject *
Factory_buffer(Factory* self)
@@ -757,8 +783,11 @@
PyDoc_STRVAR(M_aud_Factory_square_doc,
"square(threshold = 0)\n\n"
- "Makes a square wave out of an audio wave.\n\n"
- ":arg threshold: Threshold value over which an amplitude counts non-zero.\n"
+ "Makes a square wave out of an audio wave by setting all samples "
+ "with a amplitude >= threshold to 1, all <= -threshold to -1 and "
+ "all between to 0.\n\n"
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list