DMX mapování na LED pásky

Jak ve firmware 0.12.11 mapovat RGB data ze sACN nebo Art-Net vstupu na jeden nebo více fyzických LED pásků pomocí nativního Berry helperu.

K čemu `map()` slouží

DMX.map() je nativní C++ helper dostupný z Berry Scriptu. Přemapuje konkrétní DMX byte buffer na jeden nebo více fyzických LED portů.

Používá se ve chvíli, kdy kontroler přijímá RGB kanály ze sACN nebo Art-Net universu a má je rychle vyrenderovat na fyzický LED pásek nebo několik LED pásků. Přepočet běží v C++ části firmware, takže Berry Script nemusí dělat per-pixel for loop.

Typicky se volá z render callbacku vstupního SACN nebo Art-Net IO. Tento callback dostane poslední přijatý DMX buffer a v render fázi ho může přemapovat do bufferů PIX1, PIX2 nebo dalších portů. Fyzické porty se potom zobrazí standardní cestou firmware.

Pozor na rozdíl mezi IO labelem a IO typem. Label v io[...] je label_t, takže může mít maximálně 5 znaků. Pro Art-Net proto použijte například label ARTN a v konfiguraci nastavte "type": "ARTNET".

Není potřeba držet vlastní ready flag ani psát render callbacky na fyzické porty. Důležité je jen to, že mapování je explicitně navázané na vstupní DMX buffer:

io["SACN"].render = def(channels, offset, frames_received, bytes_received)
    DMX.map(channels, 120, 255, io["PIX1"], 340, true, io["PIX2"], 340, false)
end

Typické použití:

jeden sACN nebo Art-Net universe se roztáhne na jeden fyzický LED pásek
jeden sACN nebo Art-Net universe se rozdělí na dvě větve jednoho svítidla
jeden sACN nebo Art-Net universe se rozdělí na čtyři samostatné LED výstupy
menší počet logických RGB barev se plynule interpoluje na více fyzických pixelů

Tvar volání

DMX.map(channels, [logical_pixels], [fade], port, [physical_pixels], [reverse], ...)

Stejná signatura zapsaná s pojmenovanými argumenty:

DMX.map(
    channels,          # bytes, prijaty DMX RGB buffer
    logical_pixels?,   # int, default = vsechny RGB pixely v bufferu
    fade?,             # int 0..255, default = 255
    port,
    physical_pixels?,  # int, default = dostupna velikost portu
    reverse?,          # bool, default = false
    ...
) -> bool

Mentální model pro jedno volání je:

map(
  channels: bytes,
  logical_pixels?: number,
  fade?: number,
  ...targets: {
    port: PORT,
    physical_pixels?: number,
    reverse?: boolean
  }[]
): boolean

Parametry jsou záměrně poziční:

channels je bytes buffer předaný do io["SACN"].render nebo io["ARTN"].render.
logical_pixels je volitelný počet RGB pixelů ze vstupu. Pokud ho neuvedete, použije se celý dostupný RGB buffer. Pokud ho uvedete, musí vstupní buffer obsahovat přesně logical_pixels * 3 RGB bajtů.
fade je volitelná síla interpolace mezi sousedními logickými pixely. Hodnota 255 znamená plynulý přechod, hodnota 0 drží nejbližší logickou barvu bez prolínání.
port je fyzický PORT výstup, například io["PIX1"].
physical_pixels je volitelný počet fyzických pixelů, které se mají na daném portu zapsat. Pokud chybí nebo je 0, použije se dostupná velikost portu.
reverse je volitelný boolean. true zapisuje fyzické pixely v opačném směru.

Každý další port začíná další výstupní větev. Zdrojový RGB rozsah se mezi zadané porty rozdělí rovnoměrně.

Jeden universe na jeden pásek

Příklad: 120 RGB hodnot ze sACN se plynule roztáhne na 680 fyzických pixelů na PIX1.

io["SACN"].render = def(channels, offset, frames_received, bytes_received)
    DMX.map(channels, 120, 255, io["PIX1"], 680)
end

Pro Art-Net je tvar stejný, jen callback visí na Art-Net IO. V příkladu se používá krátký label ARTN, který splňuje limit maximálně 5 znaků:

io["ARTN"].render = def(channels, offset, frames_received, bytes_received)
    DMX.map(channels, 120, 255, io["PIX1"], 680)
end

Jeden universe na dvě větve

Příklad: první polovina RGB vstupu jde na PIX1, druhá polovina na PIX2. PIX1 je fyzicky zapojený obráceně, proto má reverse = true.

io["ARTN"].render = def(channels, offset, frames_received, bytes_received)
    DMX.map(
        channels,
        120, 255,
        io["PIX1"], 340, true,
        io["PIX2"], 340, false
    )
end

Jeden universe na čtyři pásky

Příklad: 120 logických RGB pixelů se rozdělí po 30 logických pixelech na čtyři fyzické výstupy. Každý výstup si může říct vlastní fyzickou délku a směr.

io["SACN"].render = def(channels, offset, frames_received, bytes_received)
    DMX.map(
        channels,
        120, 255,
        io["PIX1"], 170, false,
        io["PIX2"], 170, false,
        io["PIX3"], 170, true,
        io["PIX4"], 170, true
    )
end

Telemetrie příjmu

Pro výkonové smoke testy je důležité neměřit počet Berry render callbacků, ale skutečně přijaté DMX framy a bajty. Ve firmware 0.12.11 proto callback dostává i souhrn přijatých framů a bajtů od posledního volání.

io["SACN"].cb = def(channels, offset, frames_received, bytes_received)
    print("prijato frame", frames_received, "bajtu", bytes_received)
end

Stejné čtyři argumenty dostává i Art-Net callback:

io["ARTN"].cb = def(channels, offset, frames_received, bytes_received)
    print("prijato frame", frames_received, "bajtu", bytes_received)
end

Pojmenovaná signatura callbacku:

io["SACN"].cb = def(
    channels,          # byte buffer s prijatymi DMX sloty
    offset,            # prvni DMX kanal, ktery buffer reprezentuje
    frames_received,   # pocet prijatych sACN framu od posledniho callbacku
    bytes_received     # pocet prijatych DMX datovych bajtu od posledniho callbacku
)
end

Praktická pravidla

DMX.map() pouze zapisuje barvy do pixel bufferů jednotlivých portů. Fyzické odeslání na LED pásek stále dělá standardní port render/show krok firmware.

io["SACN"].render a io["ARTN"].render se volají před implicitním renderem fyzických portů. Proto je vhodné z nich naplnit port buffery a portům nechat jejich běžné zobrazení.

Callback se volá i bez TNGL segmentu. To je užitečné pro instalace, kde snímky animace vyrábí externí DMX konzole a kontroler je pouze přijímá, přemapuje a zobrazí.

Aktuální implementace je určená pro RGB vstupní data. Pokud přijímáte jiný DMX order než RGB, nastavte vstupní IO na RGB nebo data před DMX.map() převeďte na packed RGB buffer.

V jednom volání lze použít až osm výstupních portů.