1 files changed, 98 insertions, 24 deletions

diff --git a/src/gqueue/sys_defs.h b/src/gqueue/sys_defs.h
index 4351d4ad..ea3f176e 100644
--- a/src/gqueue/sys_defs.h
+++ b/src/gqueue/sys_defs.h
@@ -23,6 +23,8 @@
  * 			operations because fully synchronous queues have the highest storage requirements. The other queue types are
  * 			optimizations. Efficiency IS important to use (particularly RAM efficiency).
  * 			In practice we only implement ASync, GSync and FSync queues as PSync queues are of dubious value.
+ * 			<br>
+ * 			We also define GDataBuffer which is a data buffer that supports being queued.
  * @{
  */
 
@@ -32,45 +34,52 @@
 #if GFX_USE_GQUEUE || defined(__DOXYGEN__)
 
 /**
+ * @brief	A queue item
+ * @{
+ */
+typedef struct gfxQueueASyncItem {
+	struct gfxQueueASyncItem	*next;
+} gfxQueueASyncItem, gfxQueueGSyncItem;
+
+typedef struct gfxQueueFSyncItem {
+	struct gfxQueueFSyncItem	*next;
+	gfxSem						sem;
+} gfxQueueFSyncItem;
+/* @} */
+
+/**
  * @brief	A queue
  * @{
  */
 typedef struct gfxQueueASync {
-	struct gfxQueueASyncItem	*head;
-	struct gfxQueueASyncItem	*tail;
+	gfxQueueASyncItem	*head;
+	gfxQueueASyncItem	*tail;
 } gfxQueueASync;
 
 typedef struct gfxQueueGSync {
-	struct gfxQueueGSyncItem	*head;
-	struct gfxQueueGSyncItem	*tail;
-	gfxSem						sem;
+	gfxQueueGSyncItem	*head;
+	gfxQueueGSyncItem	*tail;
+	gfxSem				sem;
 } gfxQueueGSync;
 
 typedef struct gfxQueueFSync {
-	struct gfxQueueFSyncItem	*head;
-	struct gfxQueueFSyncItem	*tail;
-	gfxSem						sem;
+	gfxQueueFSyncItem	*head;
+	gfxQueueFSyncItem	*tail;
+	gfxSem				sem;
 } gfxQueueFSync;
 /* @} */
 
 /**
- * @brief	A queue item
- * @{
+ * @brief	A Data Buffer Queue
+ * @note	This structure is followed immediately by the data itself.
+ * 			When allocating the buffers for the data put this structure
+ * 			at the beginning of the buffer.
  */
-typedef struct gfxQueueASyncItem {
-	struct gfxQueueASyncItem	*next;
-} gfxQueueASyncItem;
-
-typedef struct gfxQueueGSyncItem {
-	struct gfxQueueGSyncItem	*next;
-} gfxQueueGSyncItem;
-
-typedef struct gfxQueueFSyncItem {
-	struct gfxQueueFSyncItem	*next;
-	gfxSem						sem;
-} gfxQueueFSyncItem;
-/* @} */
-
+typedef struct GDataBuffer {
+	gfxQueueGSyncItem	next;		// @< Used for queueing the buffers
+	size_t				size;		// @< The size of the buffer area following this structure (in bytes)
+	size_t				len;		// @< The length of the data in the buffer area (in bytes)
+} GDataBuffer;
 
 /*===========================================================================*/
 /* Function declarations.                                                    */
@@ -98,6 +107,19 @@ void gfxQueueFSyncInit(gfxQueueFSync *pqueue);
 /* @} */
 
 /**
+ * @brief	De-Initialise a queue.
+ *
+ * @param[in]	pqueue	A pointer to the queue
+ *
+ * @api
+ * @{
+ */
+#define gfxQueueASyncDeinit(pqueue)
+void gfxQueueGSyncDeinit(gfxQueueGSync *pqueue);
+void gfxQueueFSyncDeinit(gfxQueueFSync *pqueue);
+/* @} */
+
+/**
  * @brief	Get an item from the head of the queue (and remove it from the queue).
  * @return	NULL if the timeout expires before an item is available
  *
@@ -286,6 +308,58 @@ bool_t gfxQueueFSyncIsInI(gfxQueueFSync *pqueue, const gfxQueueFSyncItem *pitem)
 #define gfxQueueFSyncNextI(pitem)	((const gfxQueueFSyncItem *)((pitem)->next))
 /* @} */
 
+/**
+ * @brief		Allocate some buffers and put them on the free list
+ * @return		TRUE is it succeeded. FALSE on allocation failure.
+ *
+ * @param[in] num	The number of buffers to allocate
+ * @param[in] size	The size (in bytes) of each buffer
+ *
+ * @api
+ */
+bool_t gfxBufferAlloc(unsigned num, size_t size);
+
+/**
+ * @brief		Is there one or more buffers currently available on the free list
+ * @return		TRUE if there are buffers in the free list
+ *
+ * @api
+ * @{
+ */
+bool_t gfxBufferIsAvailable(void);
+/* @} */
+
+/**
+ * @brief		Get a buffer from the free list
+ * @return		A GDataBuffer pointer or NULL if the timeout is exceeded
+ *
+ * @params[in] ms	The maximum amount of time in milliseconds to wait for a buffer if one is not available.
+ *
+ * @api
+ * @{
+ */
+GDataBuffer *gfxBufferGet(delaytime_t ms);
+GDataBuffer *gfxBufferGetI(void);
+/* @} */
+
+/**
+ * @brief		Release a buffer back to the free list
+ *
+ * @param[in] pd		The buffer to put (back) on the free-list.
+ *
+ * @note		This call should be used to return any buffers that were taken from
+ * 				the free-list once they have been finished with. It can also be used
+ * 				to put new buffers onto the free-list. Just make sure the "size" field
+ * 				of the GDataBuffer structure has been filled in first.
+ *
+ * @api
+ * @{
+ */
+void gfxBufferRelease(GDataBuffer *pd);
+void gfxBufferReleaseI(GDataBuffer *pd);
+/* @} */
+
+
 #ifdef __cplusplus
 }
 #endif