Continued Outliner Code Refactor #96713

New Issue

Julian Eisel · 2022-03-22T19:34:34+01:00

Julian Eisel commented

2022-03-22 19:34:34 +01:00

The Outliner code is compiled in C++ now, and a big part of the tree building logic has be ported to a new object oriented design. See contents of source/blender/editors/space_outliner/tree/. A lot of existing code can be improved by making use of this new design.

(NOTE) Note for interested GSoC participants --
A GSoC participant wouldn't be expected to get all these tasks done, this is just a general collection of TODOs. It's fine to only pick a few of these tasks, depending on the proposed project duration.

Relevant Design Notes

These basics about the new design are important to understand:

Each Display Mode of the Outliner is represented by an AbstractTreeDisplay sub-class, e.g. TreeDisplayViewLayer, TreeDisplaySequencer, etc.
Elements in the tree are represented by a AbstractTreeElement sub-class, e.g. TreeElementGPencilLayer, TreeElementNLATrack. Not all tree element types are ported to this new design yet.
The legacy (C-style) representation of a tree element is TreeElement. There is one for each visible element in the tree. It should be entirely replaced by the AbstractTreeElement design.

Possible Tasks

Replace most switch-case like logic for tree element types by virtual function calls. E.g. replace the long tree_element_get_icon() with a virtual AbstractTreeElement::getIcon().
Port remaining element types to the new design.
Get rid of TreeElement.directdata. This is type unsafe and confusing (not clear what it contains in many places). Instead the AbstractTreeElement sub-classes should store the exact data needed, and if needed expose those publicly in some way.
Separate element creation from tree insertion, outliner_add_element() currently does both. This causes a few problems, most importantly, all data needed to construct an element has to be passed to the function as a (type unsafe) void *.

