Stroke-level path sampling and runtime-state API for drawlayer. More...

#include "iop/drawlayer/brush.h"
#include <glib.h>
#include <stdint.h>

Include dependency graph for iop/drawlayer/paint.h:

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

Data Structures
struct	dt_drawlayer_paint_raw_input_t
	One raw pointer event queued to stroke processing. More...

struct	dt_drawlayer_damaged_rect_t
	Integer axis-aligned rectangle in buffer coordinates. More...

struct	dt_drawlayer_paint_stroke_t
	Mutable stroke runtime state owned by worker/backend code. More...

struct	dt_drawlayer_paint_callbacks_t
	Callback bundle used by stroke processing entry points. More...

Typedefs
typedef enum dt_drawlayer_paint_stroke_pos_t	dt_drawlayer_paint_stroke_pos_t
	Position of a raw input event inside a stroke lifecycle.

typedef struct dt_drawlayer_paint_raw_input_t	dt_drawlayer_paint_raw_input_t
	One raw pointer event queued to stroke processing.

typedef struct dt_drawlayer_damaged_rect_t	dt_drawlayer_damaged_rect_t
	Integer axis-aligned rectangle in buffer coordinates.

typedef struct dt_drawlayer_paint_stroke_t	dt_drawlayer_paint_stroke_t
	Mutable stroke runtime state owned by worker/backend code.

typedef gboolean(*	dt_drawlayer_paint_build_dab_cb) (void user_data, dt_drawlayer_paint_stroke_t state, const dt_drawlayer_paint_raw_input_t input, dt_drawlayer_brush_dab_t out_dab)
	Build a resolved dab from one raw input event.

typedef gboolean(*	dt_drawlayer_paint_layer_to_widget_cb) (void user_data, float lx, float ly, float wx, float *wy)
	Convert layer-space coordinates back to widget-space (for HUD/preview alignment).

typedef void(*	dt_drawlayer_paint_stroke_seed_cb) (void *user_data, uint64_t stroke_seed)
	Notify caller when a new stroke seed is started.

typedef struct dt_drawlayer_paint_callbacks_t	dt_drawlayer_paint_callbacks_t
	Callback bundle used by stroke processing entry points.

Enumerations
enum	dt_drawlayer_paint_stroke_pos_t { DT_DRAWLAYER_PAINT_STROKE_FIRST = 0 , DT_DRAWLAYER_PAINT_STROKE_MIDDLE = 1 , DT_DRAWLAYER_PAINT_STROKE_END = 2 }
	Position of a raw input event inside a stroke lifecycle. More...

Functions
void	dt_drawlayer_paint_path_state_reset (dt_drawlayer_paint_stroke_t *state)
	Reset stroke path state and pending raw queue for a new stroke.

gboolean	dt_drawlayer_paint_queue_raw_input (dt_drawlayer_paint_stroke_t state, const dt_drawlayer_paint_raw_input_t input)
	Queue one raw input event (FIFO).

void	dt_drawlayer_paint_interpolate_path (dt_drawlayer_paint_stroke_t state, const dt_drawlayer_paint_callbacks_t callbacks, void *user_data)
	Drain queued raw input events and append evenly spaced dabs to `state->pending_dabs`.

void	dt_drawlayer_paint_finalize_path (dt_drawlayer_paint_stroke_t *state)
	Force emission of a pending initial dab when a stroke had no emitted samples yet.

gboolean	dt_drawlayer_paint_rasterize_segment_to_buffer (const dt_drawlayer_brush_dab_t dab, float distance_percent, const dt_drawlayer_cache_patch_t sample_patch, dt_drawlayer_cache_patch_t patch, float scale, dt_drawlayer_cache_patch_t stroke_mask, dt_drawlayer_damaged_rect_t runtime_state, dt_drawlayer_paint_stroke_t runtime_private)
	Replay one emitted dab segment into a float buffer through brush API.

dt_drawlayer_damaged_rect_t *	dt_drawlayer_paint_runtime_state_create (void)
	Allocate zero-initialized stroke-damage accumulator state.

void	dt_drawlayer_paint_runtime_state_destroy (dt_drawlayer_damaged_rect_t **state)
	Destroy stroke-damage accumulator state and null pointer.

void	dt_drawlayer_paint_runtime_state_reset (dt_drawlayer_damaged_rect_t *state)
	Reset stroke-damage accumulator to empty/invalid.

dt_drawlayer_paint_stroke_t *	dt_drawlayer_paint_runtime_private_create (void)
	Allocate stroke runtime payload object used by paint+brush internals.

void	dt_drawlayer_paint_runtime_private_destroy (dt_drawlayer_paint_stroke_t **state)
	Destroy stroke runtime payload and null pointer.

