134 lines
8.1 KiB
Markdown
134 lines
8.1 KiB
Markdown
---
|
|
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.
|