Merge pull request #27 from bbbart/documentation

working on API reference documentation

docs/conf.py

@@ -43,7 +43,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

pyfmodex/__init__.py

@@ -1,32 +1,18 @@
-"""Fmod ex python bindings."""
-from .fmodex import (
-    get_disk_busy,
-    set_disk_busy,
-    get_memory_stats,
-    initialize_debugging,
-    initialize_memory,
-)
-from . import globalvars
+"""FMOD python bindings."""
+
+from .fmodex import (get_disk_busy, get_memory_stats, initialize_debugging,
+                     initialize_memory, set_disk_busy)
 
 # Avoid recursive import hell
-from . import (
-    dsp,
-    dsp_connection,
-    geometry,
-    channel,
-    channel_group,
-    reverb,
-    sound,
-    sound_group,
-    system,
-)
-from .utils import FmodError
+from . import (channel, channel_group, dsp, dsp_connection, geometry,
+               globalvars, reverb, sound, sound_group, system)
 
 # import reverb presets
 from .reverb_presets import REVERB_PRESET, set_reverb_preset
 
 # import structures to be used with Resonance Audio plugin
 from .roomproperties import MaterialNames, RoomProperties
+from .utils import FmodError
 
 __version__ = "0.7.0"
 
@@ -41,6 +27,7 @@
 c["SoundGroup"] = sound_group.SoundGroup
 c["System"] = system.System
 globalvars.class_list = c
+
 from . import constants
 
 System = c["System"]

pyfmodex/channel.py

@@ -1,28 +1,36 @@
+"""A source of audio signal that connects to the
+:py:class:`~pyfmodex.channel_group.ChannelGroup` mixing
+hierarchy.
+"""
 from ctypes import *
-from .fmodobject import _dll
-from .structures import VECTOR, REVERB_PROPERTIES
-from .globalvars import get_class
-from .callback_prototypes import CHANNELCONTROL_CALLBACK
-from .utils import ckresult, check_type
-from .structobject import Structobject as so
-from .flags import MODE
 
 from .channel_control import ChannelControl
+from .fmodobject import _dll
+from .globalvars import get_class
+from .utils import check_type, ckresult
 
 
 class Channel(ChannelControl):
-    @property
-    def pan_level(self):
-        l = c_float()
-        ckresult(_dll.FMOD_Channel_Get3DPanLevel(self._ptr, byref(l)))
-        return l.value
+    """A source of audio signal that connects to the
+    :py:class:`~pyfmodex.channel_group.ChannelGroup` mixing hierarchy.
 
-    @pan_level.setter
-    def pan_level(self, l):
-        ckresult(_dll.FMOD_Channel_Set3DPanLevel(self._ptr, c_float(l)))
+    Created with :py:meth:`~pyfmodex.system.System.play_sound` or
+    :py:meth:`~pyfmodex.system.System.play_dsp`.
+    """
 
     @property
     def channel_group(self):
+        """The ChannelGroup this object outputs to.
+
+        A :py:class:`~pyfmodex.channel_group.ChannelGroup` may contain many
+        :py:class:`Channels <~pyfmodex.channel.Channel>`.
+
+        :py:class:`Channels <~pyfmodex.channel.Channel>` may only output to a
+        single :py:class:`~pyfmodex.channel_group.ChannelGroup`. Setting this
+        will remove it from the previous group first.
+
+        :type: ChannelGroup
+        """
         grp_ptr = c_void_p()
         ckresult(_dll.FMOD_Channel_GetChannelGroup(self._ptr, byref(grp_ptr)))
         return get_class("ChannelGroup")(grp_ptr)
@@ -34,12 +42,22 @@ def channel_group(self, group):
 
     @property
     def current_sound(self):
