[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [30666] branches/soc-2010-nexyon/intern/ audaspace/Python/AUD_PyAPI.cpp: Audaspace Python API: Better docs.

Joerg Mueller nexyon at gmail.com
Fri Jul 23 20:00:38 CEST 2010


Revision: 30666
          http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=30666
Author:   nexyon
Date:     2010-07-23 20:00:37 +0200 (Fri, 23 Jul 2010)

Log Message:
-----------
Audaspace Python API: Better docs.

Modified Paths:
--------------
    branches/soc-2010-nexyon/intern/audaspace/Python/AUD_PyAPI.cpp

Modified: branches/soc-2010-nexyon/intern/audaspace/Python/AUD_PyAPI.cpp
===================================================================
--- branches/soc-2010-nexyon/intern/audaspace/Python/AUD_PyAPI.cpp	2010-07-23 17:51:39 UTC (rev 30665)
+++ branches/soc-2010-nexyon/intern/audaspace/Python/AUD_PyAPI.cpp	2010-07-23 18:00:37 UTC (rev 30666)
@@ -118,104 +118,228 @@
 }
 
 PyDoc_STRVAR(M_aud_Sound_sine_doc,
-			 "sine()\n"
-			 "\tCreates a sine sound at a specific frequency.\n");
+			 "sine(frequency)\n\n"
+			 "Creates a sine sound wave.\n\n"
+			 ":arg frequency: The frequency of the sine wave in Hz.\n"
+			 ":type frequency: float\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound");
 
 static PyObject *
 Sound_sine(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_file_doc,
-			 "Creates a sound object of a sound file.");
+			 "file(filename)\n\n"
+			 "Creates a sound object of a sound file.\n\n"
+			 ":arg filename: Path of the file.\n"
+			 ":type filename: string\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound");
 
 static PyObject *
 Sound_file(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_lowpass_doc,
-			 "Creates a lowpass filter with a specific cut off frequency.");
+			 "lowpass(sound, frequency)\n\n"
+			 "Creates a low quality lowpass filter.\n\n"
+			 ":arg sound: The sound to filter.\n"
+			 ":type sound: aud.Sound\n"
+			 ":arg frequency: The cut off trequency of the lowpass.\n"
+			 ":type frequency: float\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound");
 
 static PyObject *
 Sound_lowpass(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_delay_doc,
-			 "Delays a sound by a specific amount of seconds.");
+			 "delay(sound, time)\n\n"
+			 "Delays a sound by playing silence before the sound starts.\n\n"
+			 ":arg sound: The sound to filter.\n"
+			 ":type sound: aud.Sound\n"
+			 ":arg time: How many seconds of silence should be added before the sound.\n"
+			 ":type time: float\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound");
 
 static PyObject *
 Sound_delay(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_double_doc,
-			 "Plays two sounds of the same specs in sequence.");
+			 "double(first, second)\n\n"
+			 "Plays two sounds in sequence.\n\n"
+			 ":arg first: The sound to play first.\n"
+			 ":type first: aud.Sound\n"
+			 ":arg second: The sound to play second.\n"
+			 ":type second: aud.Sound\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound\n"
+			 ".. note:: The two sounds have to have the same specifications "
+			 "(channels and samplerate).");
 
 static PyObject *
 Sound_double(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_highpass_doc,
-			 "Creates a highpass filter with a specific cut off frequency.");
+			 "highpass(sound, frequency)\n\n"
+			 "Creates a low quality highpass filter.\n\n"
+			 ":arg sound: The sound to filter.\n"
+			 ":type sound: aud.Sound\n"
+			 ":arg frequency: The cut off trequency of the highpass.\n"
+			 ":type frequency: float\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound");
 
 static PyObject *
 Sound_highpass(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_limiter_doc,
-			 "Limits a sound within a specific start and end time.");
+			 "limit(sound, start, end)\n\n"
+			 "Limits a sound within a specific start and end time.\n\n"
+			 ":arg sound: The sound to filter.\n"
+			 ":type sound: aud.Sound\n"
+			 ":arg start: Start time in seconds.\n"
+			 ":type start: float\n"
+			 ":arg end: End time in seconds.\n"
+			 ":type end: float\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound");
 
 static PyObject *
 Sound_limiter(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_pitch_doc,
-			 "Changes the pitch of a sound with a specific factor.");
+			 "pitch(sound, factor)\n\n"
+			 "Changes the pitch of a sound with a specific factor.\n\n"
+			 ":arg sound: The sound to filter.\n"
+			 ":type sound: aud.Sound\n"
+			 ":arg factor: The factor to change the pitch with.\n"
+			 ":type factor: float\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound\n"
+			 ".. note:: This is done by changing the sample rate of the "
+			 "underlying sound, which has to be an integer, so the factor "
+			 "value rounded and the factor may not be 100 % accurate.");
 
 static PyObject *
 Sound_pitch(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_volume_doc,
-			 "Changes the volume of a sound with a specific factor.");
+			 "volume(sound, volume)\n\n"
+			 "Changes the volume of a sound.\n\n"
+			 ":arg sound: The sound to filter.\n"
+			 ":type sound: aud.Sound\n"
+			 ":arg volume: The new volume..\n"
+			 ":type volume: float\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound\n"
+			 ".. note:: Should be in the range [0, 1] to avoid clipping.");
 
 static PyObject *
 Sound_volume(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_fadein_doc,
-			 "Fades a sound in from a specific start time and with a specific length.");
+			 "fadein(sound, start, length)\n\n"
+			 "Fades a sound in.\n\n"
+			 ":arg sound: The sound to filter.\n"
+			 ":type sound: aud.Sound\n"
+			 ":arg start: Time in seconds when the fading should start.\n"
+			 ":type filename: float\n"
+			 ":arg length: Time in seconds how long the fading should last.\n"
+			 ":type filename: float\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound");
 
 static PyObject *
 Sound_fadein(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_fadeout_doc,
-			 "Fades a sound out from a specific start time and with a specific length.");
+			 "fadeout(sound, start, length)\n\n"
+			 "Fades a sound out.\n\n"
+			 ":arg sound: The sound to filter.\n"
+			 ":type sound: aud.Sound\n"
+			 ":arg start: Time in seconds when the fading should start.\n"
+			 ":type filename: float\n"
+			 ":arg length: Time in seconds how long the fading should last.\n"
+			 ":type filename: float\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound");
 
 static PyObject *
 Sound_fadeout(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_loop_doc,
-			 "Loops a sound a specific amount of times, negative values mean endlessly.");
+			 "loop(sound, count)\n\n"
+			 "Loops a sound.\n\n"
+			 ":arg sound: The sound to filter.\n"
+			 ":type sound: aud.Sound\n"
+			 ":arg count: How often the sound should be looped. "
+			 "Negative values mean endlessly.\n"
+			 ":type count: integer\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound");
 
 static PyObject *
 Sound_loop(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_superpose_doc,
-			 "Mixes two sounds of the same specs.");
+			 "superpose(sound1, sound2)\n\n"
+			 "Mixes two sounds.\n\n"
+			 ":arg sound1: The sound to filter.\n"
+			 ":type sound1: aud.Sound\n"
+			 ":arg sound2: The sound to filter.\n"
+			 ":type sound2: aud.Sound\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound");
 
 static PyObject *
 Sound_superpose(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_pingpong_doc,
-			 "Plays a sound forward and then backward.");
+			 "pingpong(sound)\n\n"
+			 "Plays a sound forward and then backward.\n\n"
+			 ":arg sound: The sound to filter.\n"
+			 ":type sound: aud.Sound\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound\n"
+			 ".. note:: The sound has to be buffered to be played reverse.");
 
 static PyObject *
 Sound_pingpong(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_reverse_doc,
-			 "Plays a sound reversed.");
+			 "reverse(sound)\n\n"
+			 "Plays a sound reversed.\n\n"
+			 ":arg sound: The sound to filter.\n"
+			 ":type sound: aud.Sound\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound\n"
+			 ".. note:: The sound has to be buffered to be played reverse.");
 
 static PyObject *
 Sound_reverse(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_buffer_doc,
-			 "Buffers a sound into RAM.");
+			 "buffer(sound)\n\n"
+			 "Buffers a sound into RAM.\n\n"
+			 ":arg sound: The sound to buffer.\n"
+			 ":type sound: aud.Sound\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound\n"
+			 ".. note:: Raw PCM data needs a lot of space, only buffer short sounds.");
 
 static PyObject *
 Sound_buffer(PyObject* nothing, PyObject* args);
 
 PyDoc_STRVAR(M_aud_Sound_square_doc,
-			 "Makes a square wave out of an audio wave depending on a threshold value.");
+			 "squre(sound, threshold)\n\n"
+			 "Makes a square wave out of an audio wave.\n\n"
+			 ":arg sound: The sound to filter.\n"
+			 ":type sound: aud.Sound\n"
+			 ":arg threshold: Threshold value over which an amplitude counts non-zero.\n"
+			 ":type threshold: float\n"
+			 ":return: The created aud.Sound object.\n"
+			 ":rtype: aud.Sound");
 
 static PyObject *
 Sound_square(PyObject* nothing, PyObject* args);
