Skip to content

Turn one illustration into an animated 2D mesh avatar with a coding agent and a local editor

4.0 KB
Raw Blame
/* Optional headless rendering extension to mesh_avatar.h.
 * Build the library with --features render before linking these functions.
 * The default CPU-only library does NOT export them. Including this header
 * requires no macro and does not enable the library feature.
 *
 * Renderers use opaque never-reused tokens and per-renderer serialization.
 * They reference an avatar token without owning it; destroy renderers before
 * destroying their avatar. Rendering reads the cached frame without ticking.
 * Raw geometry borrowers must still synchronize their reads against tick/destroy.
 * All renderer functions use the core MaStatus and thread-local last-error API.
 * Recover from a contained GPU panic by destroying/reopening the affected objects.
 * Destroy all avatars/renderers before unloading the library.
 */


#ifndef MESH_AVATAR_RENDER_H
#define MESH_AVATAR_RENDER_H

/* Generated by cbindgen 0.29.4. Do not edit; run conformance/ffi-header.sh. */

#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>
#include "mesh_avatar.h"

#define MA_FIT_CONTAIN 0

#define MA_FIT_COVER 1

#define MA_RGBA_STRAIGHT 0

#define MA_RGBA_PREMULTIPLIED 1

/**
 * Physical output pixels, MSAA samples (1 or 4), fit and explicit viewport padding.
 * Use mesh_avatar_get_info to obtain the avatar's recommended pad_top/pad_side.
 */
typedef struct {
  uint32_t width;
  uint32_t height;
  uint32_t samples;
  /**
   * MA_FIT_CONTAIN or MA_FIT_COVER.
   */
  uint32_t fit;
  /**
   * Finite and greater than -1.
   */
  double pad_top;
  /**
   * Finite and greater than -0.5.
   */
  double pad_side;
} MaRenderOptions;

/**
 * Opaque renderer token. Uses a separate registry from avatar handles; zero is invalid.
 */
typedef uint64_t MaRenderer;

#define MA_GPU_UNAVAILABLE 7

#define MA_RENDER_ERROR 8

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

/**
 * Create a headless renderer bound to avatar's textures. Requires the render feature.
 * Returns MA_GPU_UNAVAILABLE only when no compatible adapter can be found; otherwise
 * GPU initialization failures return MA_RENDER_ERROR. On failure *out is zero.
 * Calls on a renderer are serialized; it may move between threads. It does not own
 * the avatar. Destroy the renderer before the avatar; rendering a destroyed avatar fails.
 * # Safety
 * options must be readable/aligned; out writable/aligned. Pointers must not alias.
 */
MaStatus mesh_avatar_renderer_create(MaHandle avatar,
                                     const MaRenderOptions *options,
                                     MaRenderer *out);

/**
 * Render the current cached frame without ticking or invalidating borrowed geometry.
 * Requires the render feature. rgba must hold at least width*height*4 bytes for the
 * current size. Writes tightly packed RGBA8, top row first, with transparent clear.
 * alpha_mode is MA_RGBA_STRAIGHT or MA_RGBA_PREMULTIPLIED. Extra bytes are untouched.
 * The synchronous call waits for readback. The buffer is never retained and remains
 * unchanged on failure. The caller must synchronize concurrent access to its buffer.
 * Calls acquire the renderer before the avatar lock; tick/render/destroy are serialized.
 * # Safety
 * rgba must be writable for length bytes, non-NULL, and must not alias library storage.
 */
MaStatus mesh_avatar_renderer_render(MaRenderer renderer,
                                     uint8_t *rgba,
                                     size_t length,
                                     uint32_t alpha_mode);

/**
 * Change physical output size, keeping fit/padding/MSAA. Requires the render feature.
 * Invalid sizes leave the renderer unchanged. Reallocate caller buffers before rendering.
 */
MaStatus mesh_avatar_renderer_resize(MaRenderer renderer, uint32_t width, uint32_t height);

/**
 * Destroy a renderer from any thread, including after a contained panic.
 * Requires the render feature. Rejects zero, unknown or destroyed tokens.
 */
MaStatus mesh_avatar_renderer_destroy(MaRenderer renderer);

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  /* MESH_AVATAR_RENDER_H */