Brush Properties #100137

New Issue

Joseph Eagar · 2022-08-02T12:36:06+02:00

Joseph Eagar commented

2022-08-02 12:36:06 +02:00

Blender needs a more generic way to store brush properties. This is needed to simplify code and to support the more advanced brush systems found in other graphics software. Krita's brush editor, for example, lets users add input dynamics to each brush property (for example, users can map pen pressure to size, tilt to squish, etc) and with custom input curves. A generic property system is also needed for the planned node-based brush engine.

A proof of concept has been implemented in temp-sculpt-brush-channel. This task documents how it works.

Brush Properties

NOTE: the word "channel" shall be renamed to "property."

A brush channel (BrushChannel) is a float, int, color, curve, enum, bitmask, etc. It can be driven by input mappings (e.g. pen pressure) with
custom input curves. Channels are stored in channel sets (BrushChannelSet) and are looked up by name.

Brush channels do not store property values themselves but instead wrap RNA properties.

UX Design

Channel Dynamics

Input dynamics works in a similar way to Krita. Here is the rather bad UX I came up with in sculpt-dev:

Property Lists

Brush properties will be assigned to three different lists: Workspace settings, the menu header and right-click context menu.

This will happens in a special Brush Editor Mode:

The icons on the left control property visibility.

Property Categories

Brush properties can be grouped into categories (which are currently hard-coded):

Technical Design

Property Types

Integers
Floats
2/3/4 dimension vectors.
Curves (e.g. falloff curve).
Booleans.
Bitmasks.
Enums.

Channel Inheritance

Unified brush properties are stored in ToolSettings.unified_channels. Properties are flagged in unified mode with BRUSH_CHANNEL_FORCE_INHERIT (possibly to be renamed to BRUSH_CHANNEL_UNIFIED).

Note that each input mapping inside of a brush channel can also be set to unified independently, this is useful if e.g. you want a brush to have it's own radius but still use the scene pen pressure input mapping.

In addition bitmasks can be set to OR with the parent (scene defaults) value. This is needed for the automasking settings.

Compile-time Name Checking

Brush settings identifiers are simple C strings. The C API is designed to catch typos at compiler time. It does this by generating a bunch of global string variables like so:

const char *BRUSH_builtin_strength = "strength";
const char *BRUSH_builtin_radius = "radius";

Important API functions are then wrapped in a series of BRUSHSET_XXX macros (todo: find better preset than BRUSHSET_). So to lookup a channel you might do:

BrushChannel *ch = BRUSHSET_LOOKUP(brush->channels, radius);

The C++ API works a bit differently; BrushChannelSetIF has one accessor method per brush channel.
I tried to get compile-time string validation of channel names to work but failed (at least in C++17),
so I ended up using macros to create accessor methods instead.

No ID pointers

Aside from textures (the implementation of which incomplete), no ID pointers are allowed in BrushChannels. This is so we can link in brushes from an asset file as library overrides without weird edge cases or performance degradations on file IO.

This decision may be revisited later.

Property Storage

The existing RNA properties are reused for local brush properties. Unified properties are stored as IDProperty copes of the Brush RNA properties in ToolSettings.unified_properties.

C++

NOTE: not yet ported to temp-sculpt-brush-channel.

The current API implementation in sculpt-dev is mostly implemented in C, which has led to some code messiness. The process of switching the implementation to C++ has begun; the existing C API will be (mostly) kept, but it will wrap a C++ one.

The C++ API works by wrapping the C DNA structs, so e.g. BrushChannel has a BrushChannelIF C++ wrapper class ("IF" just stances for "Interface"; suggestions for better names are welcome). The C++ API is quite a bit cleaner (and clearer), and uses templates:

BrushChannelIF<float> radius = channelset.radius();
BrushChannelIF<bool> use_frontface = channelset.use_frontface();

//get the channel values:
float radius_value = radius.value();
bool frontface_value = use_frontface.value();

//can also assign
radius.value() = 5.0f;
use_frontface.value() = true;

Core data structures:

