API do motor sem editor: criar cenas e renderizar imagens
Automatize o motor através da C ABI: construa cenas, adicione componentes, escreva materiais, gere terreno e água, e renderize imagens RGBA offscreen sem janela.
Tudo o que o Doppio faz ao motor passa por uma única C ABI, libcaffeine-capi
(include/caffeine/capi/EngineAPI.h, CAFFEINE_CAPI_VERSION 8). O que o editor faz, um script
também faz: criar entidades, adicionar componentes, escrever materiais, gerar terreno e água, mover a
câmara e renderizar a cena para pixéis RGBA, fora do ecrã, sem janela. Esta página serve para
automatizar isso: cenas de teste, imagens geradas, miniaturas, imagens de regressão, renders em lote.
A forma da API#
| Ideia | O que significa |
|---|---|
| Sessão | caffeine_session_create() cria uma cena (o seu próprio mundo ECS). Tudo o resto recebe a sessão. Destrói-se com caffeine_session_destroy. |
| Entidades | ids uint32_t. caffeine_session_create_entity(session, nome) devolve CAFFEINE_ENTITY_NONE se falhar. A transformação é posição, rotação (graus de Euler) e escala. Hierarquia com caffeine_session_set_entity_parent. |
| Componentes por nome | Os componentes são descritos em execução. Lista-os com caffeine_component_type_count/at e os campos com caffeine_component_type_field_at; adiciona com caffeine_session_add_component(session, entidade, type_id) e define um campo com caffeine_session_entity_component_field_set. Tipos de campo: f32, bool, i32, u32, vec2/3/4, texto, enum (pelo índice da opção), cor. É a mesma reflexão do Inspector, por isso um componente novo aparece aqui sem mudar a API. |
| Ativos | caffeine_session_set_asset_root(session, pasta) define a pasta do projeto. Os caminhos nos componentes são relativos a ela (nature/materials/oak.mat). caffeine_session_asset_project_path e caffeine_session_resolve_path convertem entre formas. |
| Materiais | Ficheiros .mat. caffeine_material_default/load/save editam-nos; caffeine_session_apply_material(session, entidade, caminho) atribui um. Um material é um ativo, nunca parte de uma malha. |
| Resultados | Todas as chamadas devolvem CaffeineResult: OK, ERROR, INVALID_ARGUMENT, NOT_FOUND. Verifica-o. |
| Versão | caffeine_capi_version() diz o que a biblioteca carregada suporta. O terreno precisa de 8, a água de 7. |
Renderizar uma imagem (o ciclo completo)#
criar sessão -> pasta de ativos -> criar entidades + componentes -> atribuir materiais
-> câmara -> (opcional) definições da viewport -> render -> escrever PNG
caffeine_session_render(session, largura, altura, pixels, pixel_bytes) preenche largura * altura * 4
bytes RGBA8 e bloqueia até terminar. Para uso interativo, caffeine_session_render_begin e depois
caffeine_session_render_poll até CAFFEINE_RENDER_READY não bloqueia. Chama
caffeine_session_tick(session, dt) entre renders quando algo anima (água, partículas).
A câmara é orbital (CaffeineCamera): yaw e pitch em radianos, distance em metros, focus o
ponto para onde olha. CaffeineViewportSettings tem show_grid (ligado por defeito: desliga-o para
uma imagem limpa), anti_aliasing (0 desligado, 1 FXAA, 2 TAA) e render_scale (0,5 a 2,0, supersampling).
Exemplo executável (Rust)#
doppio/crates/engine/examples/render_scene.rs cria um chão, um cubo, uma esfera e um sol, escreve três
.mat, atribui-os, aponta a câmara e grava um PNG:
cmake --build build --target caffeine-capi -j
cd doppio
cargo run -p doppio-engine --example render_scene -- /tmp/scene.png
O crate doppio-engine é um invólucro seguro fino das funções C; é o único crate Rust que carrega a
biblioteca, e CAFFEINE_CAPI_LIB muda onde ela procura.
Em Python (sem compilar)#
import ctypes as C
lib = C.CDLL("build/libcaffeine-capi.so") # .dylib / .dll noutros sistemas
lib.caffeine_session_create.restype = C.c_void_p
lib.caffeine_session_create_entity.restype = C.c_uint32
lib.caffeine_session_create_entity.argtypes = [C.c_void_p, C.c_char_p]
lib.caffeine_session_render.argtypes = [C.c_void_p, C.c_uint32, C.c_uint32, C.c_void_p, C.c_size_t]
session = lib.caffeine_session_create()
lib.caffeine_session_create_entity(session, b"Thing")
w, h = 640, 360
pixels = (C.c_uint8 * (w * h * 4))()
assert lib.caffeine_session_render(session, w, h, pixels, len(pixels)) == 0
# bytes(pixels) é RGBA8; passa-o ao Pillow / numpy / imageio
Qualquer linguagem com FFI para C funciona igual: declara as funções que usas e passa estruturas simples.
Gerar conteúdo e renderizá-lo#
- Terreno.
caffeine_session_set_terrain(session, entidade, &CaffeineTerrain, heights, splat_rgba)recebe uma grelha de alturas normalizada (0..1) e pesos de splat opcionais (relva, rocha, terra, lama). As quatro camadas são os campos de textoSplat Layer Paths 1..4do componente: aponta-os a texturas do projeto (o gerador de terreno escreveterrain/layers/<camada>.pngmais um.matpor camada e preenche os caminhos com o mapa de albedo de cada material).caffeine_session_terrain_heightamostra-o. - Água.
caffeine_session_set_water(session, entidade, &water)cria uma superfície animada; atribui um.matà entidade e a água é desenhada com ele.caffeine_session_water_heightamostra a superfície no tempo, por isso faz tick antes de amostrar. - Natureza e malhas. Escreve
.objno projeto e põe oMesh FilteremCustomcom o caminho emMesh(é o que Place in scene faz com árvores e rochas). - Cenas.
caffeine_session_save_scene/load_sceneleem e escrevem.caf, por isso uma cena gerada reabre no Doppio ou carrega no runtime.snapshot/restoredão pontos de desfazer baratos.
Texturas e pré-visualizações de material sem cena#
caffeine_texture_generate_map, caffeine_texture_pack_maps (ORM e empacotamentos do motor),
caffeine_texture_save_rgba/rgba16 e caffeine_texture_load_rgba trabalham diretamente em imagens.
caffeine_session_render_material_preview(_ex) renderiza uma esfera, cubo ou plano iluminado para um .mat
sem montar cena, que é como se fazem miniaturas e a galeria de materiais (scripts/render-material-gallery.sh).
Notas práticas#
- O render usa um dispositivo SDL GPU e desenha fora do ecrã: as chamadas não abrem janela. Foi verificado num desktop Linux com GPU; uma máquina sem GPU não foi testada.
- Usa uma sessão numa só thread de cada vez; a API não promete acesso concorrente a uma sessão.
- Para imagens de regressão compara com tolerância: o resultado pode variar ligeiramente entre GPUs e drivers.
- Os ativos são referenciados por caminho: define primeiro a pasta de ativos e prefere caminhos relativos para a cena acompanhar o projeto.
- Os geradores do Doppio só chamam esta API, por isso tudo o que colocam pode ser reproduzido por um script.