Grease Pencil 3.0: Final technical design

The data-block

The following code describes the proposed structure of the new grease pencil data-block:

/**
 * A grease pencil drawing is a set of strokes. The data is stored using
 * the CurvesGeometry data structure and the custom attributes within it.
 * It can either own the data or reference it from another GreasePencil
 * data-block.
 * 
 * Note: When a drawing references another data-block, it will always
 *       reference all the drawings in that data-block sequentially.
 */
struct GreasePencilDrawing {
    /**
     * The stroke data for this drawing. Can be nullptr in case the drawing
     * references its data from another data-block.
     */
    CurvesGeometry *geometry;
    
    /**
     * A reference to another GreasePencil data-block. Can be nullptr in
     * case the drawing owns its data.
     * 
     * If the data-block has multiple drawings, this drawing references
     * all of them sequentially.
     */
    GreasePencil *id_reference;
    
    /**
     * Flag. Used to set e.g. the selection status.
     */
    int flag;
    
    ...
};

/**
 * Properties for layers and layer groups.
 */
struct GreasePencilLayerProperties {
    /**
     * Name of the layer/group.
     */
    String name;
    
    /**
     * Flag. Used to set e.g. the selection, visibility, ... status.
     */
    int flag;
    
    /**
     * Color tag.
     */
    uchar color[3];
    
    ...
};

/**
 * A grease pencil layer is a collection of drawings. It maps them
 * to specific scene times on the timeline.
 */
struct GreasePencilLayer {
    /**
     * Settings of this layer.
     */
    GreasePencilLayerProperties settings;
    
    /**
     * This Map maps a scene frame number (key) to an index into
     * GreasePencil->drawings (value). The frame number indicates
     * the first frame the drawing is shown. The end time is implicitly
     * defined by the next greater frame number (key) in the map.
     * If the value mapped to (index) is -1, no drawing is shown
     * at this frame.
     *     
     *    Example:
     * 
     *    {0: 0, 5: 1, 10: -1, 12: 2, 16: -1}
     *
     *    In this example there are three drawings (drawing #0,
     *    drawing #1 and drawing #2). The first drawing starts at frame 0
     *    and ends at frame 5 (excusive). The second drawing starts at
     *    frame 5 and ends at frame 10. Finally, the third drawing starts
     *    at frame 12 and ends at frame 16.
     * 
     *           | | | | | | | | | | |1|1|1|1|1|1|1|
     *    Time:  |0|1|2|3|4|5|6|7|8|9|0|1|2|3|4|5|6|...
     *    Frame: [#0      ][#1      ]    [#2    ]
     * 
     * Note: If a drawing references another data-block, all of the drawings
     *       in that data-block are mapped sequentially to the frames.
     *       If another frame starts, the rest of the mapped drawings
     *       are discarded.
     */
    Map<int, int> frames;
};

/**
 * A grease pencil layer group is a collection of zero or more
 * grease pencil layers.
 * It is also an element of a tree-like structure of other layer groups.
 */
struct GreasePencilLayerGroup {
    /**
     * Settings of this layer group.
     */
    GreasePencilLayerProperties settings;
    
    /**
     * Pointer to the parent group and to zero or more children groups.
     */
    GreasePencilLayerGroup *parent;
    GreasePencilLayerGroup *children;
    int children_size;
    
    /**
     * An array of GreasePencilLayer's.
     */
    GreasePencilLayer *layers;
    int layer_size;
};

/**
 * The grease pencil data-block.
 * 
 * It holds a set of drawings, a tree of layer groups, and a set of layers
 * whithin each layer group.
 * 
 * Note: When this data-block is marked as an assets, the layers 
 *       and layer groups are ignored. The asset treats the drawings
 *       as a sequence of (one or more) frames with no timing.
 */
struct GreasePencil {
    ID id;
    AnimData adt;
    
    /**
     * An array of GreasePencilDrawing's.
     */
    GreasePencilDrawing *drawings;
    int drawings_size;
    
    /**
     * The root layer group (is not shown in the UI).
     * Its parent group is always nullptr.
     */
    GreasePencilLayerGroup *root_group;
    
    /**
     * An array of materials.
     */
    struct Material **mat;
    int mat_size;

    /**
     * Global flag on the data-block.
     */
    int flag;
    
    ...
};

New Object Type

The new data-block will be ID_GP and the old one will be renamed to ID_GD_LEGACY. Also, there will be a new object type OB_GPENCIL and the old one will be renamed to OB_GPENCIL_LEGACY.

Grease Pencil Operators

In order to not have to redefine all the operator types, the operators will have a switch on the object type. If it's OB_GPENCIL_LEGACY they will run the old behavior, and with OB_GPENCIL they will run the new functions.
The idea is that at some point we can deprecate OB_GPENCIL_LEGACY and remove the switch and all the old functions.

Geometry Nodes Integration

As a first step the plan is to read the current frame of a grease pencil object as a single CurvesGeometry and feed this to geometry nodes as the input. All the curves get a layer_id so that they can be seperated into the layers if needed. The output will also be a single CurvesGeometry.

EDIT: Some concerns have been raised with this approach. Will have to be discussed further.

Dependency Graph

In order to allow for more granular copy-on-write updates, there will be a way to tag a single grease pencil drawing for an update. The exact way of how this will be implemented still has to be decided on. Either we add new flags that are specific to grease pencil, or there is a more general solution.