fdl_builder_api.cpp File Reference

C ABI wrappers for the document builder (create, add, set, remove operations). More...

#include "fdl/fdl_core.h"
#include "fdl_builder.h"
#include "fdl_compat.h"
#include "fdl_doc.h"
#include "fdl_enum_map.h"
#include <cstring>
#include <new>
#include <string>

Typedefs
using	ojson = jsoncons::ojson

Functions
void	fdl_doc_set_uuid (fdl_doc_t *doc, const char *uuid)
	Set the UUID on a document.
void	fdl_doc_set_fdl_creator (fdl_doc_t *doc, const char *creator)
	Set the fdl_creator on a document.
void	fdl_doc_set_default_framing_intent (fdl_doc_t *doc, const char *fi_id)
	Set the default_framing_intent on a document.
void	fdl_doc_set_version (fdl_doc_t *doc, int major, int minor)
	Set the FDL version on a document.
fdl_doc_t *	fdl_doc_create_with_header (const char *uuid, int version_major, int version_minor, const char *fdl_creator, const char *default_framing_intent)
	Create a new FDL document with header fields and empty collections.
fdl_framing_intent_t *	fdl_doc_add_framing_intent (fdl_doc_t *doc, const char *id, const char *label, int64_t aspect_w, int64_t aspect_h, double protection)
	Add a framing intent to the document.
fdl_context_t *	fdl_doc_add_context (fdl_doc_t *doc, const char *label, const char *context_creator)
	Add a context to the document.
fdl_canvas_t *	fdl_context_add_canvas (fdl_context_t *ctx, const char *id, const char *label, const char *source_canvas_id, int64_t dim_w, int64_t dim_h, double squeeze)
	Add a canvas to a context.
void	fdl_canvas_set_effective_dimensions (fdl_canvas_t *canvas, fdl_dimensions_i64_t dims, fdl_point_f64_t anchor)
	Set effective dimensions and anchor on a canvas.
void	fdl_canvas_set_photosite_dimensions (fdl_canvas_t *canvas, fdl_dimensions_i64_t dims)
	Set photosite dimensions on a canvas.
void	fdl_canvas_set_physical_dimensions (fdl_canvas_t *canvas, fdl_dimensions_f64_t dims)
	Set physical dimensions on a canvas.
fdl_framing_decision_t *	fdl_canvas_add_framing_decision (fdl_canvas_t *canvas, const char *id, const char *label, const char *framing_intent_id, double dim_w, double dim_h, double anchor_x, double anchor_y)
	Add a framing decision to a canvas.
void	fdl_framing_decision_set_protection (fdl_framing_decision_t *fd, fdl_dimensions_f64_t dims, fdl_point_f64_t anchor)
	Set protection dimensions and anchor on a framing decision.
fdl_canvas_template_t *	fdl_doc_add_canvas_template (fdl_doc_t *doc, const char *id, const char *label, int64_t target_w, int64_t target_h, double target_squeeze, fdl_geometry_path_t fit_source, fdl_fit_method_t fit_method, fdl_halign_t halign, fdl_valign_t valign, fdl_round_strategy_t rounding)
	Add a canvas template to the document.
void	fdl_canvas_template_set_preserve_from_source_canvas (fdl_canvas_template_t *ct, fdl_geometry_path_t path)
	Set preserve_from_source_canvas on a canvas template.
void	fdl_canvas_template_set_maximum_dimensions (fdl_canvas_template_t *ct, fdl_dimensions_i64_t dims)
	Set maximum_dimensions on a canvas template.
void	fdl_canvas_template_set_pad_to_maximum (fdl_canvas_template_t *ct, int pad)
	Set pad_to_maximum flag on a canvas template.
void	fdl_framing_intent_set_aspect_ratio (fdl_framing_intent_t *fi, fdl_dimensions_i64_t dims)
	Set aspect ratio on a framing intent.
void	fdl_framing_intent_set_protection (fdl_framing_intent_t *fi, double protection)
	Set protection factor on a framing intent.
void	fdl_canvas_set_dimensions (fdl_canvas_t *canvas, fdl_dimensions_i64_t dims)
	Set dimensions on a canvas.
void	fdl_canvas_set_anamorphic_squeeze (fdl_canvas_t *canvas, double squeeze)
	Set anamorphic squeeze on a canvas.
void	fdl_canvas_set_effective_dims_only (fdl_canvas_t *canvas, fdl_dimensions_i64_t dims)
	Set effective dimensions on a canvas.
