[PD-cvs] externals/ggee/signal stream.h,1.2,1.3

[Russell Bryant]

Update of /cvsroot/pure-data/externals/ggee/signal
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv2842/signal

Modified Files:
	stream.h 
Log Message:
(Merge the rest of my changes from issue #1848356)

When I first starting looking into different ways to stream audio into Pd, I
spent a little bit of time looking at streamin~/streamout~.  While looking at
it, I fixed the security issue from the previous commit, and made the following
updates to stream.h.

 - Adding doxygen style comments.
 - Add an ifdef to prevent against multiple or recursive includes of the header.
 - Document most of the fields in the defined data structures.
 - Fix potential alignment bugs (at least on platforms using GNUC) by using the
   packed attribute for structures defining network frames.
     See http://gcc.gnu.org/onlinedocs/gcc-4.2.2/gcc/Variable-Attributes.html#Variable%20Attributes
 - Point out the fact that this code is not endianness-safe, and that it should
   eventually be updated to respect network byte order.
 - Point out that the version field of the frame header is ignored when parsing
   incoming frames.
 - Change a list of #defines to an enum.
 - Instead of using "int" in the frame header structure, use int32_t to explicitly
   state that the field is 32-bits.
	 


Index: stream.h
===================================================================
RCS file: /cvsroot/pure-data/externals/ggee/signal/stream.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** stream.h	22 May 2005 20:48:00 -0000	1.2
--- stream.h	6 Jan 2008 14:30:28 -0000	1.3
***************
*** 1,29 ****
  /* (C) Guenter Geiger 1999 */
  
! #define SF_FLOAT  1
! #define SF_DOUBLE 2
! #define SF_8BIT   10
! #define SF_16BIT  11
! #define SF_32BIT  12
! #define SF_ALAW   20
! #define SF_MP3    30
  
! #define SF_SIZEOF(a) (a == SF_FLOAT ? sizeof(t_float) : a == SF_16BIT ? sizeof(short) : 1)
  
  
  
! typedef struct _tag {      /* size (bytes) */
!      char version;         /*    1         */
!      char format;          /*    1         */
!      int count;            /*    4         */
!      char channels;        /*    1         */
!      int framesize;        /*    4         */
!      char  extension[5];   /*    5         */
! } t_tag;                   /*--------------*/
!                            /*   16         */
  
  
  typedef struct _frame {
!      t_tag  tag;
!      char*  data;
  } t_frame;
--- 1,74 ----
  /* (C) Guenter Geiger 1999 */
  
! /*!
!  * \file
!  * \author Guenter Geiger
!  *
!  * \brief Definitions used by both streamin~ and streamout~
!  *
!  * \todo This code does not honor network byte order.
!  */
  
! #ifndef __PD_STREAM_H
! #define __PD_STREAM_H
  
+ #include <inttypes.h>
  
+ /*!
+  * \brief Format identifiers for frames
+  */
+ enum tag_format {
+     SF_FLOAT  = 1,
+     SF_DOUBLE = 2,
+     SF_8BIT   = 10,
+     SF_16BIT  = 11,
+     SF_32BIT  = 12,
+     SF_ALAW   = 20,
+     SF_MP3    = 30
+ };
  
! #define SF_SIZEOF(a) (a == SF_FLOAT ? sizeof(t_float) : a == SF_16BIT ? sizeof(short) : 1)
  
+ #ifdef __GNUC__
+ #define PACKED __attribute__ ((packed))
+ #endif
  
+ /*!
+  * \brief 16-byte frame header
+  *
+  * \note Version 1
+  */
+ typedef struct _tag {
+      /*! Frame header version.  Currently ignored in streamin, but always set
+       *  to 1 for streamout.
+       *
+       *  \todo Add version checking on incoming frames.  However, this could
+       *        break existing uses of the external. */
+      char version;
+      /*! This field identifies the type of data is in the frame payload */
+      char format;
+      /*! ??? */
+      int32_t count;
+      /*! ??? */
+      char channels;
+      /*! This indicates the full size of the frame.  It is basically
+       *  ( sizeof(t_tag) + payload length ). */
+      int32_t framesize;
+      /*! ??? */
+      char extension[5];
+ } PACKED t_tag;
+ 
+ 
+ /*!
+  * \brief A complete frame
+  */
  typedef struct _frame {
!      /*! This is the frame header that contains the metadata about the frame */
!      t_tag tag;
!      /*! This buffer stores the frame data payload.  The amount of data in this
!       *  buffer is the tag.framesize - sizeof(t_tag).  Its contents can be
!       *  interpreted according to the tag.version. */
!      char *data;
  } t_frame;
+ 
+ #endif /* __PD_STREAM_H */