Convenience wrappers and C++ templates for driving wx_bgi from an OpenLB-style live loop and for materializing DDS scene geometry into an olb::SuperGeometry. More...

#include "wx_bgi.h"
#include "wx_bgi_ext.h"

Include dependency graph for wx_bgi_openlb.h:

Go to the source code of this file.

Functions
BGI_API int BGI_CALL	wxbgi_openlb_classify_point_material (float x, float y, float z, int defaultFluidMaterial, int defaultSolidMaterial, int *outMatched)
	Classify a single physical-space point against the active DDS scene and return the associated OpenLB material ID.

BGI_API int BGI_CALL	wxbgi_openlb_sample_materials_2d (float minX, float minY, float z, int cols, int rows, float stepX, float stepY, int defaultFluidMaterial, int defaultSolidMaterial, int *outMaterials, int materialCount)
	Sample a 2-D axis-aligned grid of physical points against the active DDS scene and write per-cell material IDs into a caller-supplied array.

Detailed Description

Convenience wrappers and C++ templates for driving wx_bgi from an OpenLB-style live loop and for materializing DDS scene geometry into an olb::SuperGeometry.

This header provides three layers of functionality:

1. Session helpers (wxbgi_openlb_begin_session, wxbgi_openlb_pump, wxbgi_openlb_present) — thin inline wrappers that open a wx_bgi window and run the event loop inside an OpenLB solver's time-stepping loop, matching the conventional OpenLB while (pump()) idiom.

2. C bridge functions (wxbgi_openlb_classify_point_material, wxbgi_openlb_sample_materials_2d) — exported C functions that query the active DDS retained scene and return integer OpenLB material IDs for arbitrary physical coordinates. All C functions acquire the internal bgi::gMutex and are safe to call from any thread.

3. C++ materialize templates (wxbgi_openlb_materialize_super_geometry_2d, wxbgi_openlb_materialize_super_geometry_3d) — header-only function templates that iterate every core lattice node of an olb::SuperGeometry, project its physical coordinates into the DDS scene, and write the resolved material IDs back into the geometry. An optional Mapper callback gives callers full control over the final per-node material assignment.

Note: The C++ templates are not independently thread-safe. Call them from a single thread while no other thread is modifying the DDS scene.; Coordinate units must be consistent: all physical coordinates passed to the bridge functions must be in the same world-space units used by the DDS scene (typically SI metres when working with OpenLB).

Function Documentation

◆ wxbgi_openlb_classify_point_material()

BGI_API int BGI_CALL wxbgi_openlb_classify_point_material	(	float	x,
		float	y,
		float	z,
		int	defaultFluidMaterial,
		int	defaultSolidMaterial,
		int *	outMatched
	)

Classify a single physical-space point against the active DDS scene and return the associated OpenLB material ID.

The function traverses the active DDS retained scene (the scene set via wxbgi_dds_scene_set_active(), or the default scene) and tests whether the world point (x, y, z) falls inside any DDS object that carries openlb.* attributes. The first matching object (highest openlb.priority, then insertion order) determines the returned material.

Objects participate in classification only when:

They are visible and not deleted.
They have at least one openlb.* external attribute.
Their openlb.enabled attribute is absent, or is not "0", "false", or "off".

Material resolution order for a matching object:

openlb.material attribute (integer) — used directly if present.
openlb.role attribute — "fluid" → defaultFluidMaterial; anything else → defaultSolidMaterial.

Parameters

[in]	x	X coordinate of the query point in world (physical) units.
[in]	y	Y coordinate of the query point in world (physical) units.
[in]	z	Z coordinate of the query point in world (physical) units.
[in]	defaultFluidMaterial	Material ID to return when no DDS object is matched and as the default fluid-role fallback. Typically 1 (OpenLB convention).
[in]	defaultSolidMaterial	Material ID used as the default solid-role fallback. Typically 2.
[out]	outMatched	If not `NULL`, set to `1` when a DDS object was matched, or `0` when the point is unmatched. The caller can use this flag to distinguish between a genuine fluid material and the default fallback.

Returns: The integer material ID of the highest-priority matching DDS object, or defaultFluidMaterial when no object contains the point.

Note: This function acquires bgi::gMutex and is safe to call from any thread.; If no DDS scene is active (gState.dds == nullptr), the function immediately returns defaultFluidMaterial with *outMatched = 0.; Point-in-solid tests use a small numerical epsilon (~1e-4 world units) so boundary points may be counted as inside.

◆ wxbgi_openlb_sample_materials_2d()

BGI_API int BGI_CALL wxbgi_openlb_sample_materials_2d	(	float	minX,
		float	minY,
		float	z,
		int	cols,
		int	rows,
		float	stepX,
		float	stepY,
		int	defaultFluidMaterial,
		int	defaultSolidMaterial,
		int *	outMaterials,
		int	materialCount
	)

Sample a 2-D axis-aligned grid of physical points against the active DDS scene and write per-cell material IDs into a caller-supplied array.

The function evaluates cols × rows sample points arranged in a regular grid. Each cell (col, row) (0-based) is sampled at its centre:

x = minX + (col + 0.5f) * stepX
y = minY + (row + 0.5f) * stepY
z = z  (constant for all cells)

The output array is laid out row-major: outMaterials[row * cols + col]. Unmatched cells are filled with defaultFluidMaterial.

Parameters

[in]	minX	X coordinate of the lower-left corner of the grid in world (physical) units.
[in]	minY	Y coordinate of the lower-left corner of the grid in world (physical) units.
[in]	z	Constant Z coordinate at which all cells are sampled.
[in]	cols	Number of grid columns (X direction, must be > 0).
[in]	rows	Number of grid rows (Y direction, must be > 0).
[in]	stepX	Cell width in world units (`> 0`).
[in]	stepY	Cell height in world units (`> 0`).
[in]	defaultFluidMaterial	Material ID written for unmatched cells.
[in]	defaultSolidMaterial	Fallback solid-role material (passed to `wxbgi_openlb_classify_point_material`).
[out]	outMaterials	Caller-allocated array of at least `materialCount` `int` elements. On success, the first `cols * rows` entries are overwritten in row-major order. Must not be `NULL`.
[in]	materialCount	Size of the `outMaterials` array. Must be ≥ `cols * rows`; the function returns `-1` if the provided buffer is too small.

Returns

The number of array elements written (cols * rows) on success, or -1 if any of the following conditions hold:

cols ≤ 0 or rows ≤ 0
outMaterials == NULL
materialCount < cols * rows
No active DDS scene is present.

Note: This function acquires bgi::gMutex and is safe to call from any thread.; Ownership of outMaterials remains with the caller; the function never frees or reallocates it.

See also: wxbgi_openlb_classify_point_material() for single-point classification.

Functions

Detailed Description

Function Documentation

◆ wxbgi_openlb_classify_point_material()

◆ wxbgi_openlb_sample_materials_2d()