[Spice-devel] [PATCH] Add some documentation to image-encoders header

[Frediano Ziglio]

Signed-off-by: Frediano Ziglio <fziglio at redhat.com>
---
 server/image-encoders.h | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/server/image-encoders.h b/server/image-encoders.h
index e07c036..230dd7c 100644
--- a/server/image-encoders.h
+++ b/server/image-encoders.h
@@ -45,15 +45,49 @@ void image_encoder_shared_stat_print(const ImageEncoderSharedData *shared_data);
 
 void image_encoders_init(ImageEncoders *enc, ImageEncoderSharedData *shared_data);
 void image_encoders_free(ImageEncoders *enc);
+
+/**
+ * Free Glz images which are no more retained.
+ * Caller should prevent encoding using the dictionary during the operation.
+ */
 int image_encoders_free_some_independent_glz_drawables(ImageEncoders *enc);
+
+/**
+ * Free all Glz images build from these encoders.
+ */
 void image_encoders_free_glz_drawables(ImageEncoders *enc);
+
+/**
+ * Free all Glz images marked as freed.
+ * Images are marked as freed when removed from Glz dictionary but
+ * was not possible to free as the removal was from another thread.
+ */
 void image_encoders_free_glz_drawables_to_free(ImageEncoders* enc);
+
 gboolean image_encoders_glz_create(ImageEncoders *enc, uint8_t id);
 void image_encoders_glz_get_restore_data(ImageEncoders *enc,
                                          uint8_t *out_id, GlzEncDictRestoreData *out_data);
+
+/**
+ * Disable Glz encoding on a given encoder.
+ */
 gboolean image_encoders_glz_encode_lock(ImageEncoders *enc);
+
+/**
+ * Enable again Glz encoding on a given encoder.
+ */
 void image_encoders_glz_encode_unlock(ImageEncoders *enc);
+
+/**
+ * Free all Glz images associated with a retention structure.
+ * Caller should prevent encoding using the dictionary during the operation.
+ */
 void glz_retention_free_drawables(GlzImageRetention *ret);
+
+/**
+ * Mark all Glz images associated with a retention structure
+ * as not retained.
+ */
 void glz_retention_detach_drawables(GlzImageRetention *ret);
 
 #define RED_COMPRESS_BUF_SIZE (1024 * 64)
@@ -132,6 +166,12 @@ typedef struct {
     EncoderData data;
 } GlzData;
 
+/**
+ * This structure is used to associate Glz images to be freed.
+ * Can be used to notify that attached images should be freed
+ * or are no more associated and could be freed later if
+ * needed.
+ */
 struct GlzImageRetention {
     Ring ring;
 };
@@ -204,6 +244,14 @@ int image_encoders_compress_jpeg(ImageEncoders *enc, SpiceImage *dest,
                                  SpiceBitmap *src, compress_send_data_t* o_comp_data);
 int image_encoders_compress_lz4(ImageEncoders *enc, SpiceImage *dest,
                                 SpiceBitmap *src, compress_send_data_t* o_comp_data);
+
+/**
+ * Compress an image with Glz.
+ * Glz use a shared dictionary which needs to access images stored
+ * in RedDrawables even after the compression took place.
+ * For this reason these drawables are marked in a GlzImageRetention
+ * structure.
+ */
 int image_encoders_compress_glz(ImageEncoders *enc,
                                 SpiceImage *dest, SpiceBitmap *src,
                                 RedDrawable *red_drawable,
-- 
2.7.4