Clarify aom_codec_get_global_headers() comments.
- Explain how memory owned by callers should be freed.
- Document the format of the returned OBU.
BUG=aomedia:2012
Change-Id: Id98c643e2740e4f38c37f1006caf713d505322c7
diff --git a/aom/aom_encoder.h b/aom/aom_encoder.h
index ee83aa3..2d9b4eb 100644
--- a/aom/aom_encoder.h
+++ b/aom/aom_encoder.h
@@ -853,15 +853,21 @@
* has been passed to libaom. Otherwise the global header data may be
* invalidated by additional configuration changes.
*
+ * The AV1 implementation of this function returns an OBU. The OBU returned is
+ * in Low Overhead Bitstream Format. Specifically, the obu_has_size_field bit is
+ * set, and the buffer contains the obu_size field for the returned OBU.
+ *
* \param[in] ctx Pointer to this instance's context
*
* \retval NULL
* Encoder does not support global header, or an error occurred while
* generating the global header.
+ *
* \retval Non-NULL
* Pointer to buffer containing global header packet. The caller owns the
- * memory associated with this buffer, and must free the 'buf' member as
- * well as the aom_fixed_buf_t pointer.
+ * memory associated with this buffer, and must free the 'buf' member of the
+ * aom_fixed_buf_t as well as the aom_fixed_buf_t pointer. Memory returned
+ * must be freed via call to free().
*/
aom_fixed_buf_t *aom_codec_get_global_headers(aom_codec_ctx_t *ctx);
diff --git a/av1/encoder/encoder.h b/av1/encoder/encoder.h
index e147722..7fc6a82 100644
--- a/av1/encoder/encoder.h
+++ b/av1/encoder/encoder.h
@@ -945,7 +945,12 @@
// Returns a Sequence Header OBU stored in an aom_fixed_buf_t, or NULL upon
// failure. When a non-NULL aom_fixed_buf_t pointer is returned by this
// function, the memory must be freed by the caller. Both the buf member of the
-// aom_fixed_buf_t, and the aom_fixed_buf_t pointer itself must be freed.
+// aom_fixed_buf_t, and the aom_fixed_buf_t pointer itself must be freed. Memory
+// returned must be freed via call to free().
+//
+// Note: The OBU returned is in Low Overhead Bitstream Format. Specifically,
+// the obu_has_size_field bit is set, and the buffer contains the obu_size
+// field.
aom_fixed_buf_t *av1_get_global_headers(AV1_COMP *cpi);
#ifdef __cplusplus
