GUI CURVE: a curve editor widget

Typedefs
typedef void(*	N_GUI_CURVE_BACKGROUND) (float x, float y, float w, float h, void *user_data)
	drawn behind the grid and the curve, such as a histogram.
typedef void(*	N_GUI_CURVE_CHANGE) (int widget_id, int dragging, void *user_data)
	called on every change of the points.
typedef float(*	N_GUI_CURVE_EVAL) (const float *xs, const float *ys, int count, float x, void *user_data)
	the caller's curve through the points, for drawing.

Functions
float	n_gui_curve_eval (N_GUI_CTX *ctx, int widget_id, float x)
	The editor's curve at x, as it is drawn.
float	n_gui_curve_eval_points (const float *xs, const float *ys, int count, float x)
	A monotone cubic Hermite spline through points.
int	n_gui_curve_get_points (N_GUI_CTX *ctx, int widget_id, float *xs, float *ys, int max)
	Read the points.
int	n_gui_curve_new (N_GUI_CTX *ctx, int window_id, float x, float y, float w, float h, int max_points, N_GUI_CURVE_CHANGE on_change, void *user_data)
	Add a curve editor to a window.
void	n_gui_curve_set_background (N_GUI_CTX *ctx, int widget_id, N_GUI_CURVE_BACKGROUND draw, void *user_data)
	Draw something behind the grid and the curve.
void	n_gui_curve_set_eval (N_GUI_CTX *ctx, int widget_id, N_GUI_CURVE_EVAL eval, void *user_data)
	Draw the caller's own curve through the points.
void	n_gui_curve_set_point_radius (N_GUI_CTX *ctx, int widget_id, float radius)
	Size of the drawn points, for a display scale.
int	n_gui_curve_set_points (N_GUI_CTX *ctx, int widget_id, const float *xs, const float *ys, int count)
	Replace the points.

Detailed Description

Typedef Documentation

N_GUI_CURVE_BACKGROUND

typedef void(* N_GUI_CURVE_BACKGROUND) (float x, float y, float w, float h, void *user_data)

drawn behind the grid and the curve, such as a histogram.

Parameters

x	left edge on screen
y	top edge on screen
w	width
h	height
user_data	what was handed to n_gui_curve_set_background()

Definition at line 92 of file n_gui_curve.h.

N_GUI_CURVE_CHANGE

typedef void(* N_GUI_CURVE_CHANGE) (int widget_id, int dragging, void *user_data)

called on every change of the points.

Parameters

widget_id	the editor
dragging	1 while the change is a step of a drag of one point, 0 for a point added or removed
user_data	what was handed to n_gui_curve_new()

Definition at line 75 of file n_gui_curve.h.

N_GUI_CURVE_EVAL

typedef float(* N_GUI_CURVE_EVAL) (const float *xs, const float *ys, int count, float x, void *user_data)

the caller's curve through the points, for drawing.

Parameters

xs	the points' x, ascending, in [0,1]
ys	the points' y, in [0,1]
count	how many points, at least 2
x	where to evaluate, in [0,1]
user_data	what was handed to n_gui_curve_set_eval()

Returns

the curve's value at x

Definition at line 84 of file n_gui_curve.h.

Function Documentation

n_gui_curve_eval()

float n_gui_curve_eval	(	N_GUI_CTX *	ctx,
		int	widget_id,
		float	x )

The editor's curve at x, as it is drawn.

Parameters

ctx	the GUI context.
widget_id	the editor.
x	where, clamped to [0,1].

Returns

the value, or x when widget_id is not an editor.

Definition at line 416 of file n_gui_curve.c.

References _curve_of(), and _curve_value().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_gui_curve_eval_points()

float n_gui_curve_eval_points	(	const float *	xs,
		const float *	ys,
		int	count,
		float	x )

A monotone cubic Hermite spline through points.

The tangents are the averaged secant slopes, zeroed at a local extremum and limited to three times the segment's slope (Fritsch-Carlson), so a segment never overshoots its end points. Outside the points the curve holds the end value. The result is clamped to [0,1].

Parameters

xs	the points' x, ascending. Must not be NULL.
ys	the points' y. Must not be NULL.
count	how many. 0 gives x, 1 gives that point's y.
x	where, clamped to [0,1].

Returns

the value.

Definition at line 82 of file n_gui_curve.c.

References _curve_clamp().

Referenced by _curve_value(), and main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_gui_curve_get_points()

int n_gui_curve_get_points	(	N_GUI_CTX *	ctx,
		int	widget_id,
		float *	xs,
		float *	ys,
		int	max )

Read the points.

Parameters

