Update comments.

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

1 files changed, 25 insertions, 11 deletions

diff --git a/libass/ass_render.c b/libass/ass_render.c
index 5a1c0e5a19..7a118e02b1 100644
--- 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);