void	dt_drawlayer_paint_runtime_private_reset (dt_drawlayer_paint_stroke_t *state)
	Reset transient stroke runtime payload between strokes.

void	dt_drawlayer_paint_runtime_set_stroke_seed (dt_drawlayer_paint_stroke_t *state, uint64_t seed)
	Set deterministic stroke seed for noise-derived effects.

uint64_t	dt_drawlayer_paint_runtime_get_stroke_seed (const dt_drawlayer_paint_stroke_t *state)
	Get current deterministic stroke seed.

gboolean	dt_drawlayer_paint_runtime_ensure_smudge_pixels (dt_drawlayer_paint_stroke_t *state, int width, int height)
	Ensure smudge carry buffer allocation for given footprint dimensions.

float *	dt_drawlayer_paint_runtime_smudge_pixels (dt_drawlayer_paint_stroke_t *state)
	Get smudge carry buffer pointer (RGBA float).

int	dt_drawlayer_paint_runtime_smudge_width (const dt_drawlayer_paint_stroke_t *state)
	Get smudge carry buffer width.

int	dt_drawlayer_paint_runtime_smudge_height (const dt_drawlayer_paint_stroke_t *state)
	Get smudge carry buffer height.

gboolean	dt_drawlayer_paint_runtime_have_smudge_pickup (const dt_drawlayer_paint_stroke_t *state)
	Query whether smudge pickup coordinates are initialized.

void	dt_drawlayer_paint_runtime_get_smudge_pickup (const dt_drawlayer_paint_stroke_t state, float x, float *y)
	Read smudge pickup coordinates.

void	dt_drawlayer_paint_runtime_set_smudge_pickup (dt_drawlayer_paint_stroke_t *state, float x, float y, gboolean have_pickup)
	Write smudge pickup coordinates and validity flag.

gboolean	dt_drawlayer_paint_runtime_prepare_dab_context (dt_drawlayer_paint_stroke_t state, const dt_drawlayer_brush_dab_t dab, int width, int height, int origin_x, int origin_y, float scale)
	Compute current dab footprint bounds in target buffer coordinates.

void	dt_drawlayer_paint_runtime_note_dab_damage (dt_drawlayer_damaged_rect_t state, const dt_drawlayer_damaged_rect_t dab_rect)
	Merge one dab rectangle into an accumulator rectangle.

gboolean	dt_drawlayer_paint_runtime_get_stroke_damage (const dt_drawlayer_damaged_rect_t state, dt_drawlayer_damaged_rect_t out_rect)
	Read accumulated stroke damage rectangle.

gboolean	dt_drawlayer_paint_merge_runtime_stroke_damage (dt_drawlayer_damaged_rect_t path_state, dt_drawlayer_damaged_rect_t target_rect)
	Merge path-state damage into target rectangle and clear path-state accumulator.

Detailed Description

Stroke-level path sampling and runtime-state API for drawlayer.

This layer consumes raw pointer input events and emits evenly spaced, optionally smoothed dabs. Rasterization is delegated to brush.h.

Typedef Documentation

◆ dt_drawlayer_damaged_rect_t

typedef struct dt_drawlayer_damaged_rect_t dt_drawlayer_damaged_rect_t

Integer axis-aligned rectangle in buffer coordinates.

Convention: nw is inclusive, se is exclusive.

◆ dt_drawlayer_paint_build_dab_cb

typedef gboolean(* dt_drawlayer_paint_build_dab_cb) (void *user_data, dt_drawlayer_paint_stroke_t *state, const dt_drawlayer_paint_raw_input_t *input, dt_drawlayer_brush_dab_t *out_dab)

Build a resolved dab from one raw input event.

Parameters

user_data	Opaque caller context.
state	Mutable stroke runtime state.
input	Raw input event.
out_dab	Output resolved dab.

Returns: TRUE when dab creation succeeds.

Precondition: Coordinate transforms and dynamic mapping policy are handled by callback implementation.

◆ dt_drawlayer_paint_callbacks_t

typedef struct dt_drawlayer_paint_callbacks_t dt_drawlayer_paint_callbacks_t

Callback bundle used by stroke processing entry points.

◆ dt_drawlayer_paint_layer_to_widget_cb

typedef gboolean(* dt_drawlayer_paint_layer_to_widget_cb) (void *user_data, float lx, float ly, float *wx, float *wy)

Convert layer-space coordinates back to widget-space (for HUD/preview alignment).

◆ dt_drawlayer_paint_raw_input_t

typedef struct dt_drawlayer_paint_raw_input_t dt_drawlayer_paint_raw_input_t

One raw pointer event queued to stroke processing.

All brush/user settings are snapshotted per event so asynchronous processing does not depend on mutable GUI state.

◆ dt_drawlayer_paint_stroke_pos_t

