# API di scripting Lua di pxstud.io — Pixel

> Parte del riferimento di scripting Lua di pxstud.io, la cui panoramica (https://pxstud.io/it/docs/scripting.md) ne spiega le convenzioni. I gruppi di opzioni e i tipi a cui rimanda sono in https://pxstud.io/it/docs/scripting/option-groups.md e https://pxstud.io/it/docs/scripting/types.md. Tutto in un unico file (in inglese): https://pxstud.io/llms-full.txt. L'indice dell'intero sito (in inglese): https://pxstud.io/llms.txt.

### Pixel
Lettura e scrittura di pixel come liste RGBA piatte (costruite sulle Image; mai ritagliate sulla selezione né specchiate), riempimenti e capovolgimenti dell'intera selezione, e il contagocce.

#### `app.clearSelection(layerId, frameId)` — modifica, annullabile, rifiutata su un livello bloccato
Cancella la selezione rendendola completamente trasparente, ritagliando il cel su ciò che resta (un cel svuotato viene rimosso, insieme a ogni fotogramma collegato); se non c'è nulla di selezionato, rimuove il cel di questo fotogramma (un fotogramma collegato perde solo il collegamento). Nel livello Sfondo tutto viene cancellato con il colore di sfondo.

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

Non restituisce nulla.

#### `app.fillSelection(layerId, frameId, color, opts?)` — modifica, annullabile, rifiutata su un livello bloccato
Riempie la selezione (o l'intero cel, se non c'è nulla di selezionato) con un colore pieno. Un riempimento semplice (copy) a meno che non venga indicato `ink`: a differenza dei comandi di disegno non prende mai l'inchiostro del contesto di modifica, come Modifica > Riempi.

- `layerId` (string)
- `frameId` (string)
- `color` (table) — { r, g, b, a }, ciascuno da 0 a 255.
- `opts` (table, facoltativo)
  - `ink` (Ink: "copy" | "simple" | "lock-alpha" | "shading"; predefinito "copy") — copy sostituisce i pixel, simple compone l'alfa, lock-alpha ricolora solo i pixel visibili, shading fa avanzare i colori lungo `shades`. Ignorato da erase.
  - `shades` (a list of colors ("#rrggbb[aa]" or { r, g, b, a }), in ramp order) — La rampa lungo cui avanza lo shading. Un pixel il cui colore non è nella lista resta intatto; un pixel alla fine della lista resta lì.
  - `shadeReverse` (boolean; predefinito false) — Lo shading avanza all'indietro in `shades` (il tasto destro del mouse nell'interfaccia) invece che in avanti.

Non restituisce nulla.

#### `app.flipCelRegion(layerId, frameId, axis)` — modifica, annullabile, rifiutata su un livello bloccato
Capovolge i pixel selezionati (o l'intero cel, se non c'è nulla di selezionato) entro i limiti della selezione: ogni pixel selezionato si sposta nella posizione speculare, quelli lasciati indietro vengono cancellati (con il colore di sfondo nel livello Sfondo) e anche il riquadro di selezione si capovolge.

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

Non restituisce nulla.

#### `app.getCompositePixels(frameId, x, y, width, height)` — pura
I pixel di app.getCompositeImage come lista RGBA piatta nella forma di app.getPixels. Al massimo 262144 pixel per chiamata.

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

Restituisce (table): Lista RGBA piatta.

#### `app.getPixels(layerId, frameId, x, y, width, height)` — pura
Legge un rettangolo width x height in (x, y) del cel di un livello/fotogramma come lista RGBA piatta (lunghezza width*height*4, per righe: il pixel (px, py) inizia all'indice (py*width + px)*4 + 1), nella forma che app.setPixels accetta. I pixel senza cel vengono letti come trasparenti (0, 0, 0, 0). Costruita su app.getImage, che è più veloce quando non ti serve una lista. Al massimo 262144 pixel per chiamata.

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

Restituisce (table): Lista RGBA piatta.

#### `app.sampleColor(frameId, x, y, layerId?)` — legge
Il contagocce: il colore in (x, y) come { r, g, b, a }, per impostazione predefinita ciò che la tela mostra in quel punto (livelli visibili miscelati con la loro opacità e le loro modalità di fusione), oppure il colore di un solo livello quando viene indicato layerId.

- `frameId` (string)
- `x` (number)
- `y` (number)
- `layerId` (string, facoltativo) — Campiona solo questo livello. Se omesso = tutti i livelli visibili composti, come appaiono sullo schermo.

Restituisce (table): { r, g, b, a }, ciascuno da 0 a 255.

#### `app.setPixels(layerId, frameId, x, y, width, height, pixels)` — pura
Sovrascrive un rettangolo width x height in (x, y) del cel di un livello/fotogramma con una lista RGBA piatta (la forma di app.getPixels), come un unico app.putImage. Scrittura grezza: mai ritagliata sulla selezione né specchiata. Negli sprite indicizzati e in scala di grigi i colori vengono mappati come li mappa img:setPixel. Al massimo 262144 pixel per chiamata.

- `layerId` (string)
- `frameId` (string)
- `x` (number)
- `y` (number)
- `width` (number)
- `height` (number)
- `pixels` (table) — Lista RGBA piatta, lunghezza width*height*4, per righe: il pixel (px, py) è all'indice (py*width + px)*4 + 1 (r, poi g, b, a; ciascuno da 0 a 255).

Non restituisce nulla.