brush.h File Reference

Dab-level brush rasterization API for drawlayer. More...

#include <glib.h>
#include <stdint.h>

Include dependency graph for brush.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	dt_drawlayer_brush_dab_t
	Fully resolved input dab descriptor. More...
struct	dt_drawlayer_brush_batch_t
	A run of dabs that share everything the batch composite needs to be a single step. More...

Macros
#define	OUTER_LOOP   1

Typedefs
typedef struct dt_drawlayer_cache_patch_t	dt_drawlayer_cache_patch_t
typedef struct dt_drawlayer_damaged_rect_t	dt_drawlayer_damaged_rect_t
typedef enum dt_drawlayer_brush_shape_t	dt_drawlayer_brush_shape_t
	Supported analytic fall-off profiles for brush alpha.
typedef enum dt_drawlayer_brush_mode_t	dt_drawlayer_brush_mode_t
	Pixel blending behavior used while stamping a dab.
typedef dt_drawlayer_brush_shape_t	dt_iop_drawlayer_brush_shape_t
typedef dt_drawlayer_brush_mode_t	dt_iop_drawlayer_brush_mode_t
typedef struct dt_drawlayer_brush_dab_t	dt_drawlayer_brush_dab_t
	Fully resolved input dab descriptor.
typedef struct dt_drawlayer_brush_batch_t	dt_drawlayer_brush_batch_t
	A run of dabs that share everything the batch composite needs to be a single step.

Enumerations
enum	dt_drawlayer_brush_shape_t {   DT_DRAWLAYER_BRUSH_SHAPE_LINEAR = 0 ,   DT_DRAWLAYER_BRUSH_SHAPE_GAUSSIAN = 1 ,   DT_DRAWLAYER_BRUSH_SHAPE_QUADRATIC = 2 ,   DT_DRAWLAYER_BRUSH_SHAPE_SIGMOIDAL = 3 }
	Supported analytic fall-off profiles for brush alpha. More...
enum	dt_drawlayer_brush_mode_t {   DT_DRAWLAYER_BRUSH_MODE_PAINT = 0 ,   DT_DRAWLAYER_BRUSH_MODE_ERASE = 1 ,   DT_DRAWLAYER_BRUSH_MODE_BLUR = 2 ,   DT_DRAWLAYER_BRUSH_MODE_SMUDGE = 3 }
	Pixel blending behavior used while stamping a dab. More...

Functions
gboolean	dt_drawlayer_brush_rasterize (const dt_drawlayer_cache_patch_t *sample_patch, dt_drawlayer_cache_patch_t *patch, float scale, const dt_drawlayer_brush_dab_t *dab, float sample_opacity_scale, dt_drawlayer_cache_patch_t *stroke_mask, struct dt_drawlayer_paint_stroke_t *stroke)
	Rasterize one dab into a float RGBA buffer.
gboolean	dt_drawlayer_brush_batch_is_uniform (const dt_drawlayer_brush_dab_t *dabs, guint count, dt_drawlayer_brush_batch_t *out)
	Decide whether a run of dabs can take the batch path, and describe it if so.
gboolean	dt_drawlayer_brush_rasterize_batch (const dt_drawlayer_brush_batch_t *batch, dt_drawlayer_cache_patch_t *patch, float scale, dt_drawlayer_cache_patch_t *stroke_mask, float *transmittance, float *noise_scratch, dt_drawlayer_damaged_rect_t *batch_damage)
	Rasterize a whole batch in two passes: accumulate transmittance, then composite once.
gboolean	dt_drawlayer_brush_rasterize_dab_argb8 (const dt_drawlayer_brush_dab_t *dab, uint8_t *argb, int width, int height, int stride, float center_x, float center_y, float opacity_multiplier)
	Rasterize a single dab preview into ARGB8 for GUI overlays.
gboolean	dt_drawlayer_brush_rasterize_dab_rgbaf (const dt_drawlayer_brush_dab_t *dab, float *rgba, int width, int height, float center_x, float center_y, float opacity_multiplier, const float background_rgb[3])
	Rasterize a single dab preview in linear float RGBA over an opaque background.

Detailed Description

Dab-level brush rasterization API for drawlayer.

This API is intentionally independent from drawlayer module internals. Callers provide fully resolved dab inputs in target buffer coordinates.

Definition in file brush.h.

Macro Definition Documentation

OUTER_LOOP

#define OUTER_LOOP   1

Definition at line 25 of file brush.h.

Typedef Documentation

dt_drawlayer_brush_batch_t

typedef struct dt_drawlayer_brush_batch_t dt_drawlayer_brush_batch_t