typedef enum dt_drawlayer_paint_stroke_pos_t dt_drawlayer_paint_stroke_pos_t

Position of a raw input event inside a stroke lifecycle.

◆ dt_drawlayer_paint_stroke_seed_cb

typedef void(* dt_drawlayer_paint_stroke_seed_cb) (void *user_data, uint64_t stroke_seed)

Notify caller when a new stroke seed is started.

◆ dt_drawlayer_paint_stroke_t

typedef struct dt_drawlayer_paint_stroke_t dt_drawlayer_paint_stroke_t

Mutable stroke runtime state owned by worker/backend code.

The same object carries path generation state and raster-time transient data. It is reset at stroke boundaries by the worker lifecycle.

Enumeration Type Documentation

◆ dt_drawlayer_paint_stroke_pos_t

enum dt_drawlayer_paint_stroke_pos_t

Position of a raw input event inside a stroke lifecycle.

Enumerator
DT_DRAWLAYER_PAINT_STROKE_FIRST	Button-press / stroke start marker.
DT_DRAWLAYER_PAINT_STROKE_MIDDLE	In-stroke motion sample.
DT_DRAWLAYER_PAINT_STROKE_END	Button-release / stroke end marker.

Function Documentation

◆ dt_drawlayer_paint_finalize_path()

void dt_drawlayer_paint_finalize_path ( dt_drawlayer_paint_stroke_t * state )

Force emission of a pending initial dab when a stroke had no emitted samples yet.

Note: Used for very short strokes that collected no middle sample.

References _clamp01(), _emit_dab(), _ensure_pending_dabs(), _freeze_emitted_dab_raster_state(), _paint_dab_sample_spacing(), DT_DRAWLAYER_PAINT_STROKE_FIRST, IS_NULL_PTR, state, and dt_drawlayer_brush_dab_t::stroke_pos.

Referenced by _backend_worker_process_stroke_end(), and _flush_pending_initial_if_needed().

◆ dt_drawlayer_paint_interpolate_path()

void dt_drawlayer_paint_interpolate_path	(	dt_drawlayer_paint_stroke_t *	state,
		const dt_drawlayer_paint_callbacks_t *	callbacks,
		void *	user_data
	)

Drain queued raw input events and append evenly spaced dabs to state->pending_dabs.

Note: No coalescing is performed here. FIFO order is preserved.

References _paint_compact_raw_input_queue(), _paint_process_one_raw_input(), IS_NULL_PTR, and state.

Referenced by _process_backend_input().

◆ dt_drawlayer_paint_merge_runtime_stroke_damage()

gboolean dt_drawlayer_paint_merge_runtime_stroke_damage	(	dt_drawlayer_damaged_rect_t *	path_state,
		dt_drawlayer_damaged_rect_t *	target_rect
	)

Merge path-state damage into target rectangle and clear path-state accumulator.

Returns: TRUE when a valid rectangle was merged.

References _paint_union_damage_rect(), dt_drawlayer_paint_runtime_get_stroke_damage(), dt_drawlayer_paint_runtime_state_reset(), FALSE, IS_NULL_PTR, and TRUE.

Referenced by dt_drawlayer_worker_publish_backend_stroke_damage().

◆ dt_drawlayer_paint_path_state_reset()

void dt_drawlayer_paint_path_state_reset ( dt_drawlayer_paint_stroke_t * state )

Reset stroke path state and pending raw queue for a new stroke.

References _paint_reset_path_runtime_state(), IS_NULL_PTR, and state.

Referenced by _stroke_begin(), and _stroke_clear().

◆ dt_drawlayer_paint_queue_raw_input()

gboolean dt_drawlayer_paint_queue_raw_input	(	dt_drawlayer_paint_stroke_t *	state,
		const dt_drawlayer_paint_raw_input_t *	input
	)

Queue one raw input event (FIFO).

References _ensure_raw_inputs(), FALSE, IS_NULL_PTR, state, and TRUE.

Referenced by _process_backend_input().

◆ dt_drawlayer_paint_rasterize_segment_to_buffer()

gboolean dt_drawlayer_paint_rasterize_segment_to_buffer	(	const dt_drawlayer_brush_dab_t *	dab,
		float	distance_percent,
		const dt_drawlayer_cache_patch_t *	sample_patch,
		dt_drawlayer_cache_patch_t *	patch,
		float	scale,
		dt_drawlayer_cache_patch_t *	stroke_mask,
		dt_drawlayer_damaged_rect_t *	runtime_state,
		dt_drawlayer_paint_stroke_t *	runtime_private
	)

Replay one emitted dab segment into a float buffer through brush API.

Parameters

