query.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_screen_box
struct	mln_screen_line_string
union	mln_rendered_query_geometry_data
struct	mln_rendered_query_geometry
struct	mln_rendered_feature_query_options
struct	mln_source_feature_query_options
struct	mln_rendered_feature
struct	mln_source_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 union mln_rendered_query_geometry_data	mln_rendered_query_geometry_data
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_rendered_feature_field	mln_rendered_feature_field
typedef struct mln_rendered_feature	mln_rendered_feature
typedef enum mln_source_feature_field	mln_source_feature_field
typedef struct mln_source_feature	mln_source_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_rendered_feature_field : uint32_t
enum	mln_source_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_status	mln_render_session_query_rendered_features (mln_render_session session, const mln_rendered_query_geometry *geometry, const mln_rendered_feature_query_options *options, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status	mln_render_session_query_source_features (mln_render_session session, mln_buffer_view source_id, const mln_source_feature_query_options *options, const mln_completion *completion, mln_diagnostic *out_diagnostic)
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, const mln_completion *completion, mln_diagnostic *out_diagnostic)

Detailed Description

Public C API declarations for feature queries.

Query inputs are copied before return. Caller-driver queries complete only after the host services driver work on the graphics thread. Core-worker queries need no host service.

Typedef Documentation

mln_rendered_feature

typedef struct mln_rendered_feature mln_rendered_feature

One rendered-feature query hit borrowed for a completion callback.

Every view is valid only for that callback; copy what the host keeps. feature is one UTF-8 GeoJSON Feature, and layer_id is the style layer that rendered it. A feature that several style layers render yields one hit per layer. source_id, source_layer_id, and state are present when the matching field bit is set; a layer without a source, such as a location indicator, has no source_id. state is a UTF-8 JSON object.

mln_rendered_feature_field

typedef enum mln_rendered_feature_field mln_rendered_feature_field

Optional fields for mln_rendered_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_data

typedef union mln_rendered_query_geometry_data mln_rendered_query_geometry_data

Screen-space query geometry data.

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

typedef struct mln_source_feature mln_source_feature

One source-feature query hit borrowed for a completion callback.

Every view is valid only for that callback; copy what the host keeps. feature is one UTF-8 GeoJSON Feature. source_layer_id names the vector source layer the feature came from, and is present when its field bit is set; a source without source layers, such as GeoJSON, has none.

mln_source_feature_field

typedef enum mln_source_feature_field mln_source_feature_field

Optional fields for mln_source_feature.

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_rendered_feature_field

enum mln_rendered_feature_field : uint32_t

Optional fields for mln_rendered_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_field

enum mln_source_feature_field : uint32_t

Optional fields for mln_source_feature.

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_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,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts a feature-extension query against the latest driver state. The completion borrows one mln_buffer_view holding UTF-8 JSON (value_count 1), valid only for the callback.

For the supercluster extension, the feature's cluster_id property and the limit and offset arguments are nonnegative JSON integers, such as 5 rather than 5.0. A feature without such a cluster_id yields an empty result. Leaves use a limit of 10 unless the arguments supply one, and apply an offset only with a limit.

Returns:

• MLN_STATUS_OK when the query is accepted.
• MLN_STATUS_INVALID_ARGUMENT when session is an invalid handle, any of source_id, feature, extension, or extension_field is invalid or empty, arguments is invalid, or completion is invalid.
• MLN_STATUS_INVALID_STATE when session has been released or is not attached.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_TARGET_LOST when the session is abandoned or its target is lost before the query runs.
• MLN_STATUS_NATIVE_ERROR when the query fails.

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,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts a rendered-feature query against the session's latest driver state.

The query reads the last frame that the session rendered, so render after a camera or style change for a result that matches it. The completion borrows value_count mln_rendered_feature values, value_size bytes apart.

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 when the query is accepted.
• MLN_STATUS_INVALID_ARGUMENT when session is an invalid handle, geometry is null, undersized, or names an unknown kind, options is undersized or carries an invalid field, or completion is invalid.
• MLN_STATUS_INVALID_STATE when session has been released or is not attached.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_TARGET_LOST when the session is abandoned or its target is lost before the query runs.
• MLN_STATUS_NATIVE_ERROR when the query fails.

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,
		const mln_completion *	completion,
		mln_diagnostic *	out_diagnostic )

Starts a source-feature query against the session's latest driver state.

The query covers only the tiles that the source loaded for rendering, and a source loads tiles only while a visible layer uses it. The completion borrows value_count mln_source_feature values, value_size bytes apart.

Returns:

• MLN_STATUS_OK when the query is accepted.
• MLN_STATUS_INVALID_ARGUMENT when session is an invalid handle, source_id is invalid or empty, options is undersized or carries an invalid field, or completion is invalid.
• MLN_STATUS_INVALID_STATE when session has been released or is not attached.
• MLN_STATUS_NATIVE_ERROR when native code fails.

Completes with:

• MLN_STATUS_TARGET_LOST when the session is abandoned or its target is lost before the query runs.
• MLN_STATUS_NATIVE_ERROR when the query fails.

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_source_feature_query_options_default()

mln_source_feature_query_options mln_source_feature_query_options_default

(

void

)

Returns default source feature query options.