query.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_screen_box
struct	mln_screen_line_string
struct	mln_rendered_query_geometry
struct	mln_rendered_feature_query_options
struct	mln_source_feature_query_options
struct	mln_queried_feature

Typedefs
typedef enum mln_rendered_query_geometry_type	mln_rendered_query_geometry_type
typedef struct mln_screen_box	mln_screen_box
typedef struct mln_screen_line_string	mln_screen_line_string
typedef struct mln_rendered_query_geometry	mln_rendered_query_geometry
typedef enum mln_rendered_feature_query_option_field	mln_rendered_feature_query_option_field
typedef struct mln_rendered_feature_query_options	mln_rendered_feature_query_options
typedef enum mln_source_feature_query_option_field	mln_source_feature_query_option_field
typedef struct mln_source_feature_query_options	mln_source_feature_query_options
typedef enum mln_queried_feature_field	mln_queried_feature_field
typedef struct mln_queried_feature	mln_queried_feature

Enumerations
enum	mln_rendered_query_geometry_type : uint32_t
enum	mln_rendered_feature_query_option_field : uint32_t
enum	mln_source_feature_query_option_field : uint32_t
enum	mln_queried_feature_field : uint32_t

Functions
mln_rendered_feature_query_options	mln_rendered_feature_query_options_default (void)
mln_source_feature_query_options	mln_source_feature_query_options_default (void)
mln_rendered_query_geometry	mln_rendered_query_geometry_point (mln_screen_point point)
mln_rendered_query_geometry	mln_rendered_query_geometry_box (mln_screen_box box)
mln_rendered_query_geometry	mln_rendered_query_geometry_line_string (const mln_screen_point *points, size_t point_count)
mln_queried_feature	mln_queried_feature_default (void)
mln_status	mln_queried_feature_list_count (mln_queried_feature_list list, size_t *out_count)
mln_status	mln_queried_feature_list_get (mln_queried_feature_list list, size_t index, mln_queried_feature *out_feature)
void	mln_queried_feature_list_destroy (mln_queried_feature_list list)
mln_status	mln_render_session_query_rendered_features (mln_render_session session, const mln_rendered_query_geometry *geometry, const mln_rendered_feature_query_options *options, mln_queried_feature_list *out_result)
mln_status	mln_render_session_query_source_features (mln_render_session session, mln_buffer_view source_id, const mln_source_feature_query_options *options, mln_queried_feature_list *out_result)
mln_status	mln_render_session_query_feature_extensions (mln_render_session session, mln_buffer_view source_id, mln_buffer_view feature, mln_buffer_view extension, mln_buffer_view extension_field, const mln_buffer_view *arguments, mln_buffer *out_result)

Detailed Description

Public C API declarations for feature queries.

Typedef Documentation

mln_queried_feature

typedef struct mln_queried_feature mln_queried_feature

One query hit borrowed from a queried-feature list.

Views remain valid until the owner list is destroyed. feature is one UTF-8 GeoJSON Feature. source_id, source_layer_id, and state are present when the matching field bit is set. state is a UTF-8 JSON object.

mln_queried_feature_field

typedef enum mln_queried_feature_field mln_queried_feature_field

Optional fields for mln_queried_feature.

mln_rendered_feature_query_option_field

typedef enum mln_rendered_feature_query_option_field mln_rendered_feature_query_option_field

Optional fields for mln_rendered_feature_query_options.

mln_rendered_feature_query_options

typedef struct mln_rendered_feature_query_options mln_rendered_feature_query_options

Options for rendered feature queries.

mln_rendered_query_geometry

typedef struct mln_rendered_query_geometry mln_rendered_query_geometry

Rendered feature query geometry descriptor.

mln_rendered_query_geometry_type

typedef enum mln_rendered_query_geometry_type mln_rendered_query_geometry_type

Rendered feature query geometry variants.

mln_screen_box

typedef struct mln_screen_box mln_screen_box

Screen-space box in logical map pixels.

Corners may be given in any order and may extend past the viewport. Rendered queries normalize the corners and clip the box to the viewport.

mln_screen_line_string

typedef struct mln_screen_line_string mln_screen_line_string

Screen-space line string in logical map pixels.

mln_source_feature_query_option_field

typedef enum mln_source_feature_query_option_field mln_source_feature_query_option_field

Optional fields for mln_source_feature_query_options.

mln_source_feature_query_options

typedef struct mln_source_feature_query_options mln_source_feature_query_options

Options for source feature queries.

Enumeration Type Documentation

mln_queried_feature_field

enum mln_queried_feature_field : uint32_t

Optional fields for mln_queried_feature.

mln_rendered_feature_query_option_field

enum mln_rendered_feature_query_option_field : uint32_t

Optional fields for mln_rendered_feature_query_options.

mln_rendered_query_geometry_type

enum mln_rendered_query_geometry_type : uint32_t

Rendered feature query geometry variants.

mln_source_feature_query_option_field

enum mln_source_feature_query_option_field : uint32_t

Optional fields for mln_source_feature_query_options.

Function Documentation

mln_queried_feature_default()

mln_queried_feature mln_queried_feature_default

