Index: hid_render_comp.html =================================================================== --- hid_render_comp.html (nonexistent) +++ hid_render_comp.html (revision 10746) @@ -0,0 +1,69 @@ + + +

HID: rendering vs. composite layers

+All rendering is driven by the core. The core undrestands the PCB stackup, +layers, layer groups, compositions within the layer groups, extra labels, +layer visibility, etc. The HID is a slave device that takes drawing +instructions and blindly executes them. +

+However, the HID has a chance to alter which layer groups are drawn, using +the set_layer_group hooks return value. +

+ +The rendering is done in bursts. A burst may redraw only a small window +of the screen. Each bursts draws multiple layer groups, in Z-order, from +bottom (furthest from the eye of the user) to up (closest to the eye of +the user). Each layer group is drawn on a transparent sketch canvas. In positive mode, +objects are drawn with multiple colors on each sketch canvas. In negative mode +pixels are erased from the sketch canvas, making the affected pixels transparent again. Drawing +on a layer group (either positively or negatively) should +overwrite pixels on the same layer group. In other words, there's +no transluency between two overlapping objects drawm on the same layer +group. + +

+There is a so called output canvas, which shall be cleared to +the background color upon render_burst / start. The background +color shall be fetched from the config tree (appearance/color/background). +

+The following steps are taken by the core in a burst: +

1. call to the render_burst hook with start +
2. set_layer_group is called for the next layer; depending on the return value, the core will skip to stpe 7. +
3. set_drawing_mode is called with reset +
3. set_drawing_mode is called with positive or negative to set draw or erase +
4. objects are drawn +
5. if there are subsequent composite layers, the core will jump back to 3. +
6. set_drawing_mode is called with flush +
7. if there are further groups, the core jumps back to step 3. +
8. call to the render_burst hook with end +

+When set_drawing_mode / reset is called, the HID needs to +create a new sketch canvas, all pixels initialized to transparent. The +core may switch between positive and negative draw any time. When +set_drawing_mode / flush is called, the current sketch +canvas needs to be blitted onto the output (in a HID-specific way) and +the sketch canvas can be destroyed. The output canvas shall be flushed to +the screen upon render_burst / end. +

+Optional optimization: the most common case is when only positively drawn +layers are used to draw the final output. Drawing on separate sketch canvases and +blitting them onto an output buffer is a waste in this setup. To give HIDs a +chance to avoid the extra copies, set_drawing_mode calls have an +argument called direct. When the direct is set, it is safe +to directly draw on the output canvas, without allocating a sketch canvas. The +core guarantees the followings: +

all calls of set_drawing_mode within drawing a layer group will have the same direct argument +
if direct is set for a layer group, set_drawing_mode will not be called with negative +
only the first N consecutive layer groups can be direct; once a group is drawn with direct unset, all subsequent groups will be drawn with direct unset +

+It is possible that the core would draw the whole board in direct +mode. It is safe to ignore the direct argument and always use the +more expensive, sketch-canvas+blitting method. + + +