dab	Input dab sample from path stream.
distance_percent	Sampling distance parameter in [0,1].
sample_patch	Optional read-only source patch used by blur/smudge sampling. When NULL, sampling falls back to `patch`.
patch	Destination float RGBA patch.
scale	Layer-to-buffer scale factor.
stroke_mask	Optional stroke-local alpha mask patch.
runtime_state	Accumulated stroke damage output.
runtime_private	Mutable stroke runtime payload.

Returns: TRUE when dab replay succeeded.

References _advance_smudge_pickup_state(), _clamp01(), _paint_dab_sample_spacing(), _paint_stroke_sample_opacity_scale(), dt_drawlayer_paint_stroke_t::bounds, dt_drawlayer_paint_stroke_t::dab_window, darktable, DT_DEBUG_PERF, DT_DEBUG_VERBOSE, DT_DRAWLAYER_BRUSH_MODE_SMUDGE, dt_drawlayer_brush_rasterize(), dt_drawlayer_paint_runtime_note_dab_damage(), dt_drawlayer_paint_runtime_set_smudge_pickup(), DT_DRAWLAYER_PAINT_STROKE_FIRST, dt_get_wtime(), dt_print(), FALSE, IS_NULL_PTR, MIN, dt_drawlayer_brush_dab_t::mode, dt_drawlayer_damaged_rect_t::nw, dt_drawlayer_brush_dab_t::sample_opacity_scale, dt_drawlayer_brush_dab_t::sample_spacing, dt_drawlayer_damaged_rect_t::se, dt_drawlayer_brush_dab_t::stroke_pos, TRUE, darktable_t::unmuted, and dt_drawlayer_damaged_rect_t::valid.

Referenced by _process_backend_dab().

◆ dt_drawlayer_paint_runtime_ensure_smudge_pixels()

gboolean dt_drawlayer_paint_runtime_ensure_smudge_pixels	(	dt_drawlayer_paint_stroke_t *	state,
		int	width,
		int	height
	)

Ensure smudge carry buffer allocation for given footprint dimensions.

References FALSE, height, IS_NULL_PTR, state, TRUE, and width.

Referenced by dt_drawlayer_brush_rasterize().

◆ dt_drawlayer_paint_runtime_get_smudge_pickup()

void dt_drawlayer_paint_runtime_get_smudge_pickup	(	const dt_drawlayer_paint_stroke_t *	state,
		float *	x,
		float *	y
	)

Read smudge pickup coordinates.

References IS_NULL_PTR, state, and x.

Referenced by _advance_smudge_pickup_state(), and _apply_smudge_stroke_mode().

◆ dt_drawlayer_paint_runtime_get_stroke_damage()

gboolean dt_drawlayer_paint_runtime_get_stroke_damage	(	const dt_drawlayer_damaged_rect_t *	state,
		dt_drawlayer_damaged_rect_t *	out_rect
	)

Read accumulated stroke damage rectangle.

References FALSE, IS_NULL_PTR, state, and TRUE.

Referenced by dt_drawlayer_paint_merge_runtime_stroke_damage().

◆ dt_drawlayer_paint_runtime_get_stroke_seed()

uint64_t dt_drawlayer_paint_runtime_get_stroke_seed ( const dt_drawlayer_paint_stroke_t * state )

Get current deterministic stroke seed.

References state.

◆ dt_drawlayer_paint_runtime_have_smudge_pickup()

gboolean dt_drawlayer_paint_runtime_have_smudge_pickup ( const dt_drawlayer_paint_stroke_t * state )

Query whether smudge pickup coordinates are initialized.

References state.

Referenced by _advance_smudge_pickup_state(), and _apply_smudge_stroke_mode().

◆ dt_drawlayer_paint_runtime_note_dab_damage()

void dt_drawlayer_paint_runtime_note_dab_damage	(	dt_drawlayer_damaged_rect_t *	state,
		const dt_drawlayer_damaged_rect_t *	dab_rect
	)

Merge one dab rectangle into an accumulator rectangle.

References IS_NULL_PTR, MAX, MIN, dt_drawlayer_damaged_rect_t::nw, dt_drawlayer_damaged_rect_t::se, state, TRUE, and dt_drawlayer_damaged_rect_t::valid.

Referenced by _collect_batch_bounds(), _process_backend_dab(), _rasterize_pending_dab_batch(), dt_drawlayer_paint_rasterize_segment_to_buffer(), and dt_drawlayer_worker_publish_backend_stroke_damage().

◆ dt_drawlayer_paint_runtime_prepare_dab_context()

gboolean dt_drawlayer_paint_runtime_prepare_dab_context	(	dt_drawlayer_paint_stroke_t *	state,
		const dt_drawlayer_brush_dab_t *	dab,
		int	width,
		int	height,
		int	origin_x,
		int	origin_y,
		float	scale
	)