Ir para o conteúdo

Versão 1.5.0

ziviDomeLive 1.5.0 é a versão final de consolidação do renderer 1.x. Ela preserva a API estabelecida para Processing e torna explícitos e testáveis a seleção de renderização, o ownership do lifecycle, a calibração esférica, o roteamento de outputs, a qualificação automatizada e o empacotamento.

Destaques

  • RenderMode define a família ativa: FULL, STANDARD, DOMEMASTER, EQUIRECTANGULAR ou SKYBOX.
  • Os requisitos de renderização são derivados do modo, preview, domemaster flutuante e rotas de output ativas, permitindo omitir passes sem uso.
  • Pitch, yaw e roll são controles cíclicos compostos em um único quaternion normalizado, sem gimbal lock no estado de orientação.
  • O painel ControlP5 mostra apenas os controles relevantes ao RenderMode; seletores de rota são editáveis em FULL e fixos nos modos dedicados.
  • NDI, Syphon e Spout possuem estados explícitos de disponibilidade, inicialização, publicação, falha e encerramento.
  • O CalibrationTool oferece alvos repetíveis para qualificação visual das faces do cubo e da esfera 360 graus.
  • Qualificação JUnit, documentação bilíngue estrita, Javadocs, verificação dos pacotes e workflows GitHub passam a compor um único processo de release.

O registro detalhado por arquivo está no CHANGELOG.md do repositório.

Modos de Renderização

RenderMode.FULL é o default de compatibilidade. Sketches existentes que não chamam setRenderMode() preservam a seleção independente do preview e das rotas de cada output.

Os modos dedicados restringem a intenção pública de renderização:

Modo Vista principal Seletores de rota Controles esféricos relevantes
FULL ViewType selecionado Editáveis por output Conforme as rotas selecionadas
STANDARD Perspectiva Standard Fixos Ocultos, exceto quando o domemaster flutuante os exige
DOMEMASTER Fisheye domemaster Fixos FOV, Size%, pitch, yaw e roll
EQUIRECTANGULAR Equiretangular Fixos pitch, yaw e roll
SKYBOX Layout cubemap Fixos pitch, yaw e roll

O runtime calcula os requisitos transitivos de cada frame. Um domemaster, por exemplo, depende das fontes equiretangular e cubemap, enquanto Standard continua independente da captura esférica. Consulte Modos de Renderização e Pipeline de Renderização.

Orientação Esférica

Os controles 1.5 preservam a interface conhecida de pitch/yaw/roll, mas o estado renderizado é baseado em quaternion:

  • pitch gira no eixo local X;
  • yaw gira no eixo local Z;
  • roll gira no eixo local Y;
  • cada setter aplica o menor delta cíclico desde o valor anterior;
  • todo delta é composto em um quaternion normalizado.

Os valores retornados pelos getters são acumuladores de controle, não uma decomposição Euler do quaternion. Como rotações não comutam, aplicar pitch e depois yaw pode produzir uma atitude diferente de yaw seguido de pitch, mesmo que os valores finais exibidos coincidam. Integrações que repetem uma calibração devem preservar a ordem dos comandos ou começar por resetOrientation().

Lifecycle e Outputs

A inicialização agora possui estados observáveis e comportamento de falha limitado. A biblioteca é dona dos hooks registrados no Processing; o sketch deve chamar setup() uma vez e não deve chamar zividomelive.draw() manualmente.

Roteamento e estado do backend são conceitos separados. Uma rota pode exigir uma vista mesmo enquanto seu sender nativo está inicializando. Métodos de diagnóstico expõem motivos de falha e contadores de frames NDI. Pause, resume, redimensionamento e dispose preservam a intenção de publicação sem deixar workers em segundo plano.

NDI permanece um output experimental, não oficial e somente de vídeo. O Processing não fornece uma biblioteca NDI nativa oficial e o artefato público do Devolay é separado do runtime; portanto, o usuário deve concluir a instalação do Runtime NDI específica para seu sistema operacional.

Calibration Tool

A Cena 1 mapeia alvos procedurais GLSL 4.10 de foco, alinhamento, cor, escala de cinza, clipping, pontos e estrelas diretamente nas seis faces do cubo. A superfície completa acompanha a orientação esférica compartilhada.

A Cena 2 mapeia o padrão equiretangular v14 original de Paul Bourke em uma esfera 360 graus completa centrada em (0, 0, 0), com polos em +Z e -Z. Uma das quatro resoluções fonte é escolhida pelo bucket do output ativo, ou pela janela quando todos os outputs estão desligados. Os perfis de rotação lenta implementam a recomendação do autor de uma volta por minuto sem alterar o animator do Processing dentro da cena.

Consulte Calibração Esférica e o Protocolo do Calibration Tool.

Testes e Empacotamento

A versão introduz qualificationTests como tarefa canônica de evidência JUnit headless. Os testes permanecem em src/test e no Git, mas ficam fora do deploy ao sketchbook e dos pacotes de release. O GitHub executa a mesma suíte em um workflow dedicado.

buildReleaseArtifacts gera e verifica o ZIP, PDEX e texto de metadados do Processing. A verificação rejeita avisos legais ou citação ausentes, fontes de teste acidentais, JARs auxiliares locais de compile-only e diferenças entre ZIP e PDEX.

Notas de Compatibilidade

  • A fachada pública em minúsculas continua zividomelive.
  • RenderMode.FULL continua sendo o default.
  • A ordem de ViewType não mudou porque ControlP5 e caminhos de compatibilidade fazem mapeamento por índice.
  • Métodos diretos de renderização permanecem como shims 1.x deprecados.
  • Getters de renderers continuam públicos por compatibilidade de fonte 1.x, mas a topologia interna não é um contrato estável para 2.0.
  • Os shaders de projeção e calibração empacotados exigem suporte a OpenGL 4.1 / GLSL 4.10.

Checklist de Atualização

  1. Mantenha uma instância de zividomelive por sketch e chame setup() uma vez.
  2. Remova chamadas manuais a zividomelive.draw() e pares beginDraw()/endDraw() controlados pela cena.
  3. Não defina RenderMode para manter o roteamento legado, ou selecione um modo dedicado quando o sketch possuir uma única projeção fixa.
  4. Restaure a orientação antes de repetir uma sequência ordenada de calibração.
  5. Requalifique output de GPU, emendas, foco, cor, NDI/Syphon/Spout, pause/resume e encerramento no hardware de produção.
  6. Execute o checklist de Prontidão para Release antes de criar a tag v1.5.0.