libass分析6-源码分析-ASS_Renderer结构体分析，ass文件数据是如何存放的

Author: wencoo
Blog：https://wencoo.blog.csdn.net/
Date: 01/03/2024
Email: jianwen056@aliyun.com
Wechat：wencoo824
QQ：1419440391
Details:

文章目录

目录
- 正文或背景
ASS_Renderer结构体原型
- ASS_FontSelector结构体原型
- - ASS_FontInfo结构体原型
  - ASS_FontProvider结构体原型
- ASS_Settings结构体原型
- - ASS_Hinting结构体原型
  - ASS_ShapingLevel结构体原型
- RenderContext结构体原型
- - ASS_Shaper结构体原型
  - RasterizerData结构体原型
  - ASS_Font结构体原型
- TextInfo结构体原型
- CacheStore结构体原型
- ASS_Style结构体原型
总结
- 参考
技术交流

ASS_Renderer结构体原型

struct ass_renderer {
    ASS_Library *library;       //ass库指针
    FT_Library ftlibrary;       //字体库
    ASS_FontSelector *fontselect;   //字体选择结构体
    size_t num_emfonts;             //字体编号？？
    ASS_Settings settings;          //ass设置类
    int render_id;                  //渲染样式索引 id

    ASS_Image *images_root;     // rendering result is stored here  渲染结果存储在这里
    ASS_Image *prev_images_root;    //上一帧的渲染结果存储

    EventImages *eimg;          // temporary buffer for sorting rendered events  用于排序呈现事件的临时缓冲区
    int eimg_size;              // allocated buffer size  分配的缓冲区大小

    // frame-global data
    int width, height;          // screen dimensions (the whole frame from ass_set_frame_size)  屏幕尺寸(来自ass_set_frame_size的整个帧)
    int frame_content_height;   // content frame height ( = screen height - API margins )       内容框架高度(=屏幕高度- API边距)
    int frame_content_width;    // content frame width ( = screen width - API margins )         内容框架宽度(=屏幕宽度- API边距)
    double fit_height;          // content frame height without zoom & pan (fit to screen & letterboxed)    不缩放和平移的内容框架高度(适合屏幕和信箱)
    double fit_width;           // content frame width without zoom & pan (fit to screen & letterboxed)     没有缩放和平移的内容框架宽度(适合屏幕和信箱)
    ASS_Track *track;
    long long time;             // frame's timestamp, ms   帧的时间戳，ms
    double par_scale_x;         // x scale applied to all glyphs to preserve text aspect ratio   X比例适用于所有字形，以保持文本长宽比

    RenderContext state;        // reader的状态机？
    TextInfo text_info;
    CacheStore cache;

    const BitmapEngine *engine;

    ASS_Style user_override_style;
};

先来看看ASS_FontSelector结构体存储了那种信息

ASS_FontSelector结构体原型

struct font_selector {
    ASS_Library *library;
    FT_Library ftlibrary;

    // uid counter  uid计数器
    int uid;

    // fallbacks  两个回调函数
    char *family_default;       //字体族函数回调
    char *path_default;         //路径回到
    int index_default;

    // font database
    int n_font;                 //???
    int alloc_font;             //???
    ASS_FontInfo *font_infos;   //字体信息

    ASS_FontProvider *default_provider;     //默认程序
    ASS_FontProvider *embedded_provider;    //嵌入程序
};

先依照顺序来看ASS_FontInfo结构

ASS_FontInfo结构体原型

// internal font database element  内部字体数据库元素
// all strings are utf-8        所有字符串都是utf-8
struct font_info {
    int uid;            // unique font face id  唯一的字体id

    char **families;    // family name  字体族名称列表
    char **fullnames;   // list of localized fullnames (e.g. Arial Bold Italic) 本地化的全名列表(例如Arial Bold Italic)
    int n_family;       //列表索引
    int n_fullname;     //列表索引

    int slant;          // 倾斜角度？
    int weight;         // TrueType scale, 100-900   TrueType量表，100-900
    int width;

    // how to access this face  如何访问这张脸？
    char *path;            // absolute path  绝对路径
    int index;             // font index inside font collections   字体集合内的字体索引

    char *postscript_name; // can be used as an alternative to index to  可以用作索引的替代品吗
                           // identify a font inside a collection    识别集合中的字体

    char *extended_family;  //扩展字体族

    // font source  字体来源???
    ASS_FontProvider *provider;

    // private data for callbacks   回调的私有数据
    void *priv;
};