E.g.:
{P2843}
Instead the element can be constructed first with all the necessary arguments (possibly using C++ [[ https://devtut.github.io/cpp/perfect-forwarding.html | perfect forwarding ]]) and then added to the tree. E.g.:
{P2844}
These are some ideas, each approach has some pros and cons, but all of them should be better than what we have already.

Add function to change the parent of an element. This is done in a number of places manually, but should be put into a function that guarantees all invariants are preserved (e.g. the TreeElement.parent pointer is set correctly).
Entirely replace the legacy TreeElement with AbstractTreeElement.
Move the tree storage from SpaceOutliner.tree to SpaceOutliner_Runtime.tree (the tree is runtime only UI data). AbstractTreeDisplay.tree may also make sense.
Use a better container for tree storage than ListBase. blender::Vector?
Convert camel case (doSomething()) function names in new C++ code to snake case (do_something()). This is the conventional style for C++ code and how it probably should've been done in the beginning.
Attempt to let tree-displays (AbstractTreeDisplay sub-classes) do all tree building, removing the need for AbstractTreeElement.expand().

Making the tree-display manage all tree building avoids uncertainties of having tree building split across multiple classes, instead the tree-display has full & explicit control over what items are built for the tree. The resulting tree is more predictable, and tree-elements of a certain type can be reused in different display modes without having to share the same expanding code. Tree-elements become less confusing and focus solely on their own display and operations. Sub-tree building that should be shared for multiple items can be moved to helper functions. For example to add the mesh and the materials to an object element in multiple display modes. 
E.g.: {P2845}

Port tree traversals to new functional-style iterators. Add some further sensible iterators (e.g. lookup iterators that can early exit and return some object of custom type). See a4a7af4732, dc6fe73e70.
Document the new Outliner architecture.

Optional Experiments:

Experiment with using the new tree-view for the Outliner. Actually porting the Outliner is a quite complex project on its own.
Experiment with a more functional way of building the hierarchy.

Element Type Porting Status

Overview of element types and their porting status.

`IS_REAL_ID()` returns `true`

Element Type	Ported?	Class Name
`TSE_SOME_ID`	✅	`TreeElementID` and subclasses.
`TSE_NLA_ACTION`	✅	`TreeElementNLAAction`
`TSE_DEFGROUP_BASE`	✅	`TreeElementDeformGroupBase`
`TSE_DEFGROUP`	✅	`TreeElementDeformGroup`
`TSE_BONE`	✅	`TreeElementBone`
`TSE_EBONE`	✅	`TreeElementEditBone`
`TSE_CONSTRAINT_BASE`	✅	`TreeElementConstraintBase`
`TSE_CONSTRAINT`	✅	`TreeElementConstraint`
`TSE_MODIFIER_BASE`	✅	`TreeElementModifierBase`
`TSE_MODIFIER`	✅	`TreeElementModifier`
`TSE_LINKED_OB`	✅	`TreeElementLinkedObject`
`TSE_POSE_BASE`	✅	`TreeElementPoseBase`
`TSE_POSE_CHANNEL`	✅	`TreeElementPoseChannel`
`TSE_ANIM_DATA`	✅	`TreeElementAnimData`
`TSE_R_LAYER_BASE`	✅	`TreeElementViewLayerBase`
`TSE_R_LAYER`	✅	`TreeElementViewLayer`
`TSE_POSEGRP_BASE`	✅	`TreeElementPoseGroupBase`
`TSE_POSEGRP`	✅	`TreeElementPoseGroup`
`TSE_LINKED_PSYS`	✅	`TreeElementParticleSystem`
`TSE_LAYER_COLLECTION`	✅	`TreeElementLayerCollection`
`TSE_SCENE_COLLECTION_BASE`	✅	`TreeElementCollectionBase`
`TSE_VIEW_COLLECTION_BASE`	✅	`TreeElementViewCollectionBase`
`TSE_SCENE_OBJECTS_BASE`	✅	`TreeElementSceneObjectsBase`
`TSE_GPENCIL_EFFECT_BASE`	✅	`TreeElementGPencilEffectBase`
`TSE_GPENCIL_EFFECT`	✅	`TreeElementGPencilEffect`

Other Elements

Element Type	Ported?	Class Name
`TSE_NLA`	✅	`TreeElementNLA`
`TSE_NLA_TRACK`	✅	`TreeElementNLATrack`
`TSE_DRIVER_BASE`	✅	`TreeElementDriverBase`
`TSE_SEQUENCE`	✅	`TreeElementSequence`
`TSE_SEQ_STRIP`	✅	`TreeElementSequenceStrip`
`TSE_SEQUENCE_DUP`	✅	`TreeElementSequenceStripDuplicate`
`TSE_RNA_STRUCT`	✅	`TreeElementRNAStruct`
`TSE_RNA_PROPERTY`	✅	`TreeElementRNAProperty`
`TSE_RNA_ARRAY_ELEM`	✅	`TreeElementRNAArrayElement`
`TSE_ID_BASE`	❌
`TSE_GP_LAYER`	✅	`TreeElementGPencilLayer`
`TSE_LIBRARY_OVERRIDE_BASE`	✅	`TreeElementOverridesBase`
`TSE_LIBRARY_OVERRIDE`	✅	`TreeElementOverridesProperty`
`TSE_LIBRARY_OVERRIDE_OPERATION`	✅	`TreeElementOverridesPropertyOperation`
`TSE_GENERIC_LABEL`	✅	`TreeElementLabel`

The Outliner code is compiled in C++ now, and a big part of the tree building logic has be ported to a new object oriented design. See contents of `source/blender/editors/space_outliner/tree/`. A lot of existing code can be improved by making use of this new design. (NOTE) **Note for interested GSoC participants** -- A GSoC participant wouldn't be expected to get all these tasks done, this is just a general collection of TODOs. It's fine to only pick a few of these tasks, depending on the proposed project duration. ## Relevant Design Notes These basics about the new design are important to understand: - Each [Display Mode ](https://docs.blender.org/manual/en/latest/editors/outliner/interface.html#display-mode) of the Outliner is represented by an `AbstractTreeDisplay` sub-class, e.g. `TreeDisplayViewLayer`, `TreeDisplaySequencer`, etc. - Elements in the tree are represented by a `AbstractTreeElement` sub-class, e.g. `TreeElementGPencilLayer`, `TreeElementNLATrack`. Not all tree element types are ported to this new design yet. - The legacy (C-style) representation of a tree element is `TreeElement`. There is one for each visible element in the tree. It should be entirely replaced by the `AbstractTreeElement` design. ## Possible Tasks - [ ] Replace most switch-case like logic for tree element types by virtual function calls. E.g. replace the long `tree_element_get_icon()` with a `virtual AbstractTreeElement::getIcon()`. - [ ] Port remaining element types to the new design. - [ ] Get rid of `TreeElement.directdata`. This is type unsafe and confusing (not clear what it contains in many places). Instead the `AbstractTreeElement` sub-classes should store the exact data needed, and if needed expose those publicly in some way. - [ ] Separate element creation from tree insertion, `outliner_add_element()` currently does both. This causes a few problems, most importantly, all data needed to construct an element has to be passed to the function as a (type unsafe) `void *`. ``` E.g.: {P2843} Instead the element can be constructed first with all the necessary arguments (possibly using C++ [[ https://devtut.github.io/cpp/perfect-forwarding.html | perfect forwarding ]]) and then added to the tree. E.g.: {P2844} These are some ideas, each approach has some pros and cons, but all of them should be better than what we have already. ``` - [ ] Add function to change the parent of an element. This is done in a number of places manually, but should be put into a function that guarantees all invariants are preserved (e.g. the `TreeElement.parent` pointer is set correctly). - [ ] Entirely replace the legacy `TreeElement` with `AbstractTreeElement`. - [ ] Move the tree storage from `SpaceOutliner.tree` to `SpaceOutliner_Runtime.tree` (the tree is runtime only UI data). `AbstractTreeDisplay.tree` may also make sense. - [ ] Use a better container for tree storage than `ListBase`. `blender::Vector`? - [ ] Convert camel case (`doSomething()`) function names in new C++ code to snake case (`do_something()`). This is the conventional style for C++ code and how it probably should've been done in the beginning. - [ ] Attempt to let tree-displays (`AbstractTreeDisplay` sub-classes) do all tree building, removing the need for `AbstractTreeElement.expand()`. ``` Making the tree-display manage all tree building avoids uncertainties of having tree building split across multiple classes, instead the tree-display has full & explicit control over what items are built for the tree. The resulting tree is more predictable, and tree-elements of a certain type can be reused in different display modes without having to share the same expanding code. Tree-elements become less confusing and focus solely on their own display and operations. Sub-tree building that should be shared for multiple items can be moved to helper functions. For example to add the mesh and the materials to an object element in multiple display modes. E.g.: {P2845} ``` - [ ] Port tree traversals to new functional-style iterators. Add some further sensible iterators (e.g. lookup iterators that can early exit and return some object of custom type). See a4a7af4732, dc6fe73e70. - [ ] Document the new Outliner architecture. ---- ## Optional Experiments: - [ ] Experiment with using the new [tree-view ](https://wiki.blender.org/wiki/Source/Interface/Views/Tree_Views) for the Outliner. Actually porting the Outliner is a quite complex project on its own. - [ ] Experiment with a more functional way of building the hierarchy. --- ## Element Type Porting Status Overview of element types and their porting status. ### `IS_REAL_ID()` returns `true` | Element Type | Ported? | Class Name | | --- | --- | --- | | `TSE_SOME_ID` | ✅ | `TreeElementID` and subclasses. | | `TSE_NLA_ACTION` | ✅ | `TreeElementNLAAction` | | `TSE_DEFGROUP_BASE` | ✅ | `TreeElementDeformGroupBase` | | `TSE_DEFGROUP` | ✅ | `TreeElementDeformGroup` | | `TSE_BONE` | ✅ | `TreeElementBone` | | `TSE_EBONE` | ✅ | `TreeElementEditBone` | | `TSE_CONSTRAINT_BASE` | ✅ | `TreeElementConstraintBase` | | `TSE_CONSTRAINT` | ✅ | `TreeElementConstraint` | | `TSE_MODIFIER_BASE` | ✅ | `TreeElementModifierBase` | | `TSE_MODIFIER` | ✅ | `TreeElementModifier` | | `TSE_LINKED_OB` | ✅ | `TreeElementLinkedObject` | | `TSE_POSE_BASE` | ✅ | `TreeElementPoseBase` | | `TSE_POSE_CHANNEL` | ✅ | `TreeElementPoseChannel` | | `TSE_ANIM_DATA` | ✅ | `TreeElementAnimData` | | `TSE_R_LAYER_BASE` | ✅ | `TreeElementViewLayerBase` | | `TSE_R_LAYER` | ✅ | `TreeElementViewLayer` | | `TSE_POSEGRP_BASE` | ✅ | `TreeElementPoseGroupBase` | | `TSE_POSEGRP` | ✅ | `TreeElementPoseGroup` | `TSE_LINKED_PSYS` | ✅ | `TreeElementParticleSystem` | | `TSE_LAYER_COLLECTION` | ✅ | `TreeElementLayerCollection` | | `TSE_SCENE_COLLECTION_BASE` | ✅ | `TreeElementCollectionBase` | | `TSE_VIEW_COLLECTION_BASE` | ✅ | `TreeElementViewCollectionBase` | | `TSE_SCENE_OBJECTS_BASE` | ✅ | `TreeElementSceneObjectsBase` | | `TSE_GPENCIL_EFFECT_BASE` | ✅ | `TreeElementGPencilEffectBase` | | `TSE_GPENCIL_EFFECT` | ✅ | `TreeElementGPencilEffect` | ### Other Elements | Element Type | Ported? | Class Name | | --- | --- | --- | | `TSE_NLA` | ✅ | `TreeElementNLA` | | `TSE_NLA_TRACK` | ✅ | `TreeElementNLATrack` | | `TSE_DRIVER_BASE` | ✅ | `TreeElementDriverBase` | | `TSE_SEQUENCE` | ✅ | `TreeElementSequence` | | `TSE_SEQ_STRIP` | ✅ | `TreeElementSequenceStrip` | | `TSE_SEQUENCE_DUP` | ✅ | `TreeElementSequenceStripDuplicate` | | `TSE_RNA_STRUCT` | ✅ | `TreeElementRNAStruct` | | `TSE_RNA_PROPERTY` | ✅ | `TreeElementRNAProperty` | | `TSE_RNA_ARRAY_ELEM` | ✅ | `TreeElementRNAArrayElement` | | `TSE_ID_BASE` | ❌ | | | `TSE_GP_LAYER` | ✅ | `TreeElementGPencilLayer` | | `TSE_LIBRARY_OVERRIDE_BASE` | ✅ | `TreeElementOverridesBase` | | `TSE_LIBRARY_OVERRIDE` | ✅ | `TreeElementOverridesProperty` | | `TSE_LIBRARY_OVERRIDE_OPERATION` | ✅ |`TreeElementOverridesPropertyOperation` | `TSE_GENERIC_LABEL` | ✅ | `TreeElementLabel` |

Julian Eisel commented

2022-03-22 19:34:34 +01:00

Changed status from 'Needs Triage' to: 'Confirmed'

Julian Eisel commented

2022-03-22 19:34:34 +01:00

Added subscriber: @JulianEisel

Julian Eisel changed title from ~~Outliner Code Refactor~~ to Continued Outliner Code Refactor

2022-03-22 20:14:09 +01:00

Chirag Mathur commented

2022-04-02 23:01:45 +02:00

Added subscriber: @Chirag-Mathur

Jian Wang commented

2022-04-06 15:47:11 +02:00

Added subscriber: @Jian-Wang

Priyansh Bhatnagar commented

2023-02-02 09:59:33 +01:00

Added subscriber: @priyanshx19

Philipp Oeser removed the

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Continued Outliner Code Refactor #96713

Relevant Design Notes

Possible Tasks

Optional Experiments:

Element Type Porting Status

IS_REAL_ID() returns true

Other Elements

`IS_REAL_ID()` returns `true`