prometeu-runtime/discussion/workflow/agendas/AGD-0030-internal-viewport-270p.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0030	internal-viewport-270p	Agenda - Internal Viewport 270p (480x270)	done	2026-04-27	2026-04-27	DEC-0022	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
• frame_composer.rs
• scene_viewport_resolver.rs
• overlay.rs

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.