这里还有一个ASS_FontProvider的结构，也来看一下吧

ASS_FontProvider结构体原型

struct font_provider {
    ASS_FontSelector *parent;       //字体选择结构
    ASS_FontProviderFuncs funcs;    //回调函数的结构体集合
    void *priv;                     //回调函数的私有数据
};

ASS_FontProviderFuncs是一个回调函数的结构体集合，里面有各种回调函数的结构，使用的时候，只需要指定具体的函数即可。看一下ASS_FontProviderFuncs的结构体原型

typedef struct font_provider_funcs {
    GetDataFunc         get_data;               /* optional/mandatory 这个意思应该是必须要实现的*/
    CheckPostscriptFunc check_postscript;       /* mandatory */
    CheckGlyphFunc      check_glyph;            /* mandatory */
    DestroyFontFunc     destroy_font;           /* optional */
    DestroyProviderFunc destroy_provider;       /* optional */
    MatchFontsFunc      match_fonts;            /* optional */
    SubstituteFontFunc  get_substitutions;      /* optional */
    GetFallbackFunc     get_fallback;           /* optional */
    GetFontIndex        get_font_index;         /* optional */
} ASS_FontProviderFuncs;

具体每个回调有哪些参数，我们先不去看，到了后面用的时候再细细研究。

ASS_Settings结构体原型

typedef struct {
    int frame_width;            //帧宽
    int frame_height;           //帧高
    int storage_width;          // video width before any rescaling     任何重新缩放之前的视频宽度
    int storage_height;         // video height before any rescaling    任何重新缩放之前的视频高度
    double font_size_coeff;     // font size multiplier  字体倍增器
    double line_spacing;        // additional line spacing (in frame pixels)  额外的行间距(以帧像素为单位)
    double line_position;       // vertical position for subtitles, 0-100 (0 = no change)   字幕的垂直位置，0-100(0 =不变)  
    int top_margin;             // height of top margin. Video frame is shifted down by top_margin.  上边距的高度。视频帧通过top_margin向下移动。
    int bottom_margin;          // height of bottom margin. (frame_height - top_margin - bottom_margin) is original video height.  底边距的高度。(frame_height - top_margin - bottom_margin)为原始视频高度。
    int left_margin;
    int right_margin;
    int use_margins;            // 0 - place all subtitles inside original frame    0 -将所有字幕放在原始帧内
    // 1 - place subtitles (incl. toptitles) in full display frame incl. margins    1 -将副标题(包括标题)放在完整的显示框中，包括页边距
    double par;                 // user defined pixel aspect ratio (0 = unset)      用户自定义像素宽高比(0 =未设置)
    ASS_Hinting hinting;        //ass 微调？
    ASS_ShapingLevel shaper;    //成形等级？？？
    int selective_style_overrides; // ASS_OVERRIDE_* flags

    char *default_font;					//默认字体
    char *default_family;				//默认字体族
} ASS_Settings;

ASS_Hinting结构体原型

/*
 * Hinting type. (see ass_set_hinting below) 提示类型。(参见下面的ass_set_hint)
 *
 * Setting hinting to anything but ASS_HINTING_NONE will put libass in a mode  将提示设置为ASS_HINTING_NONE以外的任何值将使libass进入模式
 * that reduces compatibility with vsfilter and many ASS scripts. The main  这会降低与vsfilter和许多ASS脚本的兼容性。
 * problem is that hinting conflicts with smooth scaling, which precludes  这个主要问题是暗示与平滑缩放相冲突，这就排除了动画和精确定位
 * animations and precise positioning.
 *
 * In other words, enabling hinting might break some scripts severely.  换句话说，启用提示可能会严重破坏某些脚本。
 *
 * FreeType's native hinter is still buggy sometimes and it is recommended
 * to use the light autohinter, ASS_HINTING_LIGHT, instead.  For best
 * compatibility with problematic fonts, disable hinting.
 FreeType的本地提示有时仍然有bug，建议使用它使用轻自动提示，ASS_HINTING_LIGHT，而不是。最佳兼容有问题的字体，禁用提示。
 */
typedef enum {
    ASS_HINTING_NONE = 0,
    ASS_HINTING_LIGHT,
    ASS_HINTING_NORMAL,
    ASS_HINTING_NATIVE
} ASS_Hinting;

ASS_ShapingLevel结构体原型

