Spout

From GiderosMobile
(Redirected from Category:Spout)

Supported platforms:
Available since: Gideros 2018.6.3

Description

Spout lets applications on the same Windows computer share live video textures. Please see:

To add Spout support to your application you call:

require "spout"

Enable Spout in Gideros Studio -> Plugins before use.

Gideros Spout Sender and Receiver demo projects: Media:Spout_sender_receiver_demo.zip (tip: right click and Save Link As)

This plugin broadcasts a Gideros texture to other programs (OBS Studio, Resolume Arena, TouchDesigner, MadMapper, vMix, another Gideros app*) and ingests such a stream back into a Gideros texture.

*tested: Resolume Arena and Magic Music Visuals both could receive the video sent by Gideros Spout plugin. On the other hand the Gideros receiver did not receive the video from 'Spout Sender Demo' nor from Resolume Arena. Also, nothing received in OBS Studio + spoutplugin when sent from gideros sender.
Gideros apps (sender and receiver), one sender and multiple receivers, all the receivers see and update the sender 🙂

Both classes work in Spout's "memory share" mode: every frame is transferred through shared memory. The sending side reads its texture back to the CPU and the receiving side uploads it again. This makes any sender work (OpenGL or DirectX) but a full-resolution frame costs CPU time, so prefer sizes close to what you actually need (for example 1280x720 rather than 3840x2160).

The image is flipped vertically for you on both sides (OpenGL and DirectX use opposite texture origins), so a received frame is already the right way up.

SpoutSender

Broadcasts a Gideros texture as a Spout sender, so that other Spout-enabled applications on the same Windows computer can display it.

A sender has a name and a fixed size, and is visible to other applications as soon as it is created. Broadcast a texture of that size from your frame loop; the receiving side sees the frames live.

SpoutReceiver

Connects to a Spout sender running on the same Windows computer and copies its frames into a Gideros texture. The texture is then used like any other texture, typically through a Bitmap.

The receiving texture must be exactly the size of the sender. Spout reports the sender's real name and size from bind() and receiveTexture(), and these values have to be used: when the sender changes or is resized, Spout re-initialises and reports the change instead of copying a frame, and the receiving texture has to be re-created at the new size.

It also has to be a non-extended RenderTarget: by default Gideros stores a render target in a texture rounded up to a power of two (480x360 lives in a 512x512 texture) and Spout's copy never reaches the area that is displayed, which leaves a black picture while receiveTexture() keeps returning true. Pass extend = false (the 8th argument, or the "extend" field of the options table on Gideros 2024.3 and later).

Example

Loopback (send and receive in one app)

    require "spout"

    local SENDER_NAME = "Gideros_Live_Output"
    local W, H = 480, 360

    -- what we broadcast
    local scene = Sprite.new()
    local ball = Shape.new()
    ball:setFillStyle(Shape.SOLID, 0x00ffff)
    ball:beginPath()
    ball:moveTo(24, 0)
    for i = 1, 32 do
        local a = (i / 32) * math.pi * 2
        ball:lineTo(math.cos(a) * 24, math.sin(a) * 24)
    end
    ball:closePath()
    ball:endPath()
    ball:setPosition(W * 0.5, H * 0.5)
    scene:addChild(ball)

    -- sender
    local sender = SpoutSender.new(SENDER_NAME, W, H)
    local senderRT = RenderTarget.new(W, H)

    -- receiver
    local receiver = SpoutReceiver.new()
    -- extend = false is required, see the Notes
    local receiverRT = RenderTarget.new(W, H, true, false, false, false, nil, false)
    local boundName, texW, texH = SENDER_NAME, W, H

    local preview = Bitmap.new(receiverRT)
    preview:setPosition(200, 0)
    stage:addChild(preview)

    local t = 0
    stage:addEventListener(Event.ENTER_FRAME, function(e)
        t = t + 1 / 60
        ball:setPosition(W * 0.5 + math.sin(t) * 100,
                        H * 0.5 + math.cos(t) * 60)

        -- 1. render and broadcast the frame
        senderRT:clear(0x0d1117, 1.0)
        senderRT:draw(scene)
        sender:sendTexture(senderRT)

        -- 2. receive a frame into our own texture
        local ok, name, w, h = receiver:receiveTexture(receiverRT, boundName)
        if ok and w and h and (w ~= texW or h ~= texH) then
            -- the sender changed size: the receiving texture must match it
            texW, texH = w, h
            receiverRT = RenderTarget.new(w, h, true, false, false, false, nil, false)
            preview:setTexture(receiverRT)
        end
        if name and name ~= "" then boundName = name end
    end)

Connecting other applications

  • OBS Studio: install the obs-spout2 plugin, then add a "Spout2 Capture" source to a scene and pick the Gideros sender in its properties. To send OBS into Gideros, add a "Spout2 Output" filter or output and receive it with SpoutReceiver
  • Resolume Arena / Avenue: enable Output -> Spout and select the Gideros sender, or send Resolume's output to Gideros through a Spout input clip
  • TouchDesigner: use a "Spout In" / "Spout Out" TOP
  • Gideros to Gideros: run two Gideros applications on the same machine, one sending and one receiving

Notes

  • findSenders() also lists the sender created by the running application itself, which is what makes a loopback test possible
  • Sender names are global to the machine. If a name is already registered (for example by a previous run), Spout renames the new sender to name_1, name_2, ... so always connect to the name returned by findSenders() or bind() rather than to a hard-coded string
  • receiveTexture() only copies a frame when the sender name, the sender size and the texture format all match the sender the receiver is already connected to. On a connection or a size change it returns true without copying anything and reports the new name and size, so the receiving texture (a RenderTarget) has to be rebuilt to that size. A receiver that ignores the returned values keeps a frozen picture while still reporting success
  • bind() re-creates Gideros' internal GL textures when it connects, so call it when connecting or switching sender, never every frame
  • There is no event for incoming frames: poll receiveTexture() from Event.ENTER_FRAME
  • When a Bitmap displays a RenderTarget whose GL texture is updated externally (by Spout), call bitmap:setTexture(renderTarget) after a successful receive so the Bitmap picks up the new pixels
  • Prefer sizes close to what you need (e.g. 1280x720) to limit CPU cost, because memory-share mode reads the texture back to the CPU on the sender side

Methods

SpoutSender.new creates a new sender
SpoutReceiver.new creates a new receiver

sender:sendTexture publishes one frame to every connected receiver
receiver:bind connects the receiver to a sender
receiver:findSenders lists the Spout senders currently registered on the machine
receiver:receiveTexture copies the sender's current frame into a texture