field_patch.h File Reference

Shared index-space field patch descriptors and zero-copy patch views. More...

#include "sim_buffer.h"
#include <stdbool.h>
#include <stddef.h>

Include dependency graph for field_patch.h:

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

Go to the source code of this file.

Classes
struct	SimFieldPatch
	Rectangular non-empty region of a 2D field index space. More...
struct	SimFieldPatchView
	Zero-copy view over a field patch. More...

Typedefs
typedef struct SimFieldPatch	SimFieldPatch
	Rectangular non-empty region of a 2D field index space.
typedef struct SimFieldPatchView	SimFieldPatchView
	Zero-copy view over a field patch.
typedef SimResult(*	SimFieldPatchRowIterFn) (size_t row_index, void *row_data, size_t row_length, void *userdata)
	Row callback used by sim_field_patch_iter_rows().

Enumerations
enum	{ SIM_FIELD_PATCH_FLAG_NONE = 0u , SIM_FIELD_PATCH_FLAG_COVERS_FULL_ROWS = 1u << 0 , SIM_FIELD_PATCH_FLAG_IS_FULL_FIELD = 1u << 1 , SIM_FIELD_PATCH_FLAG_TOUCHES_BOUNDARY = 1u << 2 }

Functions
bool	sim_field_patch_is_valid (const SimFieldPatch *patch)
	Validate patch bounds, dimensions, and source-field extents.
SimResult	sim_field_patch_full (size_t field_width, size_t field_height, SimFieldPatch *out_patch)
	Construct a patch covering a complete field.
SimResult	sim_field_patch_from_xywh (size_t field_width, size_t field_height, size_t x0, size_t y0, size_t width, size_t height, SimFieldPatch *out_patch)
	Construct a patch from x/y origin and width/height extents.
bool	sim_field_patch_intersect (const SimFieldPatch *lhs, const SimFieldPatch *rhs, SimFieldPatch *out_patch)
	Intersect two patches from the same field.
SimResult	sim_field_patch_from_normalized_region (size_t field_width, size_t field_height, double min_x, double min_y, double max_x, double max_y, SimFieldPatch *out_patch)
	Construct a patch from normalized [0, 1] coordinate bounds.
bool	sim_field_patch_view_is_valid (const SimFieldPatchView *view)
	Validate a patch view and its backing buffer-view layout.
SimResult	sim_field_patch_view_from_field (SimField *field, const SimFieldPatch *patch, bool readonly, SimFieldPatchView *out_view)
	Create a zero-copy view over a patch of a row-major field.
SimResult	sim_field_patch_iter_rows (const SimFieldPatchView *view, SimFieldPatchRowIterFn row_fn, void *userdata)
	Iterate physical rows in a patch view.
size_t	sim_field_patch_split_tiles (const SimFieldPatch *patch, size_t tile_width, size_t tile_height, SimFieldPatch *out_tiles, size_t out_capacity)
	Split a patch into row-major tiles.

Detailed Description

Shared index-space field patch descriptors and zero-copy patch views.

A patch is a non-empty rectangle in the fastest two axes of a SimField, using x/y coordinates and half-open extents. Views expose patch storage through a SimBufferView and are zero-copy when the source field has a supported row-major layout.

Typedef Documentation

SimFieldPatchRowIterFn

typedef SimResult(* SimFieldPatchRowIterFn) (size_t row_index, void *row_data, size_t row_length, void *userdata)

Row callback used by sim_field_patch_iter_rows().

Parameters

row_index	Zero-based row number within the patch view.
row_data	Pointer to the first element of the row.
row_length	Number of elements in the row.
userdata	Caller-provided context pointer.

Returns

SIM_RESULT_OK to continue, or any other result to stop iteration.

SimFieldPatchView

typedef struct SimFieldPatchView SimFieldPatchView

Zero-copy view over a field patch.

The buffer view points into the source field's storage. The shape/stride storage arrays are owned by the view struct and back buffer_view.layout.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
SIM_FIELD_PATCH_FLAG_NONE	No derived patch property.
SIM_FIELD_PATCH_FLAG_COVERS_FULL_ROWS	Patch spans x across full rows.
SIM_FIELD_PATCH_FLAG_IS_FULL_FIELD	Patch covers the complete field.
SIM_FIELD_PATCH_FLAG_TOUCHES_BOUNDARY	Patch touches at least one field edge.

Function Documentation

sim_field_patch_from_normalized_region()

SimResult sim_field_patch_from_normalized_region	(	size_t	field_width,
		size_t	field_height,
		double	min_x,
		double	min_y,
		double	max_x,
		double	max_y,
		SimFieldPatch *	out_patch
	)

Construct a patch from normalized [0, 1] coordinate bounds.

Bounds are clamped to [0, 1], min values use floor(), and max values use ceil() so non-empty continuous regions cover all touched samples.

Parameters

	field_width	Source field width; must be nonzero.
	field_height	Source field height; must be nonzero.
	min_x	Normalized left bound.
	min_y	Normalized top bound.
	max_x	Normalized right bound; must be greater than min_x after clamping.
	max_y	Normalized bottom bound; must be greater than min_y after clamping.
[out]	out_patch	Receives the patch descriptor.

Returns

SIM_RESULT_OK or SIM_RESULT_INVALID_ARGUMENT.

sim_field_patch_from_xywh()

SimResult sim_field_patch_from_xywh	(	size_t	field_width,
		size_t	field_height,
		size_t	x0,
		size_t	y0,
		size_t	width,
		size_t	height,
		SimFieldPatch *	out_patch
	)

Construct a patch from x/y origin and width/height extents.

Parameters

	field_width	Source field width; must be nonzero.
	field_height	Source field height; must be nonzero.
	x0	Left coordinate, in [0, field_width).
	y0	Top coordinate, in [0, field_height).
	width	Patch width; must be nonzero and fit inside the field.
	height	Patch height; must be nonzero and fit inside the field.
[out]	out_patch	Receives the normalized patch descriptor.

Returns

SIM_RESULT_OK or SIM_RESULT_INVALID_ARGUMENT.

sim_field_patch_full()

SimResult sim_field_patch_full	(	size_t	field_width,
		size_t	field_height,
		SimFieldPatch *	out_patch
	)

Construct a patch covering a complete field.

Parameters

	field_width	Source field width; must be nonzero.
	field_height	Source field height; must be nonzero.
[out]	out_patch	Receives the patch descriptor.

Returns

SIM_RESULT_OK or SIM_RESULT_INVALID_ARGUMENT.

sim_field_patch_intersect()

bool sim_field_patch_intersect	(	const SimFieldPatch *	lhs,
		const SimFieldPatch *	rhs,
		SimFieldPatch *	out_patch
	)

Intersect two patches from the same field.

Parameters

	lhs	First patch.
	rhs	Second patch.
[out]	out_patch	Optional receiver for the intersection patch.

Returns

true when the patches are valid, share extents, and overlap.

sim_field_patch_is_valid()

bool sim_field_patch_is_valid

(

const SimFieldPatch *

patch

)

Validate patch bounds, dimensions, and source-field extents.

Parameters

patch

Patch descriptor to inspect.

Returns

true when the patch is non-empty and lies within its field.

sim_field_patch_iter_rows()

SimResult sim_field_patch_iter_rows	(	const SimFieldPatchView *	view,
		SimFieldPatchRowIterFn	row_fn,
		void *	userdata
	)

Iterate physical rows in a patch view.

Parameters

view	Valid patch view.
row_fn	Callback invoked once per row.
userdata	Caller data passed to row_fn.

Returns

SIM_RESULT_OK when all rows complete, or the first callback error.

sim_field_patch_split_tiles()

size_t sim_field_patch_split_tiles	(	const SimFieldPatch *	patch,
		size_t	tile_width,
		size_t	tile_height,
		SimFieldPatch *	out_tiles,
		size_t	out_capacity
	)

Split a patch into row-major tiles.

Tile dimensions of zero, or larger than the patch, collapse to the full patch dimension. Passing out_tiles NULL lets callers query the required tile count.

Parameters

	patch	Patch to split.
	tile_width	Requested tile width.
	tile_height	Requested tile height.
[out]	out_tiles	Optional array receiving up to out_capacity tiles.
	out_capacity	Number of entries available in out_tiles.

Returns

Total number of tiles required, or 0 when patch is invalid.

sim_field_patch_view_from_field()

SimResult sim_field_patch_view_from_field	(	SimField *	field,
		const SimFieldPatch *	patch,
		bool	readonly,
		SimFieldPatchView *	out_view
	)

Create a zero-copy view over a patch of a row-major field.

Supports one- and two-dimensional row-major fields whose fastest axis has unit stride. The resulting view points into field storage and is invalid after the field is destroyed or reallocated.

Parameters

	field	Source field to view.
	patch	Valid patch matching the field width and height.
	readonly	Advisory flag stored in the view for callers.
[out]	out_view	Receives the view descriptor.

Returns

SIM_RESULT_OK, SIM_RESULT_INVALID_ARGUMENT, SIM_RESULT_NOT_SUPPORTED, or SIM_RESULT_INVALID_STATE.

sim_field_patch_view_is_valid()

bool sim_field_patch_view_is_valid

(

const SimFieldPatchView *

view

)

Validate a patch view and its backing buffer-view layout.

Parameters

view	View descriptor to inspect.

Returns

true when the view references a valid patch and matching buffer view.