Major changes in wxVidXANIM (support for output filtering)

[wxWidgets.git] / utils / wxMMedia2 / lib / sndbase.h

diff --git a/utils/wxMMedia2/lib/sndbase.h b/utils/wxMMedia2/lib/sndbase.h
index 26fae17890868e7c864da513ac1e1d031b429329..9d4011610da67ae053cbfd7245cefe1545ee7b5c 100644 (file)
--- a/utils/wxMMedia2/lib/sndbase.h
+++ b/utils/wxMMedia2/lib/sndbase.h
@@ -14,24 +14,59 @@
 
 #include <wx/defs.h>
 
+// ------------------------------------------------------------------------
+// DEFINITIONS
+
+// ---------------------
+// Sound streaming mode:
+//   - wxSOUND_INPUT: simple recording mode
+//   - wxSOUND_OUTPUT: simple playing mode
+//   - wxSOUND_DUPLEX: full duplex record/play at the same time
+// ---------------------
 enum {
   wxSOUND_INPUT = 1,
   wxSOUND_OUTPUT = 2,
   wxSOUND_DUPLEX = wxSOUND_INPUT | wxSOUND_OUTPUT,
 };
 
+// ---------------------
+// wxSoundFormatType: it specifies the format family of the sound data
+// which will be passed to the stream.
+// ---------------------
 typedef enum {
   wxSOUND_NOFORMAT,
   wxSOUND_PCM,
-  wxSOUND_ULAW
+  wxSOUND_ULAW,
+  wxSOUND_G72X
 } wxSoundFormatType;
 
+// ---------------------
+// wxSoundError:
+//   - wxSOUND_NOERR: No error occured
+//   - wxSOUND_IOERR: an input/output error occured, it may concern either
+//                    a driver or a file
+//   - wxSOUND_INVFRMT: the sound format passed to the function is invalid.
+//                      Generally, it means that you passed out of range values
+//                      to the codec stream or you don't pass the right sound
+//                      format object to the right sound codec stream.
+//   - wxSOUND_INVDEV: Invalid device. Generally, it means that the sound stream
+//                     didn't manage to open the device driver due to an invalid//                     parameter or to the fact that sound is not supported on
+//                     this computer.
+//   - wxSOUND_NOEXACT: No exact matching sound codec has been found for
+//                      this sound format. It means that the sound driver didn't
+//                      manage to setup the sound card with the specified
+//                      values.
+//   - wxSOUND_NOCODEC: No matching codec has been found. Generally, it 
+//                      may happen when you call
+//                      wxSoundRouterStream::SetSoundFormat().
+//   - wxSOUND_MEMERR:  Not enough memory.
+// ---------------------
 typedef enum {
   wxSOUND_NOERR,
   wxSOUND_IOERR,
   wxSOUND_INVFRMT,
   wxSOUND_INVDEV,
-  wxSOUND_NOTEXACT,
+  wxSOUND_NOEXACT,
   wxSOUND_INVSTRM,
   wxSOUND_NOCODEC,
   wxSOUND_MEMERR
@@ -39,6 +74,13 @@ typedef enum {
 
 class WXDLLEXPORT wxSoundStream;
 
+// ---------------------
+// wxSoundCallback(stream, evt, cdata): C callback for sound event.
+//    - stream: current wxSoundStream
+//    - evt: the sound event which has occured, it may be wxSOUND_INPUT,
+//            wxSOUND_OUTPUT or wxSOUND_DUPLEX
+//    - cdata: User callback data
+// ---------------------
 typedef void (*wxSoundCallback)(wxSoundStream *stream, int evt,
                                 char *cdata);
 
@@ -51,7 +93,9 @@ class WXDLLEXPORT wxSoundFormatBase {
   wxSoundFormatBase();
   virtual ~wxSoundFormatBase();
 
+  // It returns a "standard" format type.
   virtual wxSoundFormatType GetType() const { return wxSOUND_NOFORMAT; }
+  // It clones the current format.
   virtual wxSoundFormatBase *Clone() const;
 
   virtual wxUint32 GetTimeFromBytes(wxUint32 bytes) const = 0;
@@ -70,9 +114,9 @@ class wxSoundStream {
   virtual ~wxSoundStream();
 
   // Reads "len" bytes from the sound stream.
-  virtual wxSoundStream& Read(void *buffer, size_t len) = 0;
+  virtual wxSoundStream& Read(void *buffer, wxUint32 len) = 0;
   // Writes "len" byte to the sound stream.
-  virtual wxSoundStream& Write(const void *buffer, size_t len) = 0;
+  virtual wxSoundStream& Write(const void *buffer, wxUint32 len) = 0;
   // Returns the best size for IO calls
   virtual wxUint32 GetBestSize() const { return 1024; }
 
@@ -85,18 +129,19 @@ class wxSoundStream {
   // Register a callback for a specified async event.
   void Register(int evt, wxSoundCallback cbk, char *cdata);
 
-  // Starts the async notifier.
+  // Starts the async notifier. After this call, the stream begins either 
+  // recording or playing or the two at the same time.
   virtual bool StartProduction(int evt) = 0;
   // Stops the async notifier.
   virtual bool StopProduction() = 0;
   // Sets the event handler: if it is non-null, all events are routed to it.
   void SetEventHandler(wxSoundStream *handler) { m_handler = handler; }
 
-  // Initializes the full duplex mode.
-  virtual void SetDuplexMode(bool duplex) = 0;
-
   wxSoundError GetError() const { return m_snderror; }
-  size_t GetLastAccess() const { return m_lastcount; }
+  wxUint32 GetLastAccess() const { return m_lastcount; }
+
+  // This is only useful for device (I think).
+  virtual bool QueueFilled() const { return TRUE; }
 
  protected:
   // Current sound format
@@ -106,7 +151,7 @@ class wxSoundStream {
   wxSoundError m_snderror;
 
   // Last access
-  size_t m_lastcount;
+  wxUint32 m_lastcount;
 
   // Event handler
   wxSoundStream *m_handler;
@@ -115,9 +160,6 @@ class wxSoundStream {
   char *m_cdata[2];
 
  protected:
-  // Do the async stuff.
-  void DoAsyncStuff(int evt);
-
   // Handles event
   virtual void OnSoundEvent(int evt);
 };