void	fdl_canvas_remove_effective (fdl_canvas_t *canvas)
	Remove effective dimensions and anchor from a canvas.
void	fdl_framing_decision_set_dimensions (fdl_framing_decision_t *fd, fdl_dimensions_f64_t dims)
	Set dimensions on a framing decision.
void	fdl_framing_decision_set_anchor_point (fdl_framing_decision_t *fd, fdl_point_f64_t point)
	Set anchor point on a framing decision.
void	fdl_framing_decision_set_protection_dimensions (fdl_framing_decision_t *fd, fdl_dimensions_f64_t dims)
	Set protection dimensions on a framing decision (without changing anchor).
void	fdl_framing_decision_set_protection_anchor_point (fdl_framing_decision_t *fd, fdl_point_f64_t point)
	Set protection anchor point on a framing decision (without changing dimensions).
void	fdl_framing_decision_remove_protection (fdl_framing_decision_t *fd)
	Remove protection dimensions and anchor from a framing decision.
const char *	fdl_clip_id_validate_json (const char *json_str, size_t json_len)
	Validate clip_id JSON for mutual exclusion (file vs sequence).
const char *	fdl_context_set_clip_id_json (fdl_context_t *ctx, const char *json_str, size_t json_len)
	Set clip_id on a context from a JSON string.
void	fdl_context_remove_clip_id (fdl_context_t *ctx)
	Remove clip_id from a context.

Detailed Description

C ABI wrappers for the document builder (create, add, set, remove operations).

Function Documentation

fdl_doc_set_uuid()

void fdl_doc_set_uuid	(	fdl_doc_t *	doc,
		const char *	uuid
	)

Set the UUID on a document.

Parameters

doc	Document handle.
uuid	New UUID string.

fdl_doc_set_fdl_creator()

void fdl_doc_set_fdl_creator	(	fdl_doc_t *	doc,
		const char *	creator
	)

Set the fdl_creator on a document.

Parameters

doc	Document handle.
creator	New creator string.

fdl_doc_set_default_framing_intent()

void fdl_doc_set_default_framing_intent	(	fdl_doc_t *	doc,
		const char *	fi_id
	)

Set the default_framing_intent on a document.

Parameters

doc	Document handle.
fi_id	Framing intent ID, or NULL to clear.

fdl_doc_set_version()

void fdl_doc_set_version	(	fdl_doc_t *	doc,
		int	major,
		int	minor
	)

Set the FDL version on a document.

Parameters

doc	Document handle.
major	Version major number.
minor	Version minor number.

fdl_doc_create_with_header()

fdl_doc_t * fdl_doc_create_with_header	(	const char *	uuid,
		int	version_major,
		int	version_minor,
		const char *	fdl_creator,
		const char *	default_framing_intent
	)

Create a new FDL document with header fields and empty collections.

Parameters

uuid	Document UUID.
version_major	FDL version major number.
version_minor	FDL version minor number.
fdl_creator	Creator identifier string.
default_framing_intent	Default framing intent ID, or NULL.

Returns

New document handle. Caller owns — free with fdl_doc_free().

fdl_doc_add_framing_intent()

fdl_framing_intent_t * fdl_doc_add_framing_intent	(	fdl_doc_t *	doc,
		const char *	id,
		const char *	label,
		int64_t	aspect_w,
		int64_t	aspect_h,
		double	protection
	)

Add a framing intent to the document.

Parameters

doc	Document handle.
id	Framing intent ID.
label	Display label.
aspect_w	Aspect ratio width component.
aspect_h	Aspect ratio height component.
protection	Protection factor (0.0 for no protection).

Returns

Handle to the new framing intent (owned by doc).

fdl_doc_add_context()

fdl_context_t * fdl_doc_add_context	(	fdl_doc_t *	doc,
		const char *	label,
		const char *	context_creator
	)

Add a context to the document.

Parameters

doc	Document handle.
label	Context label.
context_creator	Creator identifier string.

Returns

Handle to the new context (owned by doc).

fdl_context_add_canvas()

fdl_canvas_t * fdl_context_add_canvas	(	fdl_context_t *	ctx,
		const char *	id,
		const char *	label,
		const char *	source_canvas_id,
		int64_t	dim_w,
		int64_t	dim_h,
		double	squeeze
	)

Add a canvas to a context.

Parameters

ctx	Context handle.
id	Canvas ID.
label	Display label.
source_canvas_id	Source canvas ID (for derived canvases; equals id for originals).
dim_w	Canvas width in pixels.
dim_h	Canvas height in pixels.
squeeze	Anamorphic squeeze factor (1.0 for non-anamorphic).