/**
 * \brief Text shaping levels.  文本塑形级别。
 *
 * SIMPLE is a fast, font-agnostic shaper that can do only substitutions.   SIMPLE是一个快速的、与字体无关的整形器，它只能进行替换。
 * COMPLEX is a slower shaper using OpenType for substitutions and positioning.  COMPLEX是使用OpenType进行替换和定位的较慢的整形器。
 *
 * libass uses the best shaper available by default.  Libass默认使用最好的形状器。
 */
typedef enum {
    ASS_SHAPING_SIMPLE = 0,
    ASS_SHAPING_COMPLEX
} ASS_ShapingLevel;

RenderContext结构体原型

// Renderer state.
// Values like current font face, color, screen position, clipping and so on are stored here.
// 像当前字体、颜色、屏幕位置、剪辑等值都存储在这里。
struct render_context {
    ASS_Renderer *renderer;     //渲染器指针
    TextInfo *text_info;        //字形结构信息
    ASS_Shaper *shaper;         //ass字形，第三方库接入处理
    RasterizerData rasterizer;  //光栅化程序数据

    ASS_Event *event;           //事件参数
    ASS_Style *style;           //风格参数

    ASS_Font *font;             //字体库的指针存储结构
    double font_size;           //字体大小
    int parsed_tags;            //解析标识
    int flags;                  // decoration flags (underline/strike-through) 装饰旗帜(下划线/划线)

    int alignment;              // alignment overrides go here; if zero, style value will be used  对齐覆盖到这里;如果为零，则使用样式值
    int justify;                // justify instructions  证明的说明？？？这个翻译看不懂
    double frx, fry, frz;       // 一个什么数据的x,y,z值
    double fax, fay;            // text shearing  文本剪切
    double pos_x, pos_y;        // position     位置坐标
    double org_x, org_y;        // origin       原点坐标
    double scale_x, scale_y;    // 缩放的x，y坐标
    double hspacing;            // distance between letters, in pixels  字母之间的距离，以像素为单位
    double border_x;            // outline width  轮廓宽度
    double border_y;
    enum {
        EVENT_NORMAL = 0,       // "normal" top-, sub- or mid- title  “普通”标题，副标题或中标题
        EVENT_POSITIONED = 1,   // happens after \pos or \move, margins are ignored  发生在\pos或\move之后，忽略边距
        EVENT_HSCROLL = 2,      // "Banner" transition effect, text_width is unlimited  “Banner”的过渡效果，text_width是无限制的
        EVENT_VSCROLL = 4       // "Scroll up", "Scroll down" transition effects  “向上滚动”，“向下滚动”的过渡效果
    } evt_type;
    int border_style;           //边框风格
    uint32_t c[4];              // colors(Primary, Secondary, so on) in RGBA
    int clip_x0, clip_y0, clip_x1, clip_y1;     //裁剪坐标
    char have_origin;           // origin is explicitly defined; if 0, get_base_point() is used   明确定义了原点;如果为0，则使用get_base_point()
    char clip_mode;             // 1 = iclip    裁剪模式
    char detect_collisions;     //碰撞检测
    char be;                    // blur edges  边缘模糊
    int fade;                   // alpha from \fad  和fad效果值一样，从fad的设置来
    double blur;                // gaussian blur    高斯模糊
    double shadow_x;            //窗口x
    double shadow_y;            //窗口y
    double pbo;                 // drawing baseline offset  绘制基线偏移量
    ASS_StringView clip_drawing_text;  // 裁剪绘制文本？？？

    // used to store RenderContext.style when doing selective style overrides   用于存储RenderContext。在进行选择性样式重写时
    ASS_Style override_style_temp_storage;

    int drawing_scale;          // currently reading: regular text if 0, drawing otherwise  当前读取:如果为0，则为常规文本，否则为绘图
    int clip_drawing_scale;     // 裁剪绘制缩放？？？
    int clip_drawing_mode;      // 0 = regular clip, 1 = inverse clip  0 =正夹，1 =逆夹

    Effect effect_type;         //特效类型
    int32_t effect_timing;      //特效的生效时间
    int32_t effect_skip_timing; //特效跳过时间
    bool reset_effect;          //重置特效标志

    enum {
        SCROLL_LR,              // left-to-right
        SCROLL_RL,
        SCROLL_TB,              // top-to-bottom
        SCROLL_BT
    } scroll_direction;         // for EVENT_HSCROLL, EVENT_VSCROLL  滚动方向的枚举
    double scroll_shift;        //循环滚动
    int scroll_y0, scroll_y1;   //滚动的两个坐标？？

