116 lines
6.3 KiB
Markdown
116 lines
6.3 KiB
Markdown
---
|
|
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`.
|