ctx	the GUI context.
widget_id	the editor.
xs	receives up to max x, ascending. May be NULL to count only.
ys	receives up to max y. May be NULL to count only.
max	room in xs and ys.

Returns

how many points the editor holds, or -1 when it is not an editor.

Definition at line 378 of file n_gui_curve.c.

References _curve_of(), _N_GUI_CURVE::count, _N_GUI_CURVE::xs, and _N_GUI_CURVE::ys.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_gui_curve_new()

int n_gui_curve_new	(	N_GUI_CTX *	ctx,
		int	window_id,
		float	x,
		float	y,
		float	w,
		float	h,
		int	max_points,
		N_GUI_CURVE_CHANGE	on_change,
		void *	user_data )

Add a curve editor to a window.

It starts as the identity, two points at (0,0) and (1,1).

Parameters

ctx	the GUI context. Must not be NULL.
window_id	the window to add it to.
x	left, relative to the window.
y	top, relative to the window.
w	width.
h	height.
max_points	how many points it may hold, 2 or more.
on_change	called on every change. May be NULL.
user_data	handed back to on_change.

Returns

the widget id, or -1 on error. The editor's state is the widget's and is freed with it.

Definition at line 311 of file n_gui_curve.c.

References __n_assert, _curve_block_destroy(), _curve_draw(), _curve_mouse(), _N_GUI_CURVE::count, _N_GUI_CURVE_MOUSE::ctx, _N_GUI_CURVE_BLOCK::cv, _N_GUI_CURVE_MOUSE::cv, _N_GUI_CURVE::dragging, _N_GUI_CURVE::id, LOG_ERR, _N_GUI_CURVE::max, _N_GUI_CURVE_BLOCK::mouse, n_gui_add_custom(), n_gui_custom_set_destroy(), n_gui_custom_set_mouse(), n_log, _N_GUI_CURVE::on_change, on_change(), _N_GUI_CURVE::radius, _N_GUI_CURVE::user_data, _N_GUI_CURVE::xs, and _N_GUI_CURVE::ys.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_gui_curve_set_background()

void n_gui_curve_set_background	(	N_GUI_CTX *	ctx,
		int	widget_id,
		N_GUI_CURVE_BACKGROUND	draw,
		void *	user_data )

Draw something behind the grid and the curve.

Parameters

ctx	the GUI context.
widget_id	the editor.
draw	the callback; NULL draws nothing there.
user_data	handed back to draw.

Definition at line 399 of file n_gui_curve.c.

References _curve_of(), _N_GUI_CURVE::background, _N_GUI_CURVE::background_user_data, draw(), and n_gui_mark_dirty().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_gui_curve_set_eval()

void n_gui_curve_set_eval	(	N_GUI_CTX *	ctx,
		int	widget_id,
		N_GUI_CURVE_EVAL	eval,
		void *	user_data )

Draw the caller's own curve through the points.

Parameters

ctx	the GUI context.
widget_id	the editor.
eval	the caller's curve; NULL goes back to n_gui_curve_eval_points().
user_data	handed back to eval.

Definition at line 390 of file n_gui_curve.c.

References _curve_of(), _N_GUI_CURVE::eval, _N_GUI_CURVE::eval_user_data, and n_gui_mark_dirty().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_gui_curve_set_point_radius()

void n_gui_curve_set_point_radius	(	N_GUI_CTX *	ctx,
		int	widget_id,
		float	radius )

Size of the drawn points, for a display scale.

A press within two and a half radii of a point takes it.

Parameters

ctx	the GUI context.
widget_id	the editor.
radius	in pixels, 4 by default. Zero or less is ignored.

Definition at line 408 of file n_gui_curve.c.

References _curve_of(), n_gui_mark_dirty(), and _N_GUI_CURVE::radius.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_gui_curve_set_points()

int n_gui_curve_set_points	(	N_GUI_CTX *	ctx,
		int	widget_id,
		const float *	xs,
		const float *	ys,
		int	count )

Replace the points.

on_change is not called.

Refused while a point is being dragged, so a model echoing a change back cannot pull the point from under the pointer. The points are sorted by x and clamped to [0,1].

Parameters

ctx	the GUI context.
widget_id	the editor.
xs	the points' x. Must not be NULL.
ys	the points' y. Must not be NULL.
count	how many, 2 to the editor's maximum.

Returns

TRUE, or FALSE when refused or on a bad argument.

Definition at line 351 of file n_gui_curve.c.

References _curve_clamp(), _curve_of(), _N_GUI_CURVE::count, _N_GUI_CURVE::dragging, _N_GUI_CURVE::max, n_gui_mark_dirty(), _N_GUI_CURVE::xs, and _N_GUI_CURVE::ys.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function: