ass_cache: add comments documenting ownership of cache key members

libass/ass_cache.h

@@ -55,6 +55,7 @@ typedef void (*CacheItemDestructor)(void *key, void *value);
 
 // cache hash keys
 
+// ownership of members of the types in the union is documented in ass_cache_template.h
 typedef struct outline_hash_key {
     enum {
         OUTLINE_GLYPH,
@@ -77,6 +78,9 @@ enum {
     FILTER_FILL_IN_BORDER = 0x10,
 };
 
+// ass_cache_get() takes ownership of the bitmaps array and either frees it
+// or persists it in the item key; individual bitmaps in the array behave
+// as documented in ass_cache_template.h
 typedef struct {
     FilterDesc filter;
     size_t bitmap_count;

libass/ass_cache_template.h

@@ -58,6 +58,7 @@ START(font, ass_font_desc )
 END(ASS_FontDesc)
 
 // describes an outline bitmap
+// outline is refed when inserted and unrefed when dropped
 START(bitmap, bitmap_hash_key)
     GENERIC(OutlineHashValue *, outline)
     // quantized transform matrix
@@ -67,12 +68,14 @@ START(bitmap, bitmap_hash_key)
     VECTOR(matrix_z)
 END(BitmapHashKey)
 
+// font is refed when inserted and unrefed when dropped
 START(face_size_metrics, face_size_metrics_hash_key)
     GENERIC(ASS_Font *, font)
     GENERIC(double, size)
     GENERIC(int, face_index)
 END(FaceSizeMetricsHashKey)
 
+// font is refed when inserted and unrefed when dropped
 START(glyph_metrics, glyph_metrics_hash_key)
     GENERIC(ASS_Font *, font)
     GENERIC(double, size)
@@ -81,6 +84,7 @@ START(glyph_metrics, glyph_metrics_hash_key)
 END(GlyphMetricsHashKey)
 
 // describes an outline glyph
+// font is refed when inserted and unrefed when dropped
 START(glyph, glyph_hash_key)
     GENERIC(ASS_Font *, font)
     GENERIC(double, size) // font size
@@ -92,11 +96,14 @@ START(glyph, glyph_hash_key)
 END(GlyphHashKey)
 
 // describes an outline drawing
+// on call to ass_cache_get(), text is a non-owning view;
+// its content is duplicated when inserted; the copy is freed when dropped
 START(drawing, drawing_hash_key)
     STRING(text)
 END(DrawingHashKey)
 
 // describes an offset outline
+// outline is refed when inserted and unrefed when dropped
 START(border, border_hash_key)
     GENERIC(OutlineHashValue *, outline)
     // outline is scaled by 2^scale_ord_x|y before stroking
@@ -116,6 +123,7 @@ START(filter, filter_desc)
 END(FilterDesc)
 
 // describes glyph bitmap reference
+// bm and bm_o are refed when inserted and unrefed when dropped
 START(bitmap_ref, bitmap_ref_key)
     GENERIC(Bitmap *, bm)
     GENERIC(Bitmap *, bm_o)