(

void

)

Returns a default queried-feature descriptor.

mln_queried_feature_list_count()

mln_status mln_queried_feature_list_count	(	mln_queried_feature_list	list,
		size_t *	out_count )

Gets the number of hits in a queried-feature list handle.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when list is null or not live, or out_count is null.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_queried_feature_list_destroy()

void mln_queried_feature_list_destroy

(

mln_queried_feature_list

list

)

Destroys a queried-feature list handle. Null is accepted as a no-op.

mln_queried_feature_list_get()

mln_status mln_queried_feature_list_get	(	mln_queried_feature_list	list,
		size_t	index,
		mln_queried_feature *	out_feature )

Borrows one queried feature from a list handle.

On success, *out_feature receives views into list-owned storage. The views remain valid until the list is destroyed. out_feature->size must be at least sizeof(mln_queried_feature).

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when list is null or not live, index is out of range, out_feature is null, or out_feature->size is too small.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_render_session_query_feature_extensions()

mln_status mln_render_session_query_feature_extensions	(	mln_render_session	session,
		mln_buffer_view	source_id,
		mln_buffer_view	feature,
		mln_buffer_view	extension,
		mln_buffer_view	extension_field,
		const mln_buffer_view *	arguments,
		mln_buffer *	out_result )

Queries a feature extension from the latest render session state.

The session renderer must already exist. source_id, feature, extension, extension_field, and arguments are borrowed for the duration of the call. feature contains one UTF-8 GeoJSON Feature. arguments may be null; when present, it contains a UTF-8 JSON object. On success, *out_result receives an owned buffer containing either a JSON value or a GeoJSON Feature Collection. Destroy it with mln_buffer_destroy().

The "supercluster" extension requires "cluster_id" feature properties and "limit" and "offset" arguments to be nonnegative integer JSON literals. Floating-point or negative representations are treated as absent and still produce MLN_STATUS_OK. An absent cluster ID produces JSON null. Absent limit and offset values use the native defaults of ten leaves at offset zero. The result buffer preserves integer JSON representations.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when session is null or not live, source_id, feature, extension, extension_field, or arguments are invalid, out_result is null, or *out_result is not null.
• MLN_STATUS_INVALID_STATE when the session is detached or no renderer has been created for the session yet.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
• MLN_STATUS_NATIVE_ERROR when the render backend reports no renderer backend, or when an internal exception is converted to status.

mln_render_session_query_rendered_features()

mln_status mln_render_session_query_rendered_features	(	mln_render_session	session,
		const mln_rendered_query_geometry *	geometry,
		const mln_rendered_feature_query_options *	options,
		mln_queried_feature_list *	out_result )

Queries rendered features from the latest render session state.

The session renderer must already exist. geometry and options are borrowed for the duration of the call. Passing null for options uses default options. On success, *out_result receives an owned queried-feature list. Destroy it with mln_queried_feature_list_destroy().

Box geometry is normalized and clipped to the viewport, so a box that over-covers the viewport queries everything visible. A box that lies entirely outside the viewport yields an empty result. Point and line-string geometry are queried as given.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when session is null or not live, geometry is null or invalid, options are invalid, out_result is null, or *out_result is not null.
• MLN_STATUS_INVALID_STATE when the session is detached or no renderer has been created for the session yet.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
• MLN_STATUS_NATIVE_ERROR when the render backend reports no renderer backend, or when an internal exception is converted to status.

mln_render_session_query_source_features()

mln_status mln_render_session_query_source_features	(	mln_render_session	session,
		mln_buffer_view	source_id,
		const mln_source_feature_query_options *	options,
		mln_queried_feature_list *	out_result )

Queries source features from the latest render session state.

The session renderer must already exist. source_id and options are borrowed for the duration of the call. Passing null for options uses default options. On success, *out_result receives an owned queried-feature list. Destroy it with mln_queried_feature_list_destroy().

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when session is null or not live, source_id is invalid or empty, options are invalid, out_result is null, or *out_result is not null.
• MLN_STATUS_INVALID_STATE when the session is detached or no renderer has been created for the session yet.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the session owner thread.
• MLN_STATUS_NATIVE_ERROR when the render backend reports no renderer backend, or when an internal exception is converted to status.

mln_rendered_feature_query_options_default()

mln_rendered_feature_query_options mln_rendered_feature_query_options_default

(

void

)

Returns default rendered feature query options.

mln_rendered_query_geometry_box()

mln_rendered_query_geometry mln_rendered_query_geometry_box

(

mln_screen_box

box

)

Returns a rendered box query geometry descriptor.

mln_rendered_query_geometry_line_string()

mln_rendered_query_geometry mln_rendered_query_geometry_line_string	(	const mln_screen_point *	points,
		size_t	point_count )

Returns a rendered line-string query geometry descriptor.

mln_rendered_query_geometry_point()

mln_rendered_query_geometry mln_rendered_query_geometry_point

(

mln_screen_point

point

)

Returns a rendered point query geometry descriptor.

mln_source_feature_query_options_default()

mln_source_feature_query_options mln_source_feature_query_options_default

(

void

)

Returns default source feature query options.