Skip to content

Common Types and Macros

This page describes ABI-related macros and shared base types from grimoire-pcg/common.h.

Platform Normalization

common.h normalizes _WIN32 in some mixed toolchain environments:

#if !defined(_WIN32) && (defined(__WIN32__) || defined(WIN32) || defined(__MINGW32__))
    #define _WIN32
#endif

This helps keep export/import behavior consistent across Windows compilers.

GRIMOIRE_API

GRIMOIRE_API controls symbol visibility.

Windows behavior:

  • If _GRIMOIRE_BUILD is defined: exports (__declspec(dllexport)).
  • Otherwise: imports (__declspec(dllimport)).

GCC/Clang behavior:

  • Uses __attribute__((visibility("default"))) when available.

Fallback:

  • If no platform rule applies, GRIMOIRE_API becomes empty.

Static build note:

  • If GRIMOIRE_STATIC is defined, dynamic import/export decoration is skipped.

GRIMOIRE_DEPRECATED(msg)

Provides cross-compiler deprecation annotation:

  • MSVC: __declspec(deprecated(msg))
  • GCC/Clang: __attribute__((deprecated(msg)))
  • Fallback: empty macro

Use this for API evolution while preserving compatibility windows.

C/C++ Linkage Macros

#ifdef __cplusplus
    #define GRIMOIRE_BEGIN extern "C" {
    #define GRIMOIRE_END }
#else
    #define GRIMOIRE_BEGIN
    #define GRIMOIRE_END
#endif

These macros wrap declarations so C++ consumers keep C symbol names.

Base Seed Type

typedef int32_t hash_t;

hash_t is the shared deterministic seed type used across RNG and noise APIs.

Guidance:

  • Use constant seeds for reproducible tests and fixtures.
  • Document seed choices in gameplay/content pipelines.
  • Avoid using this type as a security token source.

Consumer Build Checklist

  • Ensure include path points to the folder that contains grimoire-pcg/.
  • Define _GRIMOIRE_BUILD only when compiling the DLL itself.
  • Do not define _GRIMOIRE_BUILD in consuming apps.
  • In C++, include headers directly without adding another extern "C" wrapper.