Returns

Handle to the new canvas (owned by doc).

fdl_canvas_set_effective_dimensions()

void fdl_canvas_set_effective_dimensions	(	fdl_canvas_t *	canvas,
		fdl_dimensions_i64_t	dims,
		fdl_point_f64_t	anchor
	)

Set effective dimensions and anchor on a canvas.

Parameters

canvas	Canvas handle.
dims	Effective dimensions.
anchor	Effective anchor point.

fdl_canvas_set_photosite_dimensions()

void fdl_canvas_set_photosite_dimensions	(	fdl_canvas_t *	canvas,
		fdl_dimensions_i64_t	dims
	)

Set photosite dimensions on a canvas.

Parameters

canvas	Canvas handle.
dims	Photosite (sensor) dimensions.

fdl_canvas_set_physical_dimensions()

void fdl_canvas_set_physical_dimensions	(	fdl_canvas_t *	canvas,
		fdl_dimensions_f64_t	dims
	)

Set physical dimensions on a canvas.

Parameters

canvas	Canvas handle.
dims	Physical dimensions (e.g. millimeters on sensor).

fdl_canvas_add_framing_decision()

fdl_framing_decision_t * fdl_canvas_add_framing_decision	(	fdl_canvas_t *	canvas,
		const char *	id,
		const char *	label,
		const char *	framing_intent_id,
		double	dim_w,
		double	dim_h,
		double	anchor_x,
		double	anchor_y
	)

Add a framing decision to a canvas.

Parameters

canvas	Canvas handle.
id	Framing decision ID.
label	Display label.
framing_intent_id	ID of the framing intent this decision implements.
dim_w	Framing width.
dim_h	Framing height.
anchor_x	Anchor x-coordinate.
anchor_y	Anchor y-coordinate.

Returns

Handle to the new framing decision (owned by doc).

fdl_framing_decision_set_protection()

void fdl_framing_decision_set_protection	(	fdl_framing_decision_t *	fd,
		fdl_dimensions_f64_t	dims,
		fdl_point_f64_t	anchor
	)

Set protection dimensions and anchor on a framing decision.

Parameters

fd	Framing decision handle.
dims	Protection dimensions.
anchor	Protection anchor point.

fdl_doc_add_canvas_template()

fdl_canvas_template_t * fdl_doc_add_canvas_template	(	fdl_doc_t *	doc,
		const char *	id,
		const char *	label,
		int64_t	target_w,
		int64_t	target_h,
		double	target_squeeze,
		fdl_geometry_path_t	fit_source,
		fdl_fit_method_t	fit_method,
		fdl_halign_t	halign,
		fdl_valign_t	valign,
		fdl_round_strategy_t	rounding
	)

Add a canvas template to the document.

Parameters

doc	Document handle.
id	Canvas template ID.
label	Display label.
target_w	Target width in pixels.
target_h	Target height in pixels.
target_squeeze	Target anamorphic squeeze factor.
fit_source	Geometry path to scale from.
fit_method	How source is scaled into target.
halign	Horizontal alignment.
valign	Vertical alignment.
rounding	Rounding strategy.

Returns

Handle to the new canvas template (owned by doc).

fdl_canvas_template_set_preserve_from_source_canvas()

void fdl_canvas_template_set_preserve_from_source_canvas	(	fdl_canvas_template_t *	ct,
		fdl_geometry_path_t	path
	)

Set preserve_from_source_canvas on a canvas template.

Parameters

ct	Canvas template handle.
path	Geometry path to preserve from the source canvas.

fdl_canvas_template_set_maximum_dimensions()

void fdl_canvas_template_set_maximum_dimensions	(	fdl_canvas_template_t *	ct,
		fdl_dimensions_i64_t	dims
	)

Set maximum_dimensions on a canvas template.

Parameters

ct	Canvas template handle.
dims	Maximum allowed output dimensions.

fdl_canvas_template_set_pad_to_maximum()

void fdl_canvas_template_set_pad_to_maximum	(	fdl_canvas_template_t *	ct,
		int	pad
	)

Set pad_to_maximum flag on a canvas template.

Parameters

ct	Canvas template handle.
pad	FDL_TRUE to pad output to maximum dimensions, FDL_FALSE otherwise.

fdl_framing_intent_set_aspect_ratio()

