aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRussell Bryant <russellbryant@users.sourceforge.net>2008-01-06 14:30:28 +0000
committerRussell Bryant <russellbryant@users.sourceforge.net>2008-01-06 14:30:28 +0000
commit01aa0ff0fcac3f98df54bf2f55002b00f0afda2d (patch)
tree9f7f1466b36a2c4711609a6ec25647e4c4fcbe2c
parent7d6f1f3c636989d9d50f1bbc9a4419f69345e514 (diff)
(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. svn path=/trunk/externals/ggee/; revision=9134
-rwxr-xr-xsignal/stream.h83
1 files changed, 64 insertions, 19 deletions
diff --git a/signal/stream.h b/signal/stream.h
index 3ccc205..8872165 100755
--- a/signal/stream.h
+++ b/signal/stream.h
@@ -1,29 +1,74 @@
/* (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
+/*!
+ * \file
+ * \author Guenter Geiger
+ *
+ * \brief Definitions used by both streamin~ and streamout~
+ *
+ * \todo This code does not honor network byte order.
+ */
-#define SF_SIZEOF(a) (a == SF_FLOAT ? sizeof(t_float) : a == SF_16BIT ? sizeof(short) : 1)
+#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)
-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 */
+#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 {
- t_tag tag;
- char* data;
+ /*! 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 */