ludus::content¶
Ludus Wiki · API overview · Browse API
Namespace
Declared in modules/content/geometry_format/include/ludus/content/geometry_format/geometry_format.h
Related declarations¶
- ludus::content::Bytes
- ludus::content::Catalog
- ludus::content::Diagnostic
- ludus::content::Digest
- ludus::content::FileReader
- ludus::content::Hasher
- ludus::content::JsonDocument
- ludus::content::JsonValue
- ludus::content::JsonWriter
- ludus::content::Resource
- ludus::content::Text
- ludus::content::geometry_format
- ludus::content::identity_records
- ludus::content::procedural
- ludus::content::render_graph_format
- ludus::content::scene_cook
- ludus::content::scene_format
- ludus::content::scene_source
- ludus::content::string_dictionary
- ludus::content::string_dictionary_format
- ludus::content::world_restore
Enumerations¶
Status¶
enum class Status : uint8
Related types: uint8
Ok¶
Ok
Pending¶
Pending
Invalid¶
Invalid
Limit¶
Limit
OutOfMemory¶
OutOfMemory
IoError¶
IoError
Conflict¶
Conflict
NotFound¶
NotFound
Unsupported¶
Unsupported
Cancelled¶
Cancelled
Declared in modules/content/include/ludus/content/content.h
Kind¶
enum class Kind : uint8
Resource category recorded in the authored catalog.
Related types: uint8
AudioSource¶
AudioSource
Encoded audio source bytes.
Sound¶
Sound
Immutable sound definition referencing audio sources.
Music¶
Music
Immutable music definition; playback state has a separate owner.
Mesh¶
Mesh
Immutable CPU triangle geometry; renderer installation is separate.
CookedScene¶
CookedScene
Fully resident predecoded scene binding; project assets retain separate identities.
CookedGeometry¶
CookedGeometry
Cooked curves/surfaces geometry (LUGEO; Ludus::GeometryFormat). Catalog schema version 2+.
Declared in modules/content/include/ludus/content/content.h
Aliases¶
ResourceId¶
using ludus::content::ResourceId = Text<MAX_RESOURCE_ID_BYTES>
Related types: MAX_RESOURCE_ID_BYTES · Text
Declared in modules/content/include/ludus/content/content.h
ResourcePath¶
using ludus::content::ResourcePath = Text<MAX_RESOURCE_PATH_BYTES>
Related types: MAX_RESOURCE_PATH_BYTES · Text
Declared in modules/content/include/ludus/content/content.h
MessageText¶
using ludus::content::MessageText = Text<MAX_MESSAGE_BYTES>
Bounded human-readable error or diagnostic message. Reuse this alias rather than spelling a new Text<N> so every message shares one instantiation.
Related types: MAX_MESSAGE_BYTES · Text
Declared in modules/content/include/ludus/content/content.h
Constants and variables¶
MAX_RESOURCE_ID_BYTES¶
constexpr usize ludus::content::MAX_RESOURCE_ID_BYTES = 128
Capacity of a ResourceId, excluding the terminator.
Related types: usize
Declared in modules/content/include/ludus/content/content.h
MAX_RESOURCE_PATH_BYTES¶
constexpr usize ludus::content::MAX_RESOURCE_PATH_BYTES = 1024
Capacity of a ResourcePath, excluding the terminator.
Related types: usize
Declared in modules/content/include/ludus/content/content.h
MAX_MESSAGE_BYTES¶
constexpr usize ludus::content::MAX_MESSAGE_BYTES = 255
Capacity of a MessageText, excluding the terminator.
Related types: usize
Declared in modules/content/include/ludus/content/content.h
MAX_DOCUMENT_BYTES¶
constexpr foundation::usize ludus::content::MAX_DOCUMENT_BYTES = foundation::usize{1024} * 1024
Inclusive encoded JSON byte ceiling for Content definitions and audio catalogs.
Related types: foundation::usize
Declared in modules/content/include/ludus/content/limits.h
MAX_RESOURCES¶
constexpr foundation::usize ludus::content::MAX_RESOURCES = 4096
Inclusive number of records in a Content catalog.
Related types: foundation::usize
Declared in modules/content/include/ludus/content/limits.h
MAX_ROOT_BYTES¶
constexpr foundation::usize ludus::content::MAX_ROOT_BYTES = 4096
Inclusive byte length of a Content filesystem root path.
Related types: foundation::usize
Declared in modules/content/include/ludus/content/limits.h
MAX_SAVE_BYTES¶
constexpr foundation::usize ludus::content::MAX_SAVE_BYTES = foundation::usize{32} * 1024 * 1024
Inclusive byte ceiling for SaveFile inputs and existing files checked for replacement. This persistence budget is independent of JSON document and scene payload admission.
Related types: foundation::usize
Declared in modules/content/include/ludus/content/limits.h
Functions¶
Hash¶
Digest ludus::content::Hash(std::span< const uint8 > data) noexcept
Declared in modules/content/include/ludus/content/content.h
ValidId¶
bool ludus::content::ValidId(std::string_view value) noexcept
Declared in modules/content/include/ludus/content/content.h
ValidPath¶
bool ludus::content::ValidPath(std::string_view value) noexcept
Declared in modules/content/include/ludus/content/content.h
ReadFile¶
Status ludus::content::ReadFile(std::string_view root, std::string_view path, usize cap, Bytes &outBytes) noexcept
Read a regular file below a trusted native root into owned bytes.
| Parameter | Description |
|---|---|
root |
Nonempty filesystem root (up to 4096 bytes); a root symlink is allowed.
|
path |
Valid relative UTF-8 path; symlinks below the root are rejected.
|
cap |
Maximum admitted file size in bytes; empty files are valid.
|
outBytes |
Replaced only on success; unchanged on every failure.
|
Returns
Ok, Invalid, NotFound, Limit, OutOfMemory, IoError, Conflict if the opened revision changes during reading, or Unsupported on other platforms.
Note
Synchronous Windows, Linux, macOS or Emscripten session-filesystem I/O; call outside render/audio critical paths. Browser reads do not access host files.
Related types: Bytes · Status · usize
Declared in modules/content/include/ludus/content/content.h
SaveFile¶
Status ludus::content::SaveFile(std::string_view root, std::string_view path, std::span< const uint8 > data, const Digest *expected) noexcept
Atomically create or replace one content file on Windows, Linux, macOS or browser MEMFS.
| Parameter | Description |
|---|---|
root |
Trusted existing native or session directory (up to 4096 bytes); a root symlink is allowed. Already-open directory mutation is outside this boundary.
|
path |
Valid relative UTF-8 path; parent directories must already exist. Symlinks below the root and non-regular destination files are rejected.
|
data |
Bytes to publish, at most 32 MiB; empty data creates an empty file.
|
expected |
Borrowed digest of the last-read destination, or nullptr to require absence. Only needed for this call. On Windows, validate the digest against the observed revision, then check its native stamp under the FoundationFilesystem writer lock before staging and before replacement. Linux and macOS check the digest under their native parent-directory lock.
|
Returns
Ok means atomic pathname publication succeeded. Conflict means a busy lock, absent expected file, or digest/absence mismatch; Invalid, Limit, OutOfMemory and IoError report admission or prepublication failure. Unsupported is returned on other platforms. Failure preserves the destination; owned temporaries are removed where possible, and foreign temporaries retained.
Note
Synchronous; writers must cooperate with the directory lock for strict compare-and-swap. Uncooperative writers can race the final check and rename.
Note
On Windows the publisher inherits the directory ACL and requests file sync. On Linux and macOS, uses an exclusive 0600 same-directory temporary named with a .ludus-save suffix (subject to native filename limits). Successful replacement creates a new inode; existing readers retain the old revision. File fsync and close must succeed before publication; directory sync is best-effort afterward. Ok does not promise drive-cache flush or power-loss durability.
Note
On Emscripten, call only from the session filesystem's single owner thread. The checks and rename do not yield; no native lock is taken. Ok means publication in volatile session memory, not browser persistence or download.