--- id: AGD-0030 ticket: internal-viewport-270p title: Agenda - Internal Viewport 270p (480x270) status: done created: 2026-04-27 resolved: 2026-04-27 decision: DEC-0022 tags: [gfx, runtime, viewport, resolution, frame-composer, host] --- # Agenda - Internal Viewport 270p (480x270) ## Contexto O runtime hoje trata `320x180` como viewport interna canonica em pontos importantes do pipeline, inclusive documentacao de hardware, `FrameComposer`, `SceneViewportResolver` e testes do host/debug overlay. A proposta e subir a resolucao interna para `480x270`, preservando a mesma proporcao `16:9`, mas alterando custo de composicao, tamanho de caches, area visivel da camera e possivelmente algumas expectativas implicitas de contrato entre runtime, host, assets e tooling. Existe contexto arquitetural recente relevante: - `DSC-0025` separou cena canonica, viewport cache e politica de resolver; - `DSC-0026` consolidou `FrameComposer` como dono da composicao do frame; - a mudanca agora nao e apenas trocar um par de constantes, porque a viewport interna participa de sizing, copy policy, camera framing e budget de memoria. ## Problema Precisamos decidir se a viewport interna do Prometeu deve deixar de ser `320x180` e passar a ser `480x270` como novo baseline do runtime. A decisao precisa fechar: - se `480x270` vira contrato fixo do sistema ou apenas default configuravel; - vira contrato fixo do sistema - se a camera e o frame visible devem realmente expor mais mundo ou apenas densidade maior; - esse deve ser o frame visible default (zoom de camera sera discutido em outra agenda) - como ficam caches, copy regions, sprite/world composition e apresentacao no host; - devem seguir o mesmo padrao que temos hj, mas com uma area maior. - qual o impacto aceito em CPU, RAM e largura de banda para o target handheld. - o impacto foi aceito na integra. esssa mudanca eh definitiva e deve perfurar em specs e docs. ## Pontos Criticos - Compatibilidade de contrato: qualquer lugar que hoje assume `320x180` pode deixar de ser detalhe interno e passar a ser break de comportamento observavel. - devemos corrigir onde for necessario. - Custo de frame: `480x270` aumenta pixels por frame em 2.25x versus `320x180`, o que pode afetar render software, fades, copy/convert no host e overlays. - o impacto foi aceito na integra. - Viewport cache e resolver: o `SceneViewportResolver` e o sizing do `FrameComposer` dependem diretamente da viewport para anchor, drift, hysteresis e regioes de refresh. -- mudancas necessarias para esse novo tamanho. - Semantica de camera: aumentar a viewport pode mudar gameplay, enquadramento, spawn visibility e design de HUD se o jogo passa a ver mais mundo. -- sem compat. nao ha jogos ainda usando essas features. - Host e debug tooling: overlay, apresentacao desktop e eventuais capturas/testes visuais hoje ainda carregam suposicoes de `320x180`. - precisamos atuar em mudancas ali tb - Escopo de migracao: precisamos decidir se a troca cobre apenas runtime/host ou tambem specs, exemplos, assets de referencia e testes de regressao. - devemos migrar tudo para o novo tamanho. os assets nao sao necessarios, podemos mante-los no mesmo tamanho, com excessao dos glyphos de texto. ## Hotspots Atuais - [hardware.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/hardware.rs#L24) - [frame_composer.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/frame_composer.rs#L197) - [scene_viewport_resolver.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/scene_viewport_resolver.rs#L56) - [overlay.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/host/prometeu-host-desktop-winit/src/overlay.rs#L478) ## Alvo da Discussao Definir o contrato correto para a viewport interna 270p no runtime e quais propagacoes sao obrigatorias antes de qualquer mudanca em spec ou codigo. ## Opcoes ### Opcao A - Manter `320x180` como contrato canonico - **Abordagem:** rejeitar a troca de baseline e, se necessario, melhorar apenas o upscale/apresentacao no host. - **Pro:** evita reabrir camera, caches, testes e budget de composicao. - **Con:** nao entrega mais area/pixel density interna e pode limitar qualidade visual ou framing pretendido. - **Manutenibilidade:** custo baixo agora, mas posterga a pergunta arquitetural se `320x180` ja nao representa mais o alvo real do produto. ### Opcao B - Promover `480x270` a nova viewport canonica fixa - **Abordagem:** trocar o baseline interno do sistema inteiro para `480x270` e propagar a mudanca onde o contrato hoje assume `320x180`. - **Pro:** simplifica o modelo final: uma resolucao interna oficial, sem modo duplo. - **Con:** aumenta custo por frame, pode expor mais mundo do que jogos atuais esperam e exige migracao coordenada em runtime/host/tests/specs. - **Manutenibilidade:** boa se o produto realmente quer 270p como target oficial; ruim se depois precisarmos voltar a variabilidade. ### Opcao C - Introduzir viewport interna configuravel com `320x180` e `480x270` - **Abordagem:** transformar a viewport interna em configuracao de sistema/composer, permitindo coexistencia de 180p e 270p. - **Pro:** reduz risco de migracao abrupta e facilita benchmark comparativo. - **Con:** amplia superficie de contrato, multiplica combinacoes de teste e pode contaminar caminhos que hoje assumem um unico baseline. - **Manutenibilidade:** pior no curto e medio prazo; so vale se variabilidade de resolucao for requisito real de produto, nao apenas etapa de transicao. ## Sugestao / Recomendacao Seguir inicialmente com a **Opcao B** como hipotese de trabalho: `480x270` deve ser tratado como novo baseline canonico, nao como configuracao geral. A recomendacao, porem, fica condicionada a duas verificacoes antes do fechamento da agenda: - confirmar que o efeito desejado e realmente aumentar a viewport observavel do jogo, e nao apenas melhorar a cadeia de apresentacao; - confirmar que o custo extra de composicao e caches cabe no budget aceito para o handheld alvo. Se qualquer uma dessas premissas falhar, a Opcao A ou uma variante mais restrita da Opcao C volta a ser competitiva. ## Perguntas em Aberto - A mudanca pretende mostrar mais mundo por frame ou manter o mesmo framing com outra granularidade visual? - mostrar mais mundo - `480x270` deve ser contrato global do runtime ou apenas default do host desktop? - contrato global do runtime, o prometeu passa a ser um console 270p - Quais syscalls, specs ou expectativas de cartridge assumem implicitamente a area visivel atual? - todas se e quando necessario - O budget de `SceneViewportCache` e das copias incrementais continua aceitavel com 2.25x mais pixels? - sim, aqui se tornarao ainda mais importantes - Fade, overlay e conversao `RGB565 -> RGBA8` no host permanecem viaveis sem nova rodada de otimizacao? - por enquanto iremos com o que temos, otimizaremos depois - Ha assets, HUDs ou testes snapshot que dependem do framing de `320x180`? - nao, nada que nao possa ser migrado para o novo tamanho, mas sem necessidade de vc atuar nisso. ## Criterio para Encerrar Esta agenda pode ser encerrada quando houver alinhamento suficiente para escrever uma decisao que feche explicitamente: - se `480x270` substitui `320x180` como contrato canonico; - sim - se a viewport maior muda framing/gameplay observavel ou apenas rasterizacao interna; - maior framing - quais modulos precisam de propagacao obrigatoria em runtime, host, specs e testes; - todos - qual evidence minima de custo/memoria e necessaria para executar a migracao com seguranca. - o preco jah foi aceito, iremos migrar. ## Resolucao A agenda foi encerrada com decisao favoravel a promover `480x270` como resolucao interna canonica do Prometeu. O novo tamanho passa a definir o frame visible default do console, com maior area observavel de mundo, sem compromisso de compatibilidade com o framing anterior de `320x180`. A migracao deve perfurar runtime, host, touch, specs, docs e testes. Otimizacoes de custo adicionais nao bloqueiam a mudanca: o aumento de CPU, RAM e bandwidth foi aceito como custo estrutural do novo baseline.