Blender needs a more generic way to store brush properties. This is needed to simplify code and to support the more advanced brush systems found in other graphics software. Krita's brush editor, for example, lets users add input dynamics to each brush property (for example, users can map pen pressure to size, tilt to squish, etc) and with custom input curves. A generic property system is also needed for the planned node-based brush engine. A proof of concept has been implemented in temp-sculpt-brush-channel. This task documents how it works. # Brush Properties NOTE: the word "channel" shall be renamed to "property." A brush channel (`BrushChannel`) is a float, int, color, curve, enum, bitmask, etc. It can be driven by input mappings (e.g. pen pressure) with custom input curves. Channels are stored in channel sets (`BrushChannelSet`) and are looked up by name. Brush channels do not store property values themselves but instead wrap RNA properties. ## UX Design ### Channel Dynamics Input dynamics works in a similar way to Krita. Here is the rather bad UX I came up with in sculpt-dev: ![image.png](https://archive.blender.org/developer/F13384273/image.png) ### Property Lists Brush properties will be assigned to three different lists: Workspace settings, the menu header and right-click context menu. This will happens in a special Brush Editor Mode: ![image.png](https://archive.blender.org/developer/F13331193/image.png) ![image.png](https://archive.blender.org/developer/F13331195/image.png) The icons on the left control property visibility. ### Property Categories Brush properties can be grouped into categories (which are currently hard-coded): ![image.png](https://archive.blender.org/developer/F13331201/image.png) ## Technical Design ### Property Types - Integers - Floats - 2/3/4 dimension vectors. - Curves (e.g. falloff curve). - Booleans. - Bitmasks. - Enums. ### Channel Inheritance Unified brush properties are stored in ToolSettings.unified_channels. Properties are flagged in unified mode with BRUSH_CHANNEL_FORCE_INHERIT (possibly to be renamed to BRUSH_CHANNEL_UNIFIED). Note that each input mapping inside of a brush channel can also be set to unified independently, this is useful if e.g. you want a brush to have it's own radius but still use the scene pen pressure input mapping. In addition bitmasks can be set to OR with the parent (scene defaults) value. This is needed for the automasking settings. ### Compile-time Name Checking Brush settings identifiers are simple C strings. The C API is designed to catch typos at compiler time. It does this by generating a bunch of global string variables like so: ``` const char *BRUSH_builtin_strength = "strength"; const char *BRUSH_builtin_radius = "radius"; ``` Important API functions are then wrapped in a series of `BRUSHSET_XXX` macros (todo: find better preset than `BRUSHSET_`). So to lookup a channel you might do: ``` BrushChannel *ch = BRUSHSET_LOOKUP(brush->channels, radius); ``` The C++ API works a bit differently; `BrushChannelSetIF` has one accessor method per brush channel. I tried to get compile-time string validation of channel names to work but failed (at least in C++17), so I ended up using macros to create accessor methods instead. ### No ID pointers Aside from textures (the implementation of which incomplete), no ID pointers are allowed in BrushChannels. This is so we can link in brushes from an asset file as library overrides without weird edge cases or performance degradations on file IO. This decision may be revisited later. **Property Storage** The existing RNA properties are reused for local brush properties. Unified properties are stored as `IDProperty` copes of the `Brush` RNA properties in `ToolSettings.unified_properties`. ### C++ NOTE: not yet ported to `temp-sculpt-brush-channel`. The current API implementation in sculpt-dev is mostly implemented in C, which has led to some code messiness. The process of switching the implementation to C++ has begun; the existing C API will be (mostly) kept, but it will wrap a C++ one. The C++ API works by wrapping the C DNA structs, so e.g. `BrushChannel` has a `BrushChannelIF` C++ wrapper class ("IF" just stances for "Interface"; suggestions for better names are welcome). The C++ API is quite a bit cleaner (and clearer), and uses templates: ``` BrushChannelIF<float> radius = channelset.radius(); BrushChannelIF<bool> use_frontface = channelset.use_frontface(); //get the channel values: float radius_value = radius.value(); bool frontface_value = use_frontface.value(); //can also assign radius.value() = 5.0f; use_frontface.value() = true; ``` ## Core data structures: - [DNA_brush_channel_types.h ](https://git.blender.org/gitweb/gitweb.cgi/blender.git/blob/refs/heads/temp-sculpt-brush-channel:/source/blender/makesdna/DNA_sculpt_brush_types.h) - [BKE_brush_channel.h ](https://git.blender.org/gitweb/gitweb.cgi/blender.git/blob/refs/heads/temp-sculpt-brush-channel:/source/blender/blenkernel/BKE_brush_engine.h)

