From dd1a5a82c11db30b8bbdc4c002970cb4d9b0ec2f Mon Sep 17 00:00:00 2001
From: eugeni <eugeni@b3059339-0415-0410-9bf9-f77b7e298cf2>
Date: Sun, 17 Dec 2006 12:00:55 +0000
Subject: Update some comments.

git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@21646 b3059339-0415-0410-9bf9-f77b7e298cf2
---
 libass/ass_font.c       | 31 +++++++++++++++++++++++++++++++
 libass/ass_fontconfig.c | 18 ++++++++++++------
 2 files changed, 43 insertions(+), 6 deletions(-)

(limited to 'libass')

diff --git a/libass/ass_font.c b/libass/ass_font.c
index 5491ed53ff..1ae136bc1e 100644
--- a/libass/ass_font.c
+++ b/libass/ass_font.c
@@ -52,6 +52,9 @@ static void charmap_magic(FT_Face face)
 	}
 }
 
+/**
+ * \brief find a memory font by name
+ */
 static int find_font(ass_library_t* library, char* name)
 {
 	int i;
@@ -61,6 +64,9 @@ static int find_font(ass_library_t* library, char* name)
 	return -1;
 }
 
+/**
+ * \brief Create a new ass_font_t according to "desc" argument
+ */
 ass_font_t* ass_font_new(ass_library_t* library, FT_Library ftlibrary, void* fc_priv, ass_font_desc_t* desc)
 {
 	char* path;
@@ -116,6 +122,9 @@ ass_font_t* ass_font_new(ass_library_t* library, FT_Library ftlibrary, void* fc_
 	return font;
 }
 
+/**
+ * \brief Set font transformation matrix and shift vector
+ **/
 void ass_font_set_transform(ass_font_t* font, FT_Matrix* m, FT_Vector* v)
 {
 	int i;
@@ -129,6 +138,9 @@ void ass_font_set_transform(ass_font_t* font, FT_Matrix* m, FT_Vector* v)
 		FT_Set_Transform(font->faces[i], &font->m, &font->v);
 }
 
+/**
+ * \brief Set font size
+ **/
 void ass_font_set_size(ass_font_t* font, int size)
 {
 	int i;
@@ -140,6 +152,10 @@ void ass_font_set_size(ass_font_t* font, int size)
 }
 
 #ifdef HAVE_FONTCONFIG
+/**
+ * \brief Select a new FT_Face with the given character
+ * The new face is added to the end of font->faces.
+ **/
 static void ass_font_reselect(void* fontconfig_priv, ass_font_t* font, uint32_t ch)
 {
 	char* path;
@@ -173,6 +189,11 @@ static void ass_font_reselect(void* fontconfig_priv, ass_font_t* font, uint32_t
 }
 #endif
 
+/**
+ * \brief Get maximal font ascender and descender.
+ * \param ch character code
+ * The values are extracted from the font face that provides glyphs for the given character
+ **/
 void ass_font_get_asc_desc(ass_font_t* font, uint32_t ch, int* asc, int* desc)
 {
 	int i;
@@ -194,6 +215,10 @@ void ass_font_get_asc_desc(ass_font_t* font, uint32_t ch, int* asc, int* desc)
 	*asc = *desc = 0;
 }
 
+/**
+ * \brief Get a glyph
+ * \param ch character code
+ **/
 FT_Glyph ass_font_get_glyph(void* fontconfig_priv, ass_font_t* font, uint32_t ch)
 {
 	int error;
@@ -253,6 +278,9 @@ FT_Glyph ass_font_get_glyph(void* fontconfig_priv, ass_font_t* font, uint32_t ch
 	return glyph;
 }
 
+/**
+ * \brief Get kerning for the pair of glyphs.
+ **/
 FT_Vector ass_font_get_kerning(ass_font_t* font, uint32_t c1, uint32_t c2)
 {
 	FT_Vector v = {0, 0};
@@ -273,6 +301,9 @@ FT_Vector ass_font_get_kerning(ass_font_t* font, uint32_t c1, uint32_t c2)
 	return v;
 }
 
+/**
+ * \brief Deallocate ass_font_t
+ **/
 void ass_font_free(ass_font_t* font)
 {
 	int i;
diff --git a/libass/ass_fontconfig.c b/libass/ass_fontconfig.c
index ef740a7d70..93e7a0adf3 100644
--- a/libass/ass_fontconfig.c
+++ b/libass/ass_fontconfig.c
@@ -54,6 +54,7 @@ struct fc_instance_s {
  * \param bold font weight value
  * \param italic font slant value
  * \param index out: font index inside a file
+ * \param charset: contains the characters that should be present in the font, can be NULL
  * \return font file path
 */ 
 static char* _select_font(fc_instance_t* priv, const char* family, unsigned bold, unsigned italic, int* index,
@@ -150,6 +151,7 @@ static char* _select_font(fc_instance_t* priv, const char* family, unsigned bold
  * \param bold font weight value
  * \param italic font slant value
  * \param index out: font index inside a file
+ * \param charset: contains the characters that should be present in the font, can be NULL
  * \return font file path
 */ 
 char* fontconfig_select_with_charset(fc_instance_t* priv, const char* family, unsigned bold, unsigned italic, int* index,
@@ -224,10 +226,13 @@ static char* validate_fname(char* name)
 }
 
 /**
- * \brief Process embedded matroska font. Saves it to ~/.mplayer/fonts.
- * \param name attachment name
- * \param data binary font data
- * \param data_size data size
+ * \brief Process memory font.
+ * \param priv private data
+ * \param library library object
+ * \param ftlibrary freetype library object
+ * \param idx index of the processed font in library->fontdata
+ * With FontConfig >= 2.4.2, builds a font pattern in memory via FT_New_Memory_Face/FcFreeTypeQueryFace.
+ * With older FontConfig versions, save the font to ~/.mplayer/fonts.
 */ 
 static void process_fontdata(fc_instance_t* priv, ass_library_t* library, FT_Library ftlibrary, int idx)
 {
@@ -309,7 +314,8 @@ static void process_fontdata(fc_instance_t* priv, ass_library_t* library, FT_Lib
 
 /**
  * \brief Init fontconfig.
- * \param dir additional directoryu for fonts
+ * \param library libass library object
+ * \param ftlibrary freetype library object
  * \param family default font family
  * \param path default font path
  * \return pointer to fontconfig private data
@@ -385,7 +391,7 @@ fc_instance_t* fontconfig_init(ass_library_t* library, FT_Library ftlibrary, con
 	return priv;
 }
 
-#else
+#else // HAVE_FONTCONFIG
 
 char* fontconfig_select(fc_instance_t* priv, const char* family, unsigned bold, unsigned italic, int* index)
 {
-- 
cgit v1.2.3