mpv/DOCS/tech/osd.txt

draft of new OSD engine:
========================
written by A'rpi
including ideas from mailing list from Jiri Svoboda, Tobias Diedrich,
Artur Zaprzala, Michael Niedermayer, Felix Buenemann, LGB

requirements:
- be able to do partial rendering, within a given bounding box
  useful when parts of the OSD are outside of the image and has to be
  updated only when OSD changes, or even has different colorspace

- text should be rendered in 2-pass way: 1. alpha 2. pixels
  so char's alpha won't overwrite previous char, and may be faster

- OSD elements should be cached - so rendering once into the cache and
  reuse this while it's unchanged

- color support (colorspace could be YA, YUVA, RGB)

- change brightness, saturation, hue of chars ???

- way to disable alphablending, and use black outline (FAST_OSD now)

- respect movie and monitor aspect, so OSD is rendered/scaled correctly
  eg. for SVCD/anamorphic DVD with hardware scaling (now OSD is squashed)

- develop some text-based apps: osdterm, osdzilla etc ;)

Ok. The basic idea of my design is using 'OSD objects', a data structure
in a 1 (or 2?) way linked list.
There would be different object types, sharing type-dependent data in a
union. The basic types: box, text, symbol, progressbar, group.

Group would be a special type, grouping other OSD objects together,
with a common x,y and boundingbox. Useful for grouping symbol+progrbar
or multiline subtitle text.

Each object could have flags, for example:
- visible (set if we should display it)
- color (set if it's YUVA not YA)
- cached (set when there is a cached rendered variant)
- bbox updated (should be set when recalc bbox, reset when change params)
- several flags to control positioning. for example, x;y could be
  absolute coordinates, or percent. flags to set left/center/right alignment...
- start and end timestamp, to automagically set/reset visible flag

OK, my first draft:

typedef struct mp_osd_obj_s {
    struct mp_osd_obj_s* next;
    unsigned char type;
    unsigned char alignment; // 2 bits: x;y percentages, 2 bits: x;y relative to parent; 2 bits: alignment left/right/center
    unsigned short flags;
    int x,y;	// coords
    unsigned char color[4]; // YUVA
    mp_osd_bbox_t bbox; // bounding box
    unsigned int start,duration; // PTS
    union {
	struct {
	    int x1,y1,x2,y2;
	} line;
	struct {
	    int x,y,w,h;
	} rect;
	struct {
	    char* text;
	    mp_font_t* font;
	} text;
	struct {
	    int symbol; // unicode
	    mp_font_t* font;
	} symbol;
	struct {
	    float value;
	    mp_font_t* font;
	} pbar;
	struct {
	    int w,h;
	    unsigned char* image;
	    unsigned int* palette;
	} spu;  // FIXME!
	struct {
	    struct mp_osd_obj_s* children;
	} group;
    } params;
} mp_osd_obj_t;