# API de scripts Lua do pxstud.io — Pixels

> Parte da referência de scripts Lua do pxstud.io, cuja visão geral (https://pxstud.io/pt-br/docs/scripting.md) explica as convenções. Os grupos de opções e os tipos a que ela remete estão em https://pxstud.io/pt-br/docs/scripting/option-groups.md e https://pxstud.io/pt-br/docs/scripting/types.md. Tudo em um único arquivo (em inglês): https://pxstud.io/llms-full.txt. O índice de todo o site (em inglês): https://pxstud.io/llms.txt.

### Pixels
Leitura e escrita de pixels como listas RGBA planas (construídas sobre Images; nunca recortadas pela seleção nem espelhadas), preenchimentos e inversões da seleção inteira, e o conta-gotas.

#### `app.clearSelection(layerId, frameId)` — altera, desfazível, recusada em uma camada bloqueada
Limpa a seleção para totalmente transparente, aparando o cel ao que sobrar (um cel esvaziado é removido, junto com todo quadro vinculado a ele); sem nada selecionado, remove o cel deste quadro (um quadro vinculado apenas perde o vínculo). Na camada Background, tudo é limpo para a cor de fundo.

- `layerId` (string)
- `frameId` (string)

Não retorna nada.

#### `app.fillSelection(layerId, frameId, color, opts?)` — altera, desfazível, recusada em uma camada bloqueada
Preenche a seleção (ou o cel inteiro, se nada estiver selecionado) com uma cor sólida. Um preenchimento simples (copy), a menos que `ink` seja informado: diferente dos comandos de desenho, nunca usa a tinta do contexto de edição, como em Editar > Preencher.

- `layerId` (string)
- `frameId` (string)
- `color` (table) — { r, g, b, a }, cada um de 0 a 255.
- `opts` (table, opcional)
  - `ink` (Ink: "copy" | "simple" | "lock-alpha" | "shading"; padrão "copy") — copy substitui os pixels, simple compõe o alfa, lock-alpha recolore apenas os pixels visíveis, shading percorre as cores ao longo de `shades`. Ignorado por erase.
  - `shades` (a list of colors ("#rrggbb[aa]" or { r, g, b, a }), in ramp order) — A rampa ao longo da qual shading avança. Um pixel cuja cor não está na lista não é alterado; um pixel no fim da lista permanece ali.
  - `shadeReverse` (boolean; padrão false) — Shading avança para trás em `shades` (o botão direito do mouse na interface) em vez de para a frente.

Não retorna nada.

#### `app.flipCelRegion(layerId, frameId, axis)` — altera, desfazível, recusada em uma camada bloqueada
Inverte os pixels selecionados (ou o cel inteiro, se nada estiver selecionado) dentro dos limites da seleção: cada pixel selecionado vai para o seu espelho, os que ficam para trás são limpos (para a cor de fundo na camada Background) e a área de seleção também é invertida.

- `layerId` (string)
- `frameId` (string)
- `axis` (FlipAxis: "horizontal" | "vertical")

Não retorna nada.

#### `app.getCompositePixels(frameId, x, y, width, height)` — pura
Os pixels de app.getCompositeImage como uma lista RGBA plana no formato de app.getPixels. No máximo 262144 pixels por chamada.

- `frameId` (string)
- `x` (number)
- `y` (number)
- `width` (number)
- `height` (number)

Retorna (table): Lista RGBA plana.

#### `app.getPixels(layerId, frameId, x, y, width, height)` — pura
Lê um retângulo width x height em (x, y) do cel de uma camada/quadro como uma lista RGBA plana (comprimento width*height*4, em ordem de linhas: o pixel (px, py) começa no índice (py*width + px)*4 + 1), no formato que app.setPixels recebe. Pixels sem cel são lidos como transparentes (0, 0, 0, 0). Construído sobre app.getImage, que é mais rápido quando você não precisa de uma lista. No máximo 262144 pixels por chamada.

- `layerId` (string)
- `frameId` (string)
- `x` (number)
- `y` (number)
- `width` (number)
- `height` (number)

Retorna (table): Lista RGBA plana.

#### `app.sampleColor(frameId, x, y, layerId?)` — lê
O conta-gotas: a cor em (x, y) como { r, g, b, a }, por padrão o que a tela mostra ali (camadas visíveis combinadas com suas opacidades e modos de mesclagem), ou a cor de uma única camada quando layerId é informado.

- `frameId` (string)
- `x` (number)
- `y` (number)
- `layerId` (string, opcional) — Amostrar apenas esta camada. Omitido = todas as camadas visíveis compostas, como mostradas na tela.

Retorna (table): { r, g, b, a }, cada um de 0 a 255.

#### `app.setPixels(layerId, frameId, x, y, width, height, pixels)` — pura
Sobrescreve um retângulo width x height em (x, y) do cel de uma camada/quadro com uma lista RGBA plana (formato de app.getPixels), como um único app.putImage. Escrita direta: nunca recortada pela seleção nem espelhada. Em sprites indexados e em tons de cinza, as cores são mapeadas como img:setPixel as mapeia. No máximo 262144 pixels por chamada.

- `layerId` (string)
- `frameId` (string)
- `x` (number)
- `y` (number)
- `width` (number)
- `height` (number)
- `pixels` (table) — Lista RGBA plana, comprimento width*height*4, em ordem de linhas: o pixel (px, py) está no índice (py*width + px)*4 + 1 (r, depois g, b, a; cada um de 0 a 255).

Não retorna nada.