Skip to content

V
vlc
Commit d9cc405c authored by Salah-Eddin Shaban's avatar Salah-Eddin Shaban Committed by Jean-Baptiste Kempf
Browse files
Options

Freetype: comments and documentation 

Signed-off-by: default avatarJean-Baptiste Kempf <jb@videolan.org>
parent c20e0373
Show whitespace changes
Inline Side-by-side
Showing with 155 additions and 61 deletions
modules/text_renderer/fonts/android.c
View file @ d9cc405c
......@@ -111,8 +111,8 @@ static int Android_ParseFamily( filter_t *p_filter, xml_reader_t *p_xml )
/*
* If p_family has not been set by the time we encounter the first file,
* it means this family has no name, and should be used only as a fallback.
* We create a new family for it in the master list and later add it to
* the "default" fallback list.
* We create a new family for it in the master list with the name "fallback-xx"
* and later add it to the "default" fallback list.
*/
else if( !strcasecmp( "file", p_node ) )
{
......@@ -172,6 +172,10 @@ static int Android_ParseFamily( filter_t *p_filter, xml_reader_t *p_xml )
return VLC_EGENERIC;
}
/*
* If the family name has "fallback" in it, add it to the
* "default" fallback list.
*/
if( strcasestr( p_family->psz_name, FB_NAME ) )
{
vlc_family_t *p_fallback =
......
modules/text_renderer/fonts/win32.c
View file @ d9cc405c
......@@ -177,6 +177,11 @@ static int CALLBACK EnumFontCallback(const ENUMLOGFONTEX *lpelfe, const NEWTEXTM
bool b_bold = ( lpelfe->elfLogFont.lfWeight == FW_BOLD );
bool b_italic = ( lpelfe->elfLogFont.lfItalic != 0 );
/*
* This function will be called by Windows as many times for each font
* of the family as the number of scripts the font supports.
* Check to avoid duplicates.
*/
for( vlc_font_t *p_font = p_family->p_fonts; p_font; p_font = p_font->p_next )
if( !!p_font->b_bold == !!b_bold && !!p_font->b_italic == !!b_italic )
return 1;
......@@ -355,6 +360,12 @@ vlc_family_t *Win32_GetFallbacks( filter_t *p_filter, const char *psz_family,
if( p_fallbacks )
p_family = SearchFallbacks( p_filter, p_fallbacks, codepoint );
/*
* If the fallback list of psz_family has no family which contains the requested
* codepoint, try UniscribeFallback(). If it returns a valid family which does
* contain that codepoint, add the new family to the fallback list to speed up
* later searches.
*/
if( !p_family )
{
psz_uniscribe = UniscribeFallback( psz_lc, codepoint );
......
modules/text_renderer/freetype.h
View file @ d9cc405c
......@@ -28,6 +28,13 @@
#ifndef VLC_FREETYPE_H
#define VLC_FREETYPE_H
/** \defgroup freetype Freetype text renderer
* Freetype text rendering cross platform
* @{
* \file
* Freetype module
*/
#ifdef HAVE_CONFIG_H
# include "config.h"
#endif
......@@ -83,25 +90,25 @@ struct filter_sys_t
input_attachment_t **pp_font_attachments;
int i_font_attachments;
/*
/**
* This is the master family list. It owns the lists of vlc_font_t's
* and should be freed using FreeFamiliesAndFonts()
*/
vlc_family_t *p_families;
/*
/**
* This maps a family name to a vlc_family_t within the master list
*/
vlc_dictionary_t family_map;
/*
/**
* This maps a family name to a fallback list of vlc_family_t's.
* Fallback lists only reference the lists of vlc_font_t's within the
* master list, so they should be freed using FreeFamilies()
*/
vlc_dictionary_t fallback_map;
/* Font face cache */
/** Font face cache */
vlc_dictionary_t face_map;
int i_fallback_counter;
......@@ -115,14 +122,14 @@ struct filter_sys_t
int *index, uni_char_t codepoint);
/**
* Get a pointer to the vlc_family_t in the master list that matches psz_family.
* Get a pointer to the vlc_family_t in the master list that matches \p psz_family.
* Add this family to the list if it hasn't been added yet.
*/
const vlc_family_t * (*pf_get_family) ( filter_t *p_filter, const char *psz_family );
/**
* Get the fallback list for psz_family from the system and cache
* it in fallback_map.
* Get the fallback list for \p psz_family from the system and cache
* it in \ref fallback_map.
* On Windows fallback lists are populated progressively as required
* using Uniscribe, so we need the codepoint here.
*/
......
modules/text_renderer/platform_fonts.c
View file @ d9cc405c
......@@ -30,6 +30,12 @@
* Preamble
*****************************************************************************/
/** \ingroup freetype_fonts
* @{
* \file
* Platform-independent font management
*/
#ifdef HAVE_CONFIG_H
# include "config.h"
#endif
......@@ -128,6 +134,16 @@ FT_Face GetFace( filter_t *p_filter, vlc_font_t *p_font )
return p_font->p_face;
}
/**
* Select the best font from the list of vlc_font_t's of the given family.
* If a family does not have the exact requested style, the nearest one will be returned.
* Like when an italic font is requested from a family which has only a regular font. In this
* case the regular font will be returned and FreeType will do synthetic styling on it.
*
* Not all fonts of a family support the same scripts. As an example, when an italic font
* containing an Arabic codepoint is requested from the Arial family, the regular font will
* be returned, because the italic font of Arial has no Arabic support.
*/
static vlc_font_t *GetBestFont( filter_t *p_filter, const vlc_family_t *p_family,
bool b_bold, bool b_italic, uni_char_t codepoint )
{
......
modules/text_renderer/platform_fonts.h
View file @ d9cc405c
......@@ -98,7 +98,11 @@ typedef struct vlc_font_t vlc_font_t;
struct vlc_font_t
{
vlc_font_t *p_next; /**< next font in the chain */
char *psz_fontfile; /**< path to the file on the disk */
/**
* path to the font file on disk, or ":/x" for font attachments, where x
* is the attachment index within \ref filter_sys_t::pp_font_attachments
*/
char *psz_fontfile;
int i_index; /**< index of the font in the font file, starts at 0 */
bool b_bold; /**< if the font is a bold version */
bool b_italic; /**< if the font is an italic version */
......@@ -111,7 +115,17 @@ struct vlc_font_t
struct vlc_family_t
{
vlc_family_t *p_next; /**< next family in the chain */
char *psz_name; /**< Human-reable name, usually requested */
/**
* Human-readable name, usually requested.
* Can be fallback-xx for font attachments with no family name, and for fallback
* fonts in Android.
* This field is used only for loading the family fonts, and for debugging.
* Apart from that, families are accessed either through the
* \ref filter_sys_t::family_map dictionary, or as a member of some fallback list
* in \ref filter_sys_t::fallback_map. And this field plays no role in either of
* the two cases.
*/
char *psz_name;
vlc_font_t *p_fonts; /**< fonts matching this family */
};
......@@ -171,10 +185,16 @@ char* Generic_Select( filter_t *p_filter, const char* family,
*
* \param psz_family the usual font family name, human-readable;
* if NULL, will use "fallback-xx"[IN]
* \param pp_list the family list where to append the font;
* can be NULL if not in a list [IN]
* \param p_dict dictionnary where to insert this family; can be NULL [IN]
* \param psz_key specific key for the dictionnary [IN]
* \param pp_list the family list where to append the new family;
* can be NULL if not in a list, or if the family is to be appended to a fallback list
* within \ref filter_sys_t::fallback_map [IN]
* \param p_dict dictionary where to insert this family; can be NULL.
* If the dictionary already has an entry for \p psz_key, which is often the case when adding
* a new fallback to a fallback list within \ref filter_sys_t::fallback_map, the new family will be
* appended there [IN]
* \param psz_key specific key for the dictionary.
* If NULL will use whatever is used for the family name, whether it is the specified \p psz_family
* or "fallback-xx" [IN]
*
* \return the new family representation
*/
......@@ -185,7 +205,8 @@ vlc_family_t *NewFamily( filter_t *p_filter, const char *psz_family,
/**
* Creates a new font.
*
* \param psz_fontfile font file [IN]
* \param psz_fontfile font file, or ":/x" for font attachments, where x is the attachment index
* within \ref filter_sys_t::pp_font_attachments [IN]
* \param i_index index of the font in the font file [IN]
* \param b_bold is a bold font or not [IN]
* \param b_bold is an italic or not [IN]
......@@ -193,7 +214,7 @@ vlc_family_t *NewFamily( filter_t *p_filter, const char *psz_family,
* If not NULL, the font will be associated to this family, and
* appended to the font list in that family [IN]
*
* \remark This function takes ownership of psz_fontfile
* \remark This function takes ownership of \p psz_fontfile
* \return the new font
*/
vlc_font_t *NewFont( char *psz_fontfile, int i_index,
......@@ -215,15 +236,25 @@ void FreeFamiliesAndFonts( vlc_family_t *p_family );
void FreeFamilies( void *p_families, void *p_obj );
/**
* Construct the default family list
* Construct the default fallback list
*
* The default fallback list will be searched when all else fails.
* It should contain at least one font for each Unicode script.
*
* No default list is required with FontConfig because FontConfig returns
* comprehensive fallback lists. On Windows a default list is used because
* Uniscribe seems less reliable than FontConfig in this regard.
*
* In some platforms, you might want multiple fonts as default
* On Android, all fallback families reside within the default fallback list,
* which is populated in Android_ParseFamily(), in the XML_READER_ENDELEM section
* of that function, where each family is added to the default list if
* its name has "fallback" in it. So InitDefaultList() is not called on Android.
*
* \param p_filter the freetype module object [IN]
* \param ppsz_default the table default fonts [IN]
* \param i_size the size of the supplied table [IN]
*
* return the default family font
* \return the default fallback list
*/
vlc_family_t *InitDefaultList( filter_t *p_filter, const char *const *ppsz_default,
int i_size );
......
modules/text_renderer/text_layout.c
View file @ d9cc405c
......@@ -29,6 +29,12 @@
* Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
/** \ingroup freetype
* @{
* \file
* Text shaping and layout
*/
#ifdef HAVE_CONFIG_H
# include "config.h"
#endif
......@@ -77,7 +83,7 @@
# define HAVE_FONT_FALLBACK
#endif
/*
/**
* Within a paragraph, run_desc_t represents a run of characters
* having the same font face, size, and style, Unicode script
* and text direction
......@@ -101,7 +107,7 @@ typedef struct run_desc_t
} run_desc_t;
/*
/**
* Glyph bitmaps. Advance and offset are 26.6 values
*/
typedef struct glyph_bitmaps_t
......@@ -120,11 +126,11 @@ typedef struct glyph_bitmaps_t
typedef struct paragraph_t
{
uni_char_t *p_code_points; //Unicode code points
int *pi_glyph_indices; //Glyph index values within the run's font face
uni_char_t *p_code_points; /**< Unicode code points */
int *pi_glyph_indices; /**< Glyph index values within the run's font face */
text_style_t **pp_styles;
FT_Face *pp_faces;
int *pi_run_ids; //The run to which each glyph belongs
FT_Face *pp_faces; /**< Used to determine run boundaries when performing font fallback */
int *pi_run_ids; /**< The run to which each glyph belongs */
glyph_bitmaps_t *p_glyph_bitmaps;
uint8_t *pi_karaoke_bar;
int i_size;
......@@ -460,11 +466,11 @@ static int AddRun( filter_t *p_filter,
return VLC_SUCCESS;
}
/*
#ifdef HAVE_FONT_FALLBACK
/**
* Add a run with font fallback, possibly breaking the run further
* into runs of glyphs that end up having the same font face.
*/
#ifdef HAVE_FONT_FALLBACK
static int AddRunWithFallback( filter_t *p_filter, paragraph_t *p_paragraph,
int i_start_offset, int i_end_offset )
{
......@@ -563,7 +569,7 @@ static bool FaceStyleEquals( filter_t *p_filter, const text_style_t *p_style1,
&& !strcasecmp( psz_fontname1, psz_fontname2 );
}
/*
/**
* Segment a paragraph into runs
*/
static int ItemizeParagraph( filter_t *p_filter, paragraph_t *p_paragraph )
......@@ -616,14 +622,14 @@ static int ItemizeParagraph( filter_t *p_filter, paragraph_t *p_paragraph )
return VLC_SUCCESS;
}
/*
#ifdef HAVE_HARFBUZZ
/**
* Shape an itemized paragraph using HarfBuzz.
* This is where the glyphs of complex scripts get their positions
* (offsets and advance values) and final forms.
* Glyph substitutions of base glyphs and diacritics may take place,
* so the paragraph size may change.
*/
#ifdef HAVE_HARFBUZZ
static int ShapeParagraphHarfBuzz( filter_t *p_filter,
paragraph_t **p_old_paragraph )
{
......@@ -799,13 +805,13 @@ error:
}
#endif
/*
#ifdef HAVE_FRIBIDI
#ifndef HAVE_HARFBUZZ
/**
* Shape a paragraph with FriBidi.
* Shaping with FriBidi is currently limited to mirroring and simple
* Arabic shaping.
*/
#ifdef HAVE_FRIBIDI
#ifndef HAVE_HARFBUZZ
static int ShapeParagraphFriBidi( filter_t *p_filter, paragraph_t *p_paragraph )
{
......@@ -837,7 +843,7 @@ static int ShapeParagraphFriBidi( filter_t *p_filter, paragraph_t *p_paragraph )
return VLC_SUCCESS;
}
/*
/**
* Zero-width invisible characters include Unicode control characters and
* zero-width spaces among other things. If not removed they can show up in the
* text as squares or other glyphs depending on the font. Zero-width spaces are
......@@ -871,7 +877,7 @@ static int RemoveZeroWidthCharacters( paragraph_t *p_paragraph )
return VLC_SUCCESS;
}
/*
/**
* Set advance values of non-spacing marks to zero. Diacritics are
* not positioned correctly but the text is more readable.
* For full shaping HarfBuzz is required.
......@@ -889,7 +895,7 @@ static int ZeroNsmAdvance( paragraph_t *p_paragraph )
#endif
#endif
/*
/**
* Load the glyphs of a paragraph. When shaping with HarfBuzz the glyph indices
* have already been determined at this point, as well as the advance values.
*/
......
modules/text_renderer/text_layout.h
View file @ d9cc405c
......@@ -25,6 +25,12 @@
* Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
/** \ingroup freetype
* @{
* \file
* Text shaping and layout
*/
#include "freetype.h"
typedef struct
......@@ -56,7 +62,20 @@ struct line_desc_t
void FreeLines( line_desc_t *p_lines );
line_desc_t *NewLine( int i_count );
/**
* Layout the text with shaping, bidirectional support, and font fallback if available.
*
* \param p_filter the FreeType module object [IN]
* \param pp_lines the list of line_desc_t's with rendered glyphs [OUT]
* \param p_bbox the bounding box of all the lines [OUT]
* \param pi_max_face_height maximum line height [OUT]
* \param psz_text array of size \p i_len containing character codepoints [IN]
* \param pp_styles array of size \p i_len containing character styles [IN]
* \param pi_k_dates array of size \p i_len containing karaoke timestamps for characters [IN]
* \param i_len length of the arrays \p psz_text, \p pp_styles, and \p pi_k_dates [IN]
* \param b_grid true for grid-mode text [IN]
*/
int LayoutText(filter_t *p_filter, line_desc_t **pp_lines,
FT_BBox *p_bbox, int *pi_max_face_height,
const uni_char_t *psz_text, text_style_t **pp_styles,
uint32_t *pi_k_dates, int i_len, bool );
uint32_t *pi_k_dates, int i_len, bool b_grid );
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment