prometeu-runtime/discussion/workflow/decisions/DEC-0022-internal-viewport-270p.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0022	internal-viewport-270p	Internal Viewport 270p (480x270) as Canonical Runtime Contract	accepted	2026-04-27	2026-04-27	AGD-0030	PLN-0043 PLN-0044 PLN-0045	gfx runtime viewport resolution frame-composer host touch

Status

Accepted on 2026-04-27.

This decision is normatively locked until explicitly revised by a later decision.

Contexto

O runtime do Prometeu ainda trata 320x180 como resolucao interna canonica em pontos centrais do sistema, incluindo Hardware, FrameComposer, host desktop, touch mapping, documentacao de hardware e testes.

O trabalho recente de DSC-0025 e DSC-0026 consolidou o modelo correto para esse tipo de mudanca: viewport cache, resolver e frame composition ja possuem ownership claro e aceitam propagacao consistente a partir de um baseline unico de viewport.

O objetivo desta decisao nao e melhorar upscale do host. O objetivo e redefinir o contrato do console para 480x270 como resolucao interna oficial, com maior area visivel de mundo por frame.

Decisao

O Prometeu SHALL adotar 480x270 como resolucao interna canonica do runtime.

320x180 MUST cease to be treated as o baseline operacional do console em runtime, host, specs, docs e testes.

480x270 MUST representar o frame visible default do sistema. A mudanca e observavel: o console passa a mostrar mais mundo por frame.

O runtime MUST NOT introduzir, nesta migracao, um modo dual 180p/270p nem uma configuracao geral de viewport interna.

Qualquer discussao futura sobre zoom de camera, framing alternativo ou modos adicionais MUST acontecer em discussao separada e MUST NOT enfraquecer este contrato base por inferencia.

Rationale

Um baseline unico e fixo reduz ambiguidade de contrato e evita contaminar FrameComposer, host e specs com variabilidade que nao foi pedida como requisito real de produto.

Aumentar apenas a cadeia de apresentacao do host nao resolve o objetivo do trabalho, porque o requisito aceito e ampliar o frame visible do console, nao apenas ampliar a imagem final.

O custo estrutural de 480x270 foi explicitamente aceito. Portanto, CPU, RAM e bandwidth adicionais nao sao criterio de veto nesta decisao; passam a ser apenas materia de otimizacao posterior.

Como ainda nao existem jogos dependentes do framing anterior, nao ha motivo para carregar compatibilidade legada como restricao principal desta migracao.

Invariantes / Contrato

• Hardware::W e Hardware::H MUST convergir para 480 e 270.
• O framebuffer canonico do runtime MUST operar em 480x270 RGB565.
• O host desktop MUST criar sua superficie base a partir da nova resolucao canonica e MUST mapear touch/pointer para o novo dominio absoluto.
• FrameComposer MUST usar 480x270 como viewport base para scene binding, camera framing, cache sizing e resolver ownership.
• SceneViewportResolver e SceneViewportCache MUST preservar o modelo atual de ownership e refresh policy; a mudanca e de baseline dimensional, nao de arquitetura.
• O efeito observavel da camera MUST ser maior framing por frame. Esta decisao MUST NOT ser reinterpretada como mero aumento de densidade com framing igual.
• A conversao RGB565 -> RGBA8, fades, overlay e copy paths MAY permanecer com a implementacao atual nesta etapa. Otimizacao posterior e permitida, mas nao e precondicao para adotar 480x270.
• Assets existentes MUST continuar validos quando seu contrato nao depende da resolucao base. A migracao de assets em massa MUST NOT ser inventada como parte obrigatoria desta decisao.
• Glyphs e superficies textuais MAY exigir ajuste posterior quando o novo framing expuser necessidade de nova ocupacao visual, mas isso nao bloqueia o baseline 270p.

Impactos

Runtime

• Hardware, Gfx, FrameComposer, SceneViewportResolver e caminhos relacionados passam a operar sobre 480x270.
• Buffers de frame e custos por pixel aumentam estruturalmente.
• O budget de viewport cache e copy path continua valido conceitualmente, mas com volume maior de trabalho e memoria.

Host

• O host desktop deve recriar sua superficie Pixels no novo tamanho base.
• O mapeamento de input absoluto deve seguir 480x270.
• Overlay e qualquer teste de RGBA host-owned devem abandonar hardcodes de 320x180.

Firmware / Guest / ABI

• O espaco visivel observado pelo software convidado muda porque a camera default passa a enquadrar uma area maior.
• Esta decisao nao cria nova syscall, nao muda formato de argumento e nao introduz seletor de resolucao.

Specs / Docs

• As specs canonicas do runtime MUST publicar 480x270 como resolucao oficial.
• Textos sobre touch e framebuffer MUST ser atualizados para refletir o novo dominio coordenado.

Tooling / Tests

• Testes com hardcodes de 320x180 MUST migrar.
• Snapshots, asserts de tamanho e fixtures de host/debug MUST convergir para 480x270.

Referencias

• AGD-0030 - Internal Viewport 270p (480x270)
• DSC-0025 - Scene Bank and Viewport Cache Refactor
• DSC-0026 - Integrate render_all with Scene Cache and Camera
• hardware.rs
• runner.rs
• input.rs
• 04-gfx-peripheral.md
• 07-touch-peripheral.md

Propagacao Necessaria

• Atualizar constantes canonicas de resolucao em runtime.
• Atualizar criacao de framebuffer e apresentacao no host desktop.
• Atualizar mapping absoluto de touch/pointer.
• Atualizar testes de FrameComposer, SceneViewportResolver, host overlay e demais asserts fixos de tamanho.
• Atualizar specs e docs que ainda publicam 320x180.
• Escrever um plano de execucao que separe: runtime/host/tests; specs/docs; qualquer ajuste textual ou visual adicional nao bloqueante.

Revision Log

• 2026-04-27: Initial accepted decision from AGD-0030.