Joseph Eagar commented

2022-08-02 12:36:06 +02:00

Added subscriber: @JosephEagar

Tiago Cruz commented

2022-08-02 12:59:13 +02:00

Added subscriber: @tiagoffcruz

TheRedWaxPolice commented

2022-08-02 20:57:40 +02:00

Added subscriber: @TheRedWaxPolice

Paul Larson commented

2022-08-04 19:36:15 +02:00

Added subscriber: @GeorgiaPacific

Iliya Katushenock commented

2022-08-14 23:37:53 +02:00

Added subscriber: @mod_moder

Iliya Katushenock commented

2022-08-14 23:37:53 +02:00

If brushes become more modular in general, that sounds very good.
I've had a lot of problems trying to use my graphics tablet so I don't have much experience with it, but I'm not sure how I could do such complex adjustments like in sai or crit.

About compile-time name checking: I'm not sure why this is needed? Are you getting a reference to a build-time structure, or are you reporting a compile-time type for builder?
If data can be queried at runtime, then attributes have an example of a lookup with validation at runtime (like inline GAttributeReader lookup).
Or maybe it's related to code generation, then maybe this part is more deeply hidden and if, let's say, I make a new brush with this system, then I will not know about such a deep part.

If brushes become more modular in general, that sounds very good. I've had a lot of problems trying to use my graphics tablet so I don't have much experience with it, but I'm not sure how I could do such complex adjustments like in sai or crit. --- About compile-time name checking: I'm not sure why this is needed? Are you getting a reference to a build-time structure, or are you reporting a compile-time type for builder? If data can be queried at runtime, then attributes have an example of a lookup with validation at runtime (like `inline GAttributeReader lookup`). Or maybe it's related to code generation, then maybe this part is more deeply hidden and if, let's say, I make a new brush with this system, then I will not know about such a deep part.

Joseph Eagar commented

2022-08-16 02:23:58 +02:00

Compile-time name checking is to ensure you don't accidentally ask for the sze attribute instead of size.

Compile-time name checking is to ensure you don't accidentally ask for the `sze` attribute instead of `size`.

Iliya Katushenock commented

2022-08-16 03:24:13 +02:00

Yes, and more generally when you call BLI_Assert, since strings are not variable names and may depend on how the program runtime
Although again, it depends on your plans for using it, I only see a comparison with accessing named data

In general, the error is there, which is not so difficult to notice, on the other hand, string checking on build limits scaling and increases build time (?)

Yes, and more generally when you call BLI_Assert, since strings are not variable names and may depend on how the program runtime Although again, it depends on your plans for using it, I only see a comparison with accessing named data In general, the error is there, which is not so difficult to notice, on the other hand, string checking on build limits scaling and increases build time (?)

Joseph Eagar commented

2022-08-17 19:20:52 +02:00

The name checking is done in C so there's no build penalty.

Aaron Carlisle commented

2022-10-23 03:39:21 +02:00

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

Nika Kutsniashvili commented

2022-12-22 18:10:35 +01:00

Added subscriber: @Nika-Kutsniashvili

Julien Kaspar added this to the Sculpt, Paint & Texture project 2023-02-08 10:20:48 +01:00

Philipp Oeser removed the

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Brush Properties #100137

Brush Properties

UX Design

Channel Dynamics

Property Lists

Property Categories

Technical Design

Property Types

Channel Inheritance

Compile-time Name Checking

No ID pointers

C++

Core data structures: