[vlc-commits] va_surface: document the API entries

[Steve Lhomme]

vlc | branch: master | Steve Lhomme <robux4 at ycbcr.xyz> | Fri Nov 29 09:30:06 2019 +0100| [1a1a555cff14c7b674a9bf85c5f5d1b559d855a6] | committer: Steve Lhomme

va_surface: document the API entries

> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=1a1a555cff14c7b674a9bf85c5f5d1b559d855a6
---

 modules/codec/avcodec/va_surface_internal.h | 42 +++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/modules/codec/avcodec/va_surface_internal.h b/modules/codec/avcodec/va_surface_internal.h
index 4558505182..c3424a79af 100644
--- a/modules/codec/avcodec/va_surface_internal.h
+++ b/modules/codec/avcodec/va_surface_internal.h
@@ -57,13 +57,55 @@ struct va_pool_cfg {
     void *opaque;
 };
 
+/**
+ * Create a VA pool for the given va module.
+ *
+ * The pf_create_device callback of the pool configuration is called. If it
+ * fails, the pool is not created.
+ */
 va_pool_t * va_pool_Create(vlc_va_t *, const struct va_pool_cfg *);
+
+/**
+ * Close the VA pool.
+ *
+ * If there is no in-flight surfaces left, the pf_destroy_device callback of the
+ * pool configuration is called and the pool is released.
+ * If threre are in-flight pictures the last surface that calls va_surface_Release
+ * will trigger the same behaviour to fully release the pool.
+ */
 void va_pool_Close(va_pool_t *);
+
+/**
+ * Setup the VA pool to allocate the amount of surfaces for the given format.
+ *
+ * The pf_create_decoder_surfaces callback of the pool configuration is called.
+ * If it succeeds, the pf_setup_avcodec_ctx callback will be called afterwards.
+ */
 int va_pool_SetupDecoder(vlc_va_t *, va_pool_t *, AVCodecContext *, const video_format_t *, size_t count);
+
+/**
+ * Get a reference to an available surface or NULL on timeout
+ */
 vlc_va_surface_t *va_pool_Get(va_pool_t *);
 
+/**
+ * Get the index of the va_surface in the pool.
+ */
 size_t va_surface_GetIndex(const vlc_va_surface_t *surface);
+
+/**
+ * Add a reference to the surface.
+ */
 void va_surface_AddRef(vlc_va_surface_t *surface);
+
+/**
+ * Remove a reference to the surface.
+ *
+ * If the pool has been closed and it was the last reference used from the pool,
+ * the pool we be released.
+ *
+ * \see va_pool_Close()
+ */
 void va_surface_Release(vlc_va_surface_t *surface);
 
 #endif /* AVCODEC_VA_SURFACE_INTERNAL_H */