    // face properties    字体属性相关？
    ASS_StringView family;      //
    unsigned bold;              //粗体
    unsigned italic;            //斜体
    int treat_family_as_pattern;
    int wrap_style;             //环绕风格？
    int font_encoding;          //字体编码

    // combination of ASS_OVERRIDE_BIT_* flags that apply right now  现在应用的ASS_OVERRIDE_BIT_*标志的组合
    unsigned overrides;
    // whether to apply font_scale  是否应用font_scale
    int apply_font_scale;
    // whether this is assumed to be explicitly positioned  是否假定它被显式定位
    int explicit;

    double screen_scale_x;      //屏幕缩放x
    double screen_scale_y;      //屏幕缩放y
    double border_scale_x;      //边框缩放x
    double border_scale_y;
    double blur_scale_x;        //模糊缩放x
    double blur_scale_y;
};

ASS_Shaper结构体原型

struct ass_shaper {
    ASS_ShapingLevel shaping_level;

    // FriBidi log2vis
    int n_glyphs, n_pars;
    FriBidiChar *event_text; // just a reference, owned by text_info  只是一个引用，属于text_info
    FriBidiCharType *ctypes;
    FriBidiLevel *emblevels;
    FriBidiStrIndex *cmap;
    FriBidiParType *pbase_dir;
    FriBidiParType base_direction;

    // OpenType features   特色功能
    int n_features;
    hb_feature_t *features;
    hb_language_t language;

    // Glyph metrics cache, to speed up shaping   字形指标缓存，以加快塑造
    Cache *metrics_cache;

#ifdef USE_FRIBIDI_EX_API
    FriBidiBracketType *btypes;
    bool bidi_brackets;
#endif

    char whole_text_layout;
};

该结构体使用了fribidi库，fribidi库主要用来转换不同语系中存在的文本方向问题，例如右向左的文本，翻转后为左向右顺序的文本。

RasterizerData结构体原型

typedef struct {
    int outline_error;  // acceptable error (in 1/64 pixel units) 可接受误差(1/64像素单位)

    // usable after rasterizer_set_outline  在rasterizer_set_outline之后可用
    ASS_Rect bbox;

    // internal buffers   内部缓冲区
    struct segment *linebuf[2];
    size_t size[2], capacity[2];
    size_t n_first;

    uint8_t *tile;
} RasterizerData;

ASS_Font结构体原型

struct ass_font {
    ASS_FontDesc desc;                      //一个解码的结构体
    ASS_Library *library;
    FT_Library ftlibrary;                   //ft库的结构体
    int faces_uid[ASS_FONT_MAX_FACES];
    FT_Face faces[ASS_FONT_MAX_FACES];      //
    ASS_ShaperFontData *shaper_priv;        //字形数据
    int n_faces;
    double size;
};

TextInfo结构体原型

typedef struct {
    GlyphInfo *glyphs;              //字形结构指针
    FriBidiChar *event_text;        //文字事件
    char *breaks;
    int length;                     //长度
    LineInfo *lines;                //行信息
    int n_lines;                    //行索引
    CombinedBitmapInfo *combined_bitmaps;   //组合位图？？？
    unsigned n_bitmaps;                     //位图索引
    double height;
    int border_top;             //边框顶
    int border_bottom;          //边框底
    int border_x;               //边框x位置
    int max_glyphs;             //最大字形数
    int max_lines;              //最大行数
    unsigned max_bitmaps;       //最大位图数
} TextInfo;

CacheStore结构体原型

缓存存储结构，Cache结构体是一个链表结构

typedef struct {
    Cache *font_cache;              //字体缓存
    Cache *outline_cache;           //轮廓缓存
    Cache *bitmap_cache;            //位图缓存
    Cache *composite_cache;         //合成图缓存
    Cache *metrics_cache;           //度量缓存？
    size_t glyph_max;               //字形最大值
    size_t bitmap_max_size;         //位图最大值
    size_t composite_max_size;      //合成最大值
} CacheStore;

ASS_Style结构体原型

已在别处分析过了，这里就不贴了

总结

我们现在整体细致的分析了ass_renderer结构的数据内容，发现里面结构体很多，并且不同的结构体里面有相同的字段，目前还不清楚两个不同结构体中相同字段是否一样，有没有什么不同，下一篇文章继续慢慢分析。

由于笔者的水平有限，加之编写的同时还要参与开发工作，文中难免会出现一些错误或者不准确的地方，恳请读者批评指正。如果读者有任何宝贵意见，可以加我微信 wencoo824。QQ：1419440391。