The C ABI

The model from any language

Core is C++, but it exposes a flat C ABI so the document model can be driven from any language with a C foreign-function interface — Python, Rust, Swift, Go, Lua, a game engine's scripting host. The C surface mirrors the C++ API: an opaque document handle, functions to shape and read it, and the native serialization.

#include "prism/C.h"

prism_document_t* s = prism_document_new();
prism_document_add_prim(s, "/world", "group");
prism_document_add_prim(s, "/world/ball", "object");
prism_document_set_float(s, "/world/ball", "radius", 1.5f);
prism_document_connect(s, "/world/ball.albedo", "/world/mat.out");

char*  text = NULL; size_t n = 0;
prism_document_serialize(s, &text, &n);      /* → .prisma bytes you own */
prism_free_buffer(text);
prism_document_free(s);

The shape of the surface

The naming is uniform — prism_<noun>_<verb> — and the lifecycle is explicit:

• handles — prism_document_t*, plus handles for the evaluator and the node registry where needed;
• build — prism_document_new, prism_document_add_prim, the typed setters (prism_document_set_float, …_set_int, …_set_string, vector/array variants), prism_document_connect;
• read — typed getters that resolve a property at a time;
• I/O — prism_document_serialize / prism_document_load for the native ASCII and binary encodings;
• free — prism_document_free, and prism_free_buffer for any buffer the library handed back.

Ownership rules

The contract is the usual C one, kept deliberately small: the library owns nothing you pass in (strings are copied at the boundary), and you own every buffer the library returns — release it with prism_free_buffer, and release handles with their _free. Errors are reported through return codes and an out-parameter message rather than exceptions, because exceptions do not cross a C boundary.

Why it's there

The C ABI is what makes Core a true foundation rather than a C++-only library. The same document a C++ tool builds, the Server edits, and a human writes by hand can also be created and read from a Python notebook or a Rust service through this surface — the same paths, the same typed values, the same files. Bind it once for your language and the entire Prism document model is available, with no C++ in your call sites.