+        """The currently playing Sound.
+
+        May be None if no :py:class:`~pyfmodex.sound.Sound` is playing.
+
+        :type: Sound
+        """
         snd_ptr = c_void_p()
         ckresult(_dll.FMOD_Channel_GetCurrentSound(self._ptr, byref(snd_ptr)))
         return get_class("Sound")(snd_ptr)
 
     @property
     def frequency(self):
+        """The playback frequency or playback rate.
+
+        :type: float
+        """
         freq = c_float()
         ckresult(_dll.FMOD_Channel_GetFrequency(self._ptr, byref(freq)))
         return freq.value
@@ -50,22 +68,57 @@ def frequency(self, freq):
 
     @property
     def index(self):
+        """The index of this object in the :py:class:`~pyfmodex.system.System`
+        :py:class:`~pyfmodex.channel.Channel` pool.
+
+        :type: int
+        """
         idx = c_int()
         self._call_fmod("FMOD_Channel_GetIndex", byref(idx))
         return idx.value
 
     @property
     def loop_count(self):
-        c = c_int()
-        ckresult(_dll.FMOD_Channel_GetLoopCount(self._ptr, byref(c)))
-        return c.value
+        """The number of times to loop before stopping.
+
+        Times to loop before stopping, with:
+
+        - 0: oneshot
+        - 1: loop once then stop
+        - -1: loop forever
+
+        This is the current loop countdown value that will decrement as it
+        plays until reaching 0. It can be reset by setting this property.
+
+        The :py:class:`~pyfmodex.flags.MODE` flags of the
+        :py:class:`~pyfmodex.sound.Sound` or
+        :py:class:`~pyfmodex.channel.Channel` must include LOOP_NORMAL or
+        LOOP_BIDI for this function to work.
+
+        :type: int
+        """
+        loopcount = c_int()
+        ckresult(_dll.FMOD_Channel_GetLoopCount(self._ptr, byref(loopcount)))
+        return loopcount.value
 
     @loop_count.setter
     def loop_count(self, count):
         ckresult(_dll.FMOD_Channel_SetLoopCount(self._ptr, c_int(count)))
 
     def get_loop_points(self, startunit, endunit):
-        "Returns tuple(start, end)" ""
+        """Retrieve the loop start and end points.
+
+        Valid TIMEUNIT types are PCM, MS and PCMBYTES. Any other time units
+        return :py:attr:`~pyfmodex.enums.RESULT.FORMAT`.
+
+        If MS or PCMBYTES are used, the value is internally converted from PCM,
+        so the retrieved value may not exactly match the set value.
+
+        :param TIMEUNIT startunit: Time units for loop start point.
+        :param TIMEUNIT endunit: Time units for loop end point.
+        :returns: Loop start point and loop end point.
+        :rtype: two-tuple of ints
+        """
         start = c_uint()
         end = c_uint()
         ckresult(
@@ -76,22 +129,91 @@ def get_loop_points(self, startunit, endunit):
         return start.value, end.value
 
     def set_loop_points(self, start, startunit, end, endunit):
+        """Set the loop start and end points.
+
+        Loop points may only be set on a :py:class:`~pyfmodex.channel.Channel`
+        playing a :py:class:`~pyfmodex.sound.Sound`, not a
+        :py:class:`~pyfmodex.channel.Channel` playing a
+        :py:class:`~pyfmodex.dsp.DSP`  (see
+        :py:meth:`~pyfmodex.system.System.play_dsp`).
+
+        Valid TIMEUNIT types are PCM, MS and PCMBYTES. Any other time units
+        return :py:attr:`~pyfmodex.enums.RESULT.FORMAT`. If MS or PCMBYTES are
+        used, the value is internally converted to PCM.
+
+        :param int start: Loop start point.
+        :param TIMEUNIT startunit: Time units for `start`.
+        :param int end: Loop end point.
+        :param TIMEUNIT endunit: Time units for `end`.
+        """
         ckresult(
             _dll.FMOD_Channel_SetLoopPoints(
                 self._ptr, c_uint(start), int(startunit), c_uint(end), int(endunit)
             )
         )
 
     def get_position(self, unit):
+        """Retrieve the current playback position.
+
+        Certain TIMEUNIT types are always available: PCM, PCMBYTES and MS. The
+        others are format specific such as MODORDER / MODROW / MODPATTERN which
+        is specific to files of type MOD / S3M / XM / IT.
+
+        If MS or PCMBYTES are used, the value is internally converted from PCM,
+        so the retrieved value may not exactly match the set value.
+
+        :param TIMEUNIT unit: Time units for position.
+        :returns: Playback position.
+        :rtype: int
+        """
         pos = c_uint()
         ckresult(_dll.FMOD_Channel_GetPosition(self._ptr, byref(pos), int(unit)))
         return pos.value
 
     def set_position(self, pos, unit):
+        """Set the current playback position.
+
+        Certain TIMEUNIT types are always available: PCM, PCMBYTES and MS. The
+        others are format specific such as MODORDER / MODROW / MODPATTERN which
+        is specific to files of type MOD / S3M / XM / IT.
+
+        If playing a :py:class:`~pyfmodex.sound.Sound` created with
+        :py:meth:`~pyfmodex.system.System.create_stream` or the
+        :py:class:`~pyfmodex.flags.MODE` flag CREATESTREAM changing the
+        position may cause a slow reflush operation while the file seek and
+        decode occurs. You can avoid this by creating the stream with the
+        :py:class:`~pyfmodex.flags.MODE` flag NONBLOCKING. This will cause the
+        stream to go into :py:attr:`~pyfmodex.enums.OPENSTATE.SETPOSITION`
+        state (see :py:attr:`~pyfmodex.sound.Sound.open_state` and Sound
+        commands will return :py:attr:`~pyfmodex.enums.RESULT.NOTREADY`.
+        :py:meth:`get_position` will also not update until this non-blocking
+        set position operation has completed.
+
+        Using a VBR source that does not have an associated seek table or seek
+        information (such as MP3 or MOD/S3M/XM/IT) may cause inaccurate seeking
+        if you specify MS or PCM. If you want FMOD to create a PCM vs bytes
+        seek table so that seeking is accurate, you will have to specify the
+        :py:class:`~pyfmodex.flags.MODE` flag ACCURATETIME when loading or
+        opening the sound. This means there is a slight delay as FMOD scans the
+        whole file when loading the sound to create this table.
+
+        :param int pos: Playback position.
+        :param TIMEUNIT unit: Time units for `pos`.
+        """
         ckresult(_dll.FMOD_Channel_SetPosition(self._ptr, pos, unit))
 
     @property
     def priority(self):
+        """The priority used for virtual Channel ordering, where 0 represents
+        most important and 256 represents least important.
+
+        Priority is used as a coarse grain control for the virtual
+        :py:class:`~pyfmodex.channel.Channel` system, lower priority
+        :py:class:`Channels <~pyfmodex.channel.Channel>` will always be stolen
+        before higher. For channels of equal priority, those with the quietest
+        :py:attr:`~pyfmodex.channel_control.ChannelControl.audibility` value
+        will be stolen first.
+        """
         pri = c_int()
         ckresult(_dll.FMOD_Channel_GetPriority(self._ptr, byref(pri)))
         return pri.value
@@ -102,6 +224,13 @@ def priority(self, pri):
 
     @property
     def is_virtual(self):
-        vi = c_bool()
-        ckresult(_dll.FMOD_Channel_IsVirtual(self._ptr, byref(vi)))
-        return vi.value
+        """Whether the Channel is being emulated by the virtual Channel system.
+
+        - True: silent / emulated
+        - False: audible / real
+
+        :type: bool
+        """
+        virtual_state = c_bool()
+        ckresult(_dll.FMOD_Channel_IsVirtual(self._ptr, byref(virtual_state)))
+        return virtual_state.value