spawn2d.h

/*

    spawn2d — Uniform sampling in combined shapes with overlap handling and distance constraints.

    Project URL : https://github.com/Geolm/spawn2d

    zlib License

    (C) 2025 Geolm

    This software is provided 'as-is', without any express or implied
    warranty.  In no event will the authors be held liable for any damages
    arising from the use of this software.

    Permission is granted to anyone to use this software for any purpose,
    including commercial applications, and to alter it and redistribute it
    freely, subject to the following restrictions:

    1. The origin of this software must not be misrepresented; you must not
    claim that you wrote the original software. If you use this software
    in a product, an acknowledgment in the product documentation would be
    appreciated but is not required.
    2. Altered source versions must be plainly marked as such, and must not be
    misrepresented as being the original software.
    3. This notice may not be removed or altered from any source distribution.

*/

#ifndef SPAWN2D_H
#define SPAWN2D_H

#include <stdint.h>
#include <stdbool.h>

//-------------------------------------------------------------------------------------------------------------------
// API
//-------------------------------------------------------------------------------------------------------------------

//-------------------------------------------------------------------------------------------------------------------
enum spawn2d_shape_type
{
    spawn2d_shape_disc,
    spawn2d_shape_aabb,
    spawn2d_shape_obb,
    spawn2d_shape_ellipse
};

//-------------------------------------------------------------------------------------------------------------------
typedef struct spawn2d_shape
{
    union 
    {
        struct {float cx, cy, radius; } disc;
        struct {float minx, miny, maxx, maxy;} aabb;
        struct {float cx, cy, width, height, angle;} obb;
        struct {float cx, cy, rx, ry; } ellipse;
    };
    enum spawn2d_shape_type type;
} spawn2d_shape;

//-------------------------------------------------------------------------------------------------------------------
typedef struct spawn2d_context
{
    const spawn2d_shape* shapes;
    uint32_t num_shapes;
    const spawn2d_shape* exclusions;
    uint32_t num_exclusions;
    const float* ctrl_points;
    uint32_t num_ctrl_points;
    float width;
    uint32_t num_tries_max;
    float min_distance;
    uint32_t* seed;
} spawn2d_context;

#ifdef __cplusplus
extern "C" {
#endif

//-------------------------------------------------------------------------------------------------------------------
// Generates points in the aggregated shapes
//          [ctx]                   Pointer to the context of spawning, cannot be NULL
//              [shapes]            Pointer to a list of shapes, cannot be NULL
//              [num_shapes]        Number of shapes, cannot be 0
//              [exclusions]        Pointer to the exclusions shapes, if none can be set to NULL
//              [num_exclusions]
//              [num_tries_max]     Number of tries to spawn each point before quitting (avoid infinite loop)
//              [min_distance]      Minimum distance between points, if > 0 implies expensive computation
//              [seed]              Pointer to the seed. The value is going to be changed by this function
//          [points]                Pointer to the output array of points, sizeof(float) * 2 * num_points, can't be NULL
//          [num_points]            >0
//
// Returns the actual number of points spawned
uint32_t spawn2d_generate_in_shapes(spawn2d_context* ctx, float* points, uint32_t num_points);

//-------------------------------------------------------------------------------------------------------------------
// Spawns points along a catmull-rom spline
//          [ctx]                       Pointer to the context of spawning, cannot be NULL
//              [control_points]        Pointer to the spline control points, the spline goes through all
//                                      buffer have a size of : sizeof(float) * 2 * num_control_points
//              [num_control_points]    >2
//              [width]                 Width of the spawning zone along the spline
//              [num_tries_max]         Number of tries to spawn each point before quitting (avoid infinite loop)
//              [min_distance]          Minimum distance between points, if > 0 implies expensive computation
//              [seed]                  Pointer to the seed. The value is going to be changed by this function
//          [points]                Pointer to the output array of points, sizeof(float) * 2 * num_points, can't be NULL
//          [num_points]            >0
//
// Returns the actual number of points spawned
uint32_t spawn2d_generate_along_spline(spawn2d_context* ctx, float* points, uint32_t num_points);




//-------------------------------------------------------------------------------------------------------------------
// Internal helper functions (optional, not part of public API)
//-------------------------------------------------------------------------------------------------------------------

//-------------------------------------------------------------------------------------------------------------------
// Returns the area of the shape
float spawn2d_compute_area(const spawn2d_shape* shape);

//-------------------------------------------------------------------------------------------------------------------
// Returns true if the point is inside the shape
bool spawn2d_point_in(const spawn2d_shape* shape, float x, float y);

//-------------------------------------------------------------------------------------------------------------------
// Uniform area sampling
//          [seed]                  Random generator seed, cannot be zero, will be changed by this function
//          [x, y]                  Pointer to point coordinates
void spawn2d_sample_area(const spawn2d_shape* shape, uint32_t* seed, float* x, float* y);

//-------------------------------------------------------------------------------------------------------------------
// Returns a random float in [0; 1[
static inline float spawn2d_rand(uint32_t *seed)
{
    union
    {
        uint32_t i;
        float f;
    } u;

    // SplitMix32
    *seed += 0x9e3779b9u;
    uint64_t z = *seed;
    z = (z ^ (z >> 15)) * 0x85ebca6bULL;
    z = (z ^ (z >> 13)) * 0xc2b2ae35ULL;
    z ^= z >> 16;

    uint32_t mant = (uint32_t)(z >> 9) & 0x007FFFFFu;
    u.i = mant | 0x3f800000u;
    return u.f - 1.0f;
}

#ifdef __cplusplus
}
#endif

#endif