Merge pull request #33 from bbbart/documentation

More documentation

pyfmodex/callback_prototypes.py

@@ -147,6 +147,7 @@
     c_int, POINTER(OUTPUT_STATE), c_void_p, c_void_p, c_uint, c_uint
 )
 OUTPUT_UPDATE_CALLBACK = func(c_int, POINTER(OUTPUT_STATE))
+OUTPUT_DEVICELISTCHANGED_CALLBACK = func(c_int, POINTER(OUTPUT_STATE))
 SOUND_NONBLOCKCALLBACK = func(c_int, c_void_p, c_int)
 SOUND_PCMREADCALLBACK = func(c_int, c_void_p, c_void_p, c_uint)
 SOUND_PCMSETPOSCALLBACK = func(c_int, c_void_p, c_int, c_uint, c_int)

pyfmodex/cone_settings.py

@@ -16,8 +16,7 @@ def __init__(self, sptr, class_name):
         Creates ConeSettings for an FMOD object.
 
         Usually not called directly, but through the
-        :py:attr:`~pyfmodex.channel_control.ChannelControl.cone_settings`
-        property of the FMOD object.
+        `cone_settings` or `threed_cone_settings` property of an FMOD object.
 
         The :py:class:`~pyfmodex.flags.MODE` flag THREED must be set on this
         object otherwise :py:const:`~pyfmodex.enums.RESULT.NEEDS3D` is

pyfmodex/enums.py

@@ -1055,11 +1055,11 @@ class DSP_PROCESS_OPERATION(Enum):
      - return normal: Meaning yes, it should execute the dsp process function
        with :py:attr:`PERFORM`
 
-     - raise :py:class:`~pyfmodex.exceptions.FmodError` with code
+     - raise :py:exc:`~pyfmodex.exceptions.FmodError` with code
        :py:attr:`~RESULT.DSP_DONTPROCESS` - Meaning no, it should skip the
        process function and not call it with :py:attr:`PERFORM`.
 
-     - raise :py:class:`~pyfmodex.exceptions.FmodError` with code
+     - raise :py:exc:`~pyfmodex.exceptions.FmodError` with code
        :py:attr:`~RESULT.DSP_SILENCE` - Meaning no, it should skip the process
        function and not call it with :py:attr:`PERFORM`, AND, tell the signal
        chain to follow that it is now idle, so that no more processing happens
@@ -1081,7 +1081,7 @@ class DSP_PROCESS_OPERATION(Enum):
 
     #: The DSP is being queried for the expected output format and whether it
     #: needs to process audio or should be bypassed. The function should
-    #: succeed, or raise :py:class:`~pyfmodex.exceptions.FmodError` if audio
+    #: succeed, or raise :py:exc:`~pyfmodex.exceptions.FmodError` if audio
     #: can pass through unprocessed. If audio is to be processed,
     #: 'outbufferarray' must be filled with the expected output format, channel
     #: count and mask.
@@ -1453,22 +1453,22 @@ class OPENSTATE(Enum):
     NONBLOCKING, note that if the user calls
     :py:meth:`~pyfmodex.sound.Sound.get_subsound`, a stream will go into
     :py:attr:`SEEKING` state and sound related commands will raise
-    :py:class:`~pyfmodex.exceptions.FmodError` with code
+    :py:exc:`~pyfmodex.exceptions.FmodError` with code
     :py:attr:`~RESULT.NOTREADY`.
 
     With streams, if you are using the :py:class:`~pyfmodex.flags.MODE` flag
     NONBLOCKING, note that if the user calls
     :py:meth:`~pyfmodex.channel.Channel.get_position`, a stream will go into
     :py:attr:`SETPOSITION` state and sound related commands will raise
-    :py:class:`~pyfmodex.exceptions.FmodError` with code
+    :py:exc:`~pyfmodex.exceptions.FmodError` with code
     :py:attr:`~RESULT.NOTREADY`.
     """
 
     READY = 0  #: Opened and ready to play.
     LOADING = 1  #: Initial load in progress.
 
     #: Failed to open - file not found, out of memory etc. See
-    #: :py:class:`~pyfmodex.exceptions.FmodError` code from
+    #: :py:exc:`~pyfmodex.exceptions.FmodError` code from
     #: :py:attr:`~pyfmodex.sound.Sound.open_state` for what happened.
     ERROR = 2
 
@@ -1570,7 +1570,7 @@ class PLUGINTYPE(Enum):
 
 
 class RESULT(Enum):
-    """Error codes for :py:class:`~pyfmodex.exceptions.FmodError` raised by
+    """Error codes for :py:exc:`~pyfmodex.exceptions.FmodError` raised by
     every function.
     """
 
@@ -2162,3 +2162,36 @@ class TAGTYPE(Enum):
 
     #: Maximum number of tag types supported.
     MAX = 11
+
+
+class OUTPUT_METHOD(IntEnum):
+    """Output method used to interact with the mixer.
+
+    If the hardware presents a ring buffer without synchronization primitives
+    :py:attr:`POLLING` is the recommended approach where FMOD will call
+    into the plugin regularly to check the play position of the buffer.
+
+    For hardware that presents a callback that must be filled immediately
+    :py:attr:`MIX_BUFFERED` is recommended as buffering occurs in a separate
+    thread, reading from the mixer is simply a memcpy.
+
+    Using :py:attr:`MIX_DIRECT` is recommended if you want to take direct
+    control of how and when the mixer runs.
+    """
+
+    #: Mixer will execute directly when calling
+    #: :py:data:`~pyfmodex.function_prototypes.OUTPUT_READFROMMIXER`, buffering
+    #: must be performed by plugin code.
+    MIX_DIRECT = 0
+
+    #: Mixer will execute and buffer indirectly (on a separate thread) in
+    #: response to
+    #: :py:data:`~pyfmodex.callback_prototypes.OUTPUT_GETPOSITION_CALLBACK` /
+    #: :py:data:`~pyfmodex.callback_prototypes.OUTPUT_LOCK_CALLBACK` /
+    #: :py:data:`~pyfmodex.callback_prototypes.OUTPUT_UNLOCK_CALLBACK`.
+    POLLING = 1
+
+    #: Mixer will execute and buffer automatically (on a separate thread) and
+    #: can be read from with
+    #: :py:data:`~pyfmodex.function_prototypes.OUTPUT_READFROMMIXER`.
+    MIX_BUFFERED = 2

