--- id: DEC-0022 ticket: internal-viewport-270p title: Internal Viewport 270p (480x270) as Canonical Runtime Contract status: accepted created: 2026-04-27 accepted: 2026-04-27 agenda: AGD-0030 plans: [PLN-0043, PLN-0044, PLN-0045] tags: [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](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/hardware.rs:116) - [runner.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/runner.rs:229) - [input.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/input.rs:73) - [04-gfx-peripheral.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/04-gfx-peripheral.md:22) - [07-touch-peripheral.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/07-touch-peripheral.md:20) ## 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`.