@@ -958,7 +1082,10 @@
 }
 
 PyDoc_STRVAR(M_aud_Handle_pause_doc,
-			 "Pauses the sound.");
+			 "pause()\n\n"
+			 "Pauses playback.\n\n"
+			 ":return: Whether the action succeeded.\n"
+			 ":rtype: boolean");
 
 static PyObject *
 Handle_pause(Handle *self)
@@ -967,7 +1094,10 @@
 }
 
 PyDoc_STRVAR(M_aud_Handle_resume_doc,
-			 "Resumes the sound.");
+			 "resume()\n\n"
+			 "Resumes playback.\n\n"
+			 ":return: Whether the action succeeded.\n"
+			 ":rtype: boolean");
 
 static PyObject *
 Handle_resume(Handle *self)
@@ -976,7 +1106,10 @@
 }
 
 PyDoc_STRVAR(M_aud_Handle_stop_doc,
-			 "Stops the sound.");
+			 "stop()\n\n"
+			 "Stops playback.\n\n"
+			 ":return: Whether the action succeeded.\n"
+			 ":rtype: boolean");
 
 static PyObject *
 Handle_stop(Handle *self)
@@ -985,7 +1118,13 @@
 }
 
 PyDoc_STRVAR(M_aud_Handle_update_doc,
-			 "Updates the 3D information of the source. Awaits a 3D position and velocity vector and a 3x3 orientation matrix.");
+			 "update(info)\n\n"
+			 "Updates the 3D information of the source."
+			 ":arg info: The 3D info in the format (fff)(fff)((fff)(fff)(fff))."
+			 " Position, velocity and a 3x3 orientation matrix.\n"
+			 ":type info: float tuple\n"
+			 ":return: Whether the action succeeded.\n"
+			 ":rtype: boolean");
 
 static PyObject *
 Handle_update(Handle *self, PyObject *data)

@@ Diff output truncated at 10240 characters. @@




More information about the Bf-blender-cvs mailing list