Update comments.

git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@23197 b3059339-0415-0410-9bf9-f77b7e298cf2

diff --git a/libass/ass_render.c b/libass/ass_render.c
index 5a1c0e5a190096dfbfc2eded98aa4e1030e4463b..7a118e02b1a5914012fe2433c1c97660e7a78c24 100644 (file)
--- a/libass/ass_render.c
+++ b/libass/ass_render.c
@@ -381,8 +381,8 @@ static ass_image_t** render_glyph(bitmap_t* bm, int dst_x, int dst_y, uint32_t c
 }
 
 /**
- * \brief Render text_info_t struct into ass_image_t list
- * Rasterize glyphs and put them in glyph cache.
+ * \brief Convert text_info_t struct to ass_image_t list
+ * Splits glyphs in halves when needed (for \kf karaoke).
  */
 static ass_image_t* render_text(text_info_t* text_info, int dst_x, int dst_y)
 {
@@ -1197,6 +1197,16 @@ static void free_render_context(void)
 {
 }
 
+/**
+ * \brief Get normal and outline (border) glyphs
+ * \param symbol ucs4 char
+ * \param info out: struct filled with extracted data
+ * \param advance subpixel shift vector used for cache lookup
+ * Tries to get both glyphs from cache.
+ * If they can't be found, gets a glyph from font face, generates outline with FT_Stroker,
+ * and add them to cache.
+ * The glyphs are returned in info->glyph and info->outline_glyph
+ */
 static void get_outline_glyph(int symbol, glyph_info_t* info, FT_Vector* advance)
 {
        int error;
@@ -1252,12 +1262,12 @@ static void get_outline_glyph(int symbol, glyph_info_t* info, FT_Vector* advance
 static void transform_3d(FT_Vector shift, FT_Glyph* glyph, FT_Glyph* glyph2, double frx, double fry, double frz);
 
 /**
- * \brief Get normal and outline glyphs from cache (if possible) or font face
- * \param index face glyph index
- * \param symbol ucs4 char
- * \param info out: struct filled with extracted data
- * \param advance advance vector of the extracted glyph
- * \return 0 on success
+ * \brief Get bitmaps for a glyph
+ * \param info glyph info
+ * Tries to get glyph bitmaps from bitmap cache.
+ * If they can't be found, they are generated by rotating and rendering the glyph.
+ * After that, bitmaps are added to the cache.
+ * They are returned in info->bm (glyph), info->bm_o (outline) and info->bm_s (shadow).
  */
 static void get_bitmap_glyph(glyph_info_t* info)
 {
@@ -1277,11 +1287,13 @@ static void get_bitmap_glyph(glyph_info_t* info)
                int error;
                info->bm = info->bm_o = info->bm_s = 0;
                if (info->glyph && info->symbol != '\n' && info->symbol != 0) {
-                       // calculating shift vector
+                       // calculating rotation shift vector (from rotation origin to the glyph basepoint)
                        shift.x = int_to_d6(info->hash_key.shift_x);
                        shift.y = int_to_d6(info->hash_key.shift_y);
+                       // apply rotation
                        transform_3d(shift, &info->glyph, &info->outline_glyph, info->frx, info->fry, info->frz);
 
+                       // render glyph
                        error = glyph_to_bitmap(ass_renderer->synth_priv,
                                        info->glyph, info->outline_glyph,
                                        &info->bm, &info->bm_o,
@@ -1289,12 +1301,13 @@ static void get_bitmap_glyph(glyph_info_t* info)
                        if (error)
                                info->symbol = 0;
 
-                       // cache
+                       // add bitmaps to cache
                        hash_val.bm_o = info->bm_o;
                        hash_val.bm = info->bm;
                        hash_val.bm_s = info->bm_s;
                        cache_add_bitmap(&(info->hash_key), &hash_val);
                }
+               // deallocate glyphs
                if (info->glyph)
                        FT_Done_Glyph(info->glyph);
                if (info->outline_glyph)
@@ -1936,7 +1949,7 @@ static int ass_render_event(ass_event_t* event, event_images_t* event_images)
                render_context.clip_y1 = y2scr(render_context.clip_y1);
        }
 
-       // rotate glyphs if needed
+       // calculate rotation parameters
        {
                FT_Vector center;
                
@@ -1963,6 +1976,7 @@ static int ass_render_event(ass_event_t* event, event_images_t* event_images)
                }
        }
 
+       // convert glyphs to bitmaps
        for (i = 0; i < text_info.length; ++i)
                get_bitmap_glyph(text_info.glyphs + i);