pyfmodex/fmodex.py

@@ -123,7 +123,7 @@ def initialize_memory(poolmem, poollen, useralloc, userrealloc, userfree, memtyp
     Callback implementations must be thread safe.
 
     If you specify a fixed size pool that is too small, FMOD will return
-    raise an :py:class:`~pyfmodex.exceptions.FmodError` with code
+    raise an :py:exc:`~pyfmodex.exceptions.FmodError` with code
     :py:attr:`~pyfmodex.enums.RESULT.MEMORY` when the limit of the fixed size
     pool is exceeded. At this point, it's possible that FMOD may become
     unstable. To maintain stability, do not allow FMOD to run out of memory.
@@ -154,7 +154,7 @@ def initialize_debugging(flags, mode, callback, filename):
     """Specify the level and delivery method of log messages when using the
     logging version of FMOD.
 
-    This function will raise an :py:class:`~pyfmodex.exceptions.FmodError` with
+    This function will raise an :py:exc:`~pyfmodex.exceptions.FmodError` with
     code :py:attr:`~pyfmodex.enums.RESULT.UNSUPPORTED` when using the
     non-logging (release) versions of FMOD.
 

pyfmodex/function_prototypes.py

@@ -158,3 +158,13 @@
 OUTPUT_LOG = func(
     None, c_int, c_char_p, c_int, c_char_p, c_char_p, c_void_p
 )  # Varargs, again
+
+#: Output request reset function.
+#:
+#: Request the output to shut down and restart.
+#:
+#: If this is issued, the output will not reset immediately, but on the next
+#: update the output will first shut down with a call to the
+#: `OUTPUT_STOP_CALLBACK` then `OUTPUT_CLOSE_CALLBACK`, followed by a restart
+#: with `OUTPUT_INIT_CALLBACK` and `OUTPUT_START_CALLBACK`.
+OUTPUT_REQUESTRESET = func(None, POINTER(OUTPUT_STATE))

pyfmodex/reverb.py

@@ -1,12 +1,27 @@
+"""An interface that manages virtual 3D reverb spheres."""
+
 from ctypes import *
+
 from .fmodobject import FmodObject
-from .structures import VECTOR, REVERB_PROPERTIES
+from .structures import REVERB_PROPERTIES, VECTOR
 from .utils import check_type
 
 
 class Reverb3D(FmodObject):
+    """An interface that manages virtual 3D reverb spheres."""
+
     @property
     def _threed_attrs(self):
+        """The 3D attributes of a reverb sphere.
+
+        :type: list with
+            - Position in 3D space represnting the center of the reverb as a
+              list of three coordinate floats
+            - Distance from the centerpoint within which the reverb will have
+              full effect
+            - Distance from the centerpoint beyond which the reverb will have
+              no effect
+        """
         pos = VECTOR()
         mindist = c_float()
         maxdist = c_float()
@@ -27,6 +42,10 @@ def _threed_attrs(self, attrs):
 
     @property
     def position(self):
+        """Position in 3D space represnting the center of the reverb.
+
+        :type: list of three coordinate floats
+        """
         return self._threed_attrs[0]
 
     @position.setter
@@ -37,6 +56,11 @@ def position(self, pos):
 
     @property
     def min_distance(self):
+        """Distance from the centerpoint within which the reverb will have full
+        effect.
+
+        :type: float
+        """
         return self._threed_attrs[1]
 
     @min_distance.setter
@@ -47,6 +71,11 @@ def min_distance(self, mindist):
 
     @property
     def max_distance(self):
+        """Distance from the centerpoint within which the reverb will have no
+        effect.
+
+        :type: float
+        """
         return self._threed_attrs[2]
 
     @max_distance.setter
@@ -57,16 +86,24 @@ def max_distance(self, maxdist):
 
     @property
     def active(self):
+        """The active state of the reverb sphere.
+
+        :type: bool
+        """
         active = c_bool()
         self._call_fmod("FMOD_Reverb3D_GetActive", byref(active))
         return active.value
 
     @active.setter
-    def active(self, a):
-        self._call_fmod("FMOD_Reverb3D_SetActive", a)
+    def active(self, active):
+        self._call_fmod("FMOD_Reverb3D_SetActive", active)
 
     @property
     def properties(self):
+        """The environmental properties of a reverb sphere.
+
+        :type: REVERB_PROPERTIES
+        """
         props = REVERB_PROPERTIES()
         self._call_fmod("FMOD_Reverb3D_GetProperties", byref(props))
         return props
@@ -77,4 +114,10 @@ def properties(self, props):
         self._call_fmod("FMOD_Reverb3D_SetProperties", byref(props))
 
     def release(self):
+        """Release the memory for a reverb object and make it inactive.
+
+        If you release all Reverb3D objects and have not added a new Reverb3D
+        object, :py:meth:`~pyfmodex.system.System.set_reverb_properties` should
+        be called to reset the reverb properties.
+        """
         self._call_fmod("FMOD_Reverb3D_Release")