New upstream version 21.0.2+dfsg1

docs/sphinx/reference-libobs-util-circlebuf.rst

@@ -0,0 +1,158 @@
+Circular Buffers
+================
+
+A circular buffer that will automatically increase in size as necessary
+as data is pushed to the front or back.
+
+.. code:: cpp
+
+   #include <util/circlebuf.h>
+
+
+Circular Buffer Structure (struct circlebuf)
+--------------------------------------------
+
+.. type:: struct circlebuf
+.. member:: void   *circlebuf.data
+.. member:: size_t circlebuf.size
+.. member:: size_t circlebuf.start_pos
+.. member:: size_t circlebuf.end_pos
+.. member:: size_t circlebuf.capacity
+
+
+Circular Buffer Inline Functions
+--------------------------------
+
+.. function:: void circlebuf_init(struct circlebuf *cb)
+
+   Initializes a circular buffer (just zeroes out the entire structure).
+
+   :param cb: The circular buffer
+
+---------------------
+
+.. function:: void circlebuf_free(struct circlebuf *cb)
+
+   Frees a circular buffer.
+
+   :param cb: The circular buffer
+
+---------------------
+
+.. function:: void circlebuf_reserve(struct circlebuf *cb, size_t capacity)
+
+   Reserves a specific amount of buffer space to ensure minimum
+   upsizing.
+
+   :param cb:       The circular buffer
+   :param capacity: The new capacity, in bytes
+
+---------------------
+
+.. function:: void circlebuf_upsize(struct circlebuf *cb, size_t size)
+
+   Sets the current active (not just reserved) size.  Any new data is
+   zeroed.
+
+   :param cb:       The circular buffer
+   :param size:     The new size, in bytes
+
+---------------------
+
+.. function:: void circlebuf_place(struct circlebuf *cb, size_t position, const void *data, size_t size)
+
+   Places data at a specific positional index (relative to the starting
+   point) within the circular buffer.
+
+   :param cb:       The circular buffer
+   :param position: Positional index relative to starting point
+   :param data:     Data to insert
+   :param size:     Size of data to insert
+
+---------------------
+
+.. function:: void circlebuf_push_back(struct circlebuf *cb, const void *data, size_t size)
+
+   Pushes data to the end of the circular buffer.
+
+   :param cb:       The circular buffer
+   :param data:     Data
+   :param size:     Size of data
+
+---------------------
+
+.. function:: void circlebuf_push_front(struct circlebuf *cb, const void *data, size_t size)
+
+   Pushes data to the front of the circular buffer.
+
+   :param cb:       The circular buffer
+   :param data:     Data
+   :param size:     Size of data
+
+---------------------
+
+.. function:: void circlebuf_push_back_zero(struct circlebuf *cb, size_t size)
+
+   Pushes zeroed data to the end of the circular buffer.
+
+   :param cb:       The circular buffer
+   :param size:     Size
+
+---------------------
+
+.. function:: void circlebuf_push_front_zero(struct circlebuf *cb, size_t size)
+
+   Pushes zeroed data to the front of the circular buffer.
+
+   :param cb:       The circular buffer
+   :param size:     Size
+
+---------------------
+
+.. function:: void circlebuf_peek_front(struct circlebuf *cb, void *data, size_t size)
+
+   Peeks data at the front of the circular buffer.
+
+   :param cb:       The circular buffer
+   :param data:     Buffer to store data in
+   :param size:     Size of data to retrieve
+
+---------------------
+
+.. function:: void circlebuf_peek_back(struct circlebuf *cb, void *data, size_t size)
+
+   Peeks data at the back of the circular buffer.
+
+   :param cb:       The circular buffer
+   :param data:     Buffer to store data in
+   :param size:     Size of data to retrieve
+
+---------------------
+
+.. function:: void circlebuf_pop_front(struct circlebuf *cb, void *data, size_t size)
+
+   Pops data from the front of the circular buffer.
+
+   :param cb:       The circular buffer
+   :param data:     Buffer to store data in, or *NULL*
+   :param size:     Size of data to retrieve
+
+---------------------
+
+.. function:: void circlebuf_pop_back(struct circlebuf *cb, void *data, size_t size)
+
+   Pops data from the back of the circular buffer.
+
+   :param cb:       The circular buffer
+   :param data:     Buffer to store data in, or *NULL*
+   :param size:     Size of data to retrieve
+
+---------------------
+
+.. function:: void *circlebuf_data(struct circlebuf *cb, size_t idx)
+
+   Gets a direct pointer to data at a specific positional index within
+   the circular buffer, relative to the starting point.
+
+   :param cb:       The circular buffer
+   :param idx:      Byte index relative to the starting point