void fdl_framing_intent_set_aspect_ratio	(	fdl_framing_intent_t *	fi,
		fdl_dimensions_i64_t	dims
	)

Set aspect ratio on a framing intent.

Parameters

fi	Framing intent handle.
dims	Aspect ratio as integer width:height (e.g. {16, 9}).

fdl_framing_intent_set_protection()

void fdl_framing_intent_set_protection	(	fdl_framing_intent_t *	fi,
		double	protection
	)

Set protection factor on a framing intent.

Parameters

fi	Framing intent handle.
protection	Protection factor (0.0 for no protection).

fdl_canvas_set_dimensions()

void fdl_canvas_set_dimensions	(	fdl_canvas_t *	canvas,
		fdl_dimensions_i64_t	dims
	)

Set dimensions on a canvas.

Parameters

canvas	Canvas handle.
dims	New canvas dimensions.

fdl_canvas_set_anamorphic_squeeze()

void fdl_canvas_set_anamorphic_squeeze	(	fdl_canvas_t *	canvas,
		double	squeeze
	)

Set anamorphic squeeze on a canvas.

Parameters

canvas	Canvas handle.
squeeze	New anamorphic squeeze factor.

fdl_canvas_set_effective_dims_only()

void fdl_canvas_set_effective_dims_only	(	fdl_canvas_t *	canvas,
		fdl_dimensions_i64_t	dims
	)

Set effective dimensions on a canvas.

Creates anchor at {0, 0} if effective anchor is not already set.

Parameters

canvas	Canvas handle.
dims	Effective dimensions.

fdl_canvas_remove_effective()

void fdl_canvas_remove_effective

(

fdl_canvas_t *

canvas

)

Remove effective dimensions and anchor from a canvas.

Parameters

canvas

Canvas handle.

fdl_framing_decision_set_dimensions()

void fdl_framing_decision_set_dimensions	(	fdl_framing_decision_t *	fd,
		fdl_dimensions_f64_t	dims
	)

Set dimensions on a framing decision.

Parameters

fd	Framing decision handle.
dims	New framing dimensions.

fdl_framing_decision_set_anchor_point()

void fdl_framing_decision_set_anchor_point	(	fdl_framing_decision_t *	fd,
		fdl_point_f64_t	point
	)

Set anchor point on a framing decision.

Parameters

fd	Framing decision handle.
point	New anchor point.

fdl_framing_decision_set_protection_dimensions()

void fdl_framing_decision_set_protection_dimensions	(	fdl_framing_decision_t *	fd,
		fdl_dimensions_f64_t	dims
	)

Set protection dimensions on a framing decision (without changing anchor).

Parameters

fd	Framing decision handle.
dims	New protection dimensions.

fdl_framing_decision_set_protection_anchor_point()

void fdl_framing_decision_set_protection_anchor_point	(	fdl_framing_decision_t *	fd,
		fdl_point_f64_t	point
	)

Set protection anchor point on a framing decision (without changing dimensions).

Parameters

fd	Framing decision handle.
point	New protection anchor point.

fdl_framing_decision_remove_protection()

void fdl_framing_decision_remove_protection

(

fdl_framing_decision_t *

fd

)

Remove protection dimensions and anchor from a framing decision.

Parameters

fd	Framing decision handle.

fdl_clip_id_validate_json()

const char * fdl_clip_id_validate_json	(	const char *	json_str,
		size_t	json_len
	)

Validate clip_id JSON for mutual exclusion (file vs sequence).

Parameters

json_str	JSON string to validate.
json_len	Length of json_str in bytes.

Returns

NULL if valid, or heap-allocated error string on failure. Caller frees error with fdl_free().

< POSIX strdup.

< POSIX strdup.

< POSIX strdup.

< POSIX strdup.

fdl_context_set_clip_id_json()

const char * fdl_context_set_clip_id_json	(	fdl_context_t *	ctx,
		const char *	json_str,
		size_t	json_len
	)

Set clip_id on a context from a JSON string.

Validates mutual exclusion (file vs sequence) before setting.

Parameters

ctx	Context handle.
json_str	JSON string representing the clip_id object.
json_len	Length of json_str in bytes.

Returns

NULL on success, or heap-allocated error string on failure. Caller frees error with fdl_free().

< POSIX strdup.

< POSIX strdup.

< POSIX strdup.

fdl_context_remove_clip_id()

void fdl_context_remove_clip_id

(

fdl_context_t *

ctx

)

Remove clip_id from a context.

Safe to call if not present.

Parameters

ctx	Context handle.