A run of dabs that share everything the batch composite needs to be a single step.

Produced by dt_drawlayer_brush_batch_is_uniform. dabs is borrowed from the caller's array and must outlive the rasterization.

dt_drawlayer_brush_dab_t

typedef struct dt_drawlayer_brush_dab_t dt_drawlayer_brush_dab_t

Fully resolved input dab descriptor.

Instances are produced by the stroke-level paint API (or equivalent caller code) and consumed by the brush rasterizer.

dt_drawlayer_brush_mode_t

typedef enum dt_drawlayer_brush_mode_t dt_drawlayer_brush_mode_t

Pixel blending behavior used while stamping a dab.

dt_drawlayer_brush_shape_t

typedef enum dt_drawlayer_brush_shape_t dt_drawlayer_brush_shape_t

Supported analytic fall-off profiles for brush alpha.

dt_drawlayer_cache_patch_t

typedef struct dt_drawlayer_cache_patch_t dt_drawlayer_cache_patch_t

Definition at line 27 of file brush.h.

dt_drawlayer_damaged_rect_t

typedef struct dt_drawlayer_damaged_rect_t dt_drawlayer_damaged_rect_t

Definition at line 28 of file brush.h.

dt_iop_drawlayer_brush_mode_t

typedef dt_drawlayer_brush_mode_t dt_iop_drawlayer_brush_mode_t

Definition at line 57 of file brush.h.

dt_iop_drawlayer_brush_shape_t

typedef dt_drawlayer_brush_shape_t dt_iop_drawlayer_brush_shape_t

Definition at line 56 of file brush.h.

Enumeration Type Documentation

dt_drawlayer_brush_mode_t

enum dt_drawlayer_brush_mode_t

Pixel blending behavior used while stamping a dab.

Enumerator
DT_DRAWLAYER_BRUSH_MODE_PAINT	Standard source-over paint in premultiplied space.
DT_DRAWLAYER_BRUSH_MODE_ERASE	Alpha attenuation / erase mode.
DT_DRAWLAYER_BRUSH_MODE_BLUR	Local blur gather then blend.
DT_DRAWLAYER_BRUSH_MODE_SMUDGE	Carry-and-deposit color pickup mode.

Definition at line 48 of file brush.h.

dt_drawlayer_brush_shape_t

enum dt_drawlayer_brush_shape_t

Supported analytic fall-off profiles for brush alpha.

Enumerator
DT_DRAWLAYER_BRUSH_SHAPE_LINEAR	Linear ramp from inner to outer radius.
DT_DRAWLAYER_BRUSH_SHAPE_GAUSSIAN	Smooth bell-like fall-off.
DT_DRAWLAYER_BRUSH_SHAPE_QUADRATIC	Stronger center emphasis than linear.
DT_DRAWLAYER_BRUSH_SHAPE_SIGMOIDAL	S-curve transition near edge.

Definition at line 39 of file brush.h.

Function Documentation

dt_drawlayer_brush_batch_is_uniform()

gboolean dt_drawlayer_brush_batch_is_uniform	(	const dt_drawlayer_brush_dab_t *	dabs,
		guint	count,
		dt_drawlayer_brush_batch_t *	out
	)

Decide whether a run of dabs can take the batch path, and describe it if so.

Requires one mode across the run (PAINT or ERASE), one opacity, one colour, and UI Flow at 100% (internal flow 0). Those are the conditions under which the per-pixel stroke alpha collapses to a product of per-dab transmittance factors clamped once – see the derivation above dt_drawlayer_brush_rasterize_batch in brush.c. SMUDGE and BLUR never qualify: they read the destination per dab.

Returns

TRUE and fills out when the run qualifies, FALSE otherwise.

Definition at line 879 of file iop/drawlayer/brush.c.

References _clamp01(), dt_drawlayer_brush_dab_t::color, d, DT_DRAWLAYER_BRUSH_MODE_ERASE, DT_DRAWLAYER_BRUSH_MODE_PAINT, FALSE, dt_drawlayer_brush_dab_t::flow, i, IS_NULL_PTR, dt_drawlayer_brush_dab_t::mode, dt_drawlayer_brush_dab_t::opacity, out, dt_drawlayer_brush_dab_t::sprinkle_coarseness, dt_drawlayer_brush_dab_t::sprinkle_size, dt_drawlayer_brush_dab_t::sprinkles, dt_drawlayer_brush_dab_t::stroke_batch, and TRUE.

Referenced by _rasterize_pending_dab_batch(), _report_speedup(), _run_batch(), and test_gate_refuses_non_uniform().

dt_drawlayer_brush_rasterize()

gboolean dt_drawlayer_brush_rasterize	(	const dt_drawlayer_cache_patch_t *	sample_patch,
		dt_drawlayer_cache_patch_t *	patch,
		const float	scale,
		const dt_drawlayer_brush_dab_t *	dab,
		const float	sample_opacity_scale,
		dt_drawlayer_cache_patch_t *	stroke_mask,
		dt_drawlayer_paint_stroke_t *	runtime_private
	)

Rasterize one dab into a float RGBA buffer.

Parameters

sample_patch	Optional read-only source patch used by blur/smudge sampling. When NULL, sampling falls back to patch.
patch	Destination premultiplied RGBA float patch.
scale	Layer-to-buffer scale factor, must be >0.
dab	Fully resolved dab input (coordinates already in layer space).
sample_opacity_scale	Opacity normalization factor derived from spacing.
stroke_mask	Optional stroke-local alpha mask patch for overlap-aware flow.
stroke	Mutable stroke runtime payload (smudge context + dab bounds output).

Returns

TRUE when at least one pixel was processed; FALSE on invalid inputs or empty footprint.

Precondition

dab->radius > 0, dab->opacity > 0, scale > 0.

Coordinates transformation to layer space is handled by the caller.

Rasterize one dab into a float RGBA buffer.

Assumes caller already converted coordinates to layer space.

Definition at line 667 of file iop/drawlayer/brush.c.

References _apply_smudge_stroke_mode(), _brush_runtime_view_from_state(), _clamp01(), _estimate_alpha_noise_gain(), _prepare_analytic_pixel_context(), _prepare_blur_context(), dt_drawlayer_brush_runtime_view_t::alpha_noise_gain, dt_drawlayer_paint_stroke_t::bounds, DT_DRAWLAYER_BRUSH_MODE_BLUR, DT_DRAWLAYER_BRUSH_MODE_ERASE, DT_DRAWLAYER_BRUSH_MODE_PAINT, DT_DRAWLAYER_BRUSH_MODE_SMUDGE, dt_drawlayer_paint_runtime_ensure_smudge_pixels(), dt_drawlayer_paint_runtime_prepare_dab_context(), dt_simd_set1(), dt_store_simd(), FALSE, dt_drawlayer_brush_dab_t::flow, height, dt_drawlayer_cache_patch_t::height, IS_NULL_PTR, dt_drawlayer_brush_dab_t::opacity, origin_x, origin_y, dt_drawlayer_cache_patch_t::pixels, dt_drawlayer_brush_dab_t::radius, dt_drawlayer_damaged_rect_t::se, dt_drawlayer_brush_pixel_eval_t::src_alpha, dt_drawlayer_brush_pixel_eval_t::stroke_alpha, dt_drawlayer_brush_pixel_eval_t::stroke_old_alpha, TRUE, view, width, dt_drawlayer_cache_patch_t::width, x, dt_drawlayer_cache_patch_t::x, and dt_drawlayer_cache_patch_t::y.

Referenced by _report_speedup(), _run_serial(), and dt_drawlayer_paint_rasterize_segment_to_buffer().

dt_drawlayer_brush_rasterize_batch()

gboolean dt_drawlayer_brush_rasterize_batch	(	const dt_drawlayer_brush_batch_t *	batch,
		dt_drawlayer_cache_patch_t *	patch,
		float	scale,
		dt_drawlayer_cache_patch_t *	stroke_mask,
		float *	transmittance,
		float *	noise_scratch,
		dt_drawlayer_damaged_rect_t *	batch_damage
	)

Rasterize a whole batch in two passes: accumulate transmittance, then composite once.

Parameters

batch	Uniform run from dt_drawlayer_brush_batch_is_uniform.
patch	Destination premultiplied RGBA float patch (the heartbeat scratch).
scale	Layer-to-buffer scale factor, must be >0.
stroke_mask	Stroke-local alpha, same dimensions as patch. Read as the batch's starting alpha and overwritten with the batch's result.
transmittance	Caller-owned scratch plane of at least patch->width * patch->height floats. Contents on entry are irrelevant; the batch box is initialised.
noise_scratch	Optional second plane of the same size. When the batch carries texture, the sprinkle field – a function of LAYER position alone, hence identical for every overlapping dab – is evaluated into it once instead of once per dab per pixel. NULL falls back to evaluating it per dab.
batch_damage	Optional; the batch's footprint is unioned into it.

Returns

TRUE when at least one dab contributed.

Both passes are parallel over disjoint rows, so the result does not depend on the thread schedule – unlike the per-dab loop it replaces, whose tile locks excluded but did not order.

Definition at line 917 of file iop/drawlayer/brush.c.

References _brush_alpha_at(), _brush_alpha_at_noise(), _brush_runtime_view_from_bounds(), _clamp01(), _estimate_alpha_noise_gain(), _sample_alpha_noise_raw(), bbox, dt_drawlayer_brush_batch_t::cap, dt_drawlayer_brush_batch_t::color, dt_drawlayer_brush_batch_t::count, dt_drawlayer_brush_batch_t::dabs, DT_DRAWLAYER_BRUSH_MODE_ERASE, dt_drawlayer_paint_runtime_note_dab_damage(), dt_simd_set1(), dt_store_simd(), FALSE, dt_drawlayer_brush_dab_t::flow, height, dt_drawlayer_cache_patch_t::height, i, IS_NULL_PTR, MAX, MIN, dt_drawlayer_brush_batch_t::mode, dt_drawlayer_damaged_rect_t::nw, dt_drawlayer_brush_dab_t::opacity, dt_drawlayer_cache_patch_t::pixels, dt_drawlayer_brush_dab_t::radius, row, dt_drawlayer_damaged_rect_t::se, dt_drawlayer_brush_batch_t::sprinkles, t, TRUE, dt_drawlayer_damaged_rect_t::valid, view, views(), width, dt_drawlayer_cache_patch_t::width, x, dt_drawlayer_brush_dab_t::x, dt_drawlayer_cache_patch_t::x, dt_drawlayer_brush_dab_t::y, and dt_drawlayer_cache_patch_t::y.

Referenced by _rasterize_pending_dab_batch(), _report_speedup(), and _run_batch().

dt_drawlayer_brush_rasterize_dab_argb8()

gboolean dt_drawlayer_brush_rasterize_dab_argb8	(	const dt_drawlayer_brush_dab_t *	dab,
		uint8_t *	argb,
		const int	width,
		const int	height,
		const int	stride,
		const float	center_x,
		const float	center_y,
		const float	opacity_multiplier
	)

Rasterize a single dab preview into ARGB8 for GUI overlays.

Parameters

dab	Input dab descriptor.
argb	Destination 8-bit ARGB surface memory.
width	Surface width.
height	Surface height.
stride	Surface stride in bytes.
center_x	Dab center X in surface coordinates.
center_y	Dab center Y in surface coordinates.
opacity_multiplier	Additional UI-time opacity scalar in [0,1].

Returns

TRUE on success, FALSE on invalid inputs.

Note

This path is for cursor/post-expose rendering only and does not update stroke runtime state.

Rasterize a single dab preview into ARGB8 for GUI overlays.

Returns

TRUE on success.

Definition at line 1081 of file iop/drawlayer/brush.c.

References _clamp01(), _prepare_sprinkle_preview(), _sample_sprinkle_preview(), dt_drawlayer_brush_profile_eval(), FALSE, height, IS_NULL_PTR, dt_drawlayer_brush_dab_t::opacity, preview, dt_drawlayer_brush_dab_t::radius, TRUE, width, and x.

Referenced by _ensure_cursor_stamp_surface().

dt_drawlayer_brush_rasterize_dab_rgbaf()

gboolean dt_drawlayer_brush_rasterize_dab_rgbaf	(	const dt_drawlayer_brush_dab_t *	dab,
		float *	rgba,
		int	width,
		int	height,
		float	center_x,
		float	center_y,
		float	opacity_multiplier,
		const float	background_rgb[3]
	)

Rasterize a single dab preview in linear float RGBA over an opaque background.

Parameters

dab	Input dab descriptor.
rgba	Destination float RGBA buffer (width*height*4), filled in linear display RGB.
width	Surface width.
height	Surface height.
center_x	Dab center X in surface coordinates.
center_y	Dab center Y in surface coordinates.
opacity_multiplier	Additional UI-time opacity scalar in [0,1].
background_rgb	Opaque linear RGB background color, or NULL for white.

Returns

TRUE on success, FALSE on invalid inputs.

Definition at line 1134 of file iop/drawlayer/brush.c.

References _clamp01(), _prepare_sprinkle_preview(), _sample_sprinkle_preview(), dt_drawlayer_brush_profile_eval(), FALSE, height, i, IS_NULL_PTR, dt_drawlayer_brush_dab_t::opacity, preview, dt_drawlayer_brush_dab_t::radius, TRUE, width, and x.

Referenced by _render_brush_profile_cell().