Spout
Supported platforms:
Available since: Gideros 2023.2
Description
Spout lets applications on the same Windows computer share live video textures.
This plugin broadcasts a Gideros texture to other programs (OBS Studio, Resolume Arena, TouchDesigner, MadMapper, another Gideros app…) and ingests such a stream back into a Gideros texture.
The plugin is a native Windows DLL and is only available in the Windows desktop player and in exported Windows desktop applications.
Enable it in Gideros Studio → Plugins before use.
require "spout"
Both classes work in Spout's memory share mode, which means 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 1280×720 rather than 3840×2160). 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. === Example === Send the Gideros screen and receive it back in the same application (a loopback test that needs no other software): require "spout" local SENDER_NAME = "Gideros_Live_Output" local W, H = 480, 360 -- what we broadcast local scene = Sprite.new() stage:addChild(scene) local ball = Shape.new() ball:setFillStyle(Shape.SOLID, 0x00ffff) ball:beginPath() ball:drawCircle(0, 0, 40) 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() local receiverRT = RenderTarget.new(W, H) 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) preview:setTexture(receiverRT) end if name and name ~= "" then boundName = name end end) Receiving from another application, letting the user pick the sender: require "spout" local receiver = SpoutReceiver.new() -- list the senders currently running on this machine for _, s in ipairs(receiver:findSenders()) do print(s.name, s.width, s.height) end -- connect to one of them and create a texture of the right size local ok, name, w, h = receiver:bind("OBS-Studio", false) local rt = RenderTarget.new(w, h) local texW, texH = w, h local preview = Bitmap.new(rt) stage:addChild(preview) stage:addEventListener(Event.ENTER_FRAME, function(e) -- keep the name Spout reports back, the sender may be renamed or replaced local connected, actualName, aw, ah = receiver:receiveTexture(rt, name) name = actualName or name if connected and aw and ah and (aw ~= texW or ah ~= texH) then -- the sender changed size, the receiving texture has to match it texW, texH = aw, ah rt = RenderTarget.new(texW, texH) preview:setTexture(rt) end end) {|- | style="width: 50%; vertical-align:top;"| === Methods === SpoutSender.new creates a Spout sender SpoutSender:sendTexture broadcasts a texture SpoutReceiver.new creates a Spout receiver SpoutReceiver:bind connects the receiver to a sender SpoutReceiver:receiveTexture receives a frame into a texture SpoutReceiver:findSenders lists the available senders | style="width: 50%; vertical-align:top;"| === Events === none === Constants === none |} === 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 === * SpoutReceiver: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 SpoutReceiver:findSenders or SpoutReceiver:bind rather than to a hard-coded string. * SpoutReceiver: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. * SpoutReceiver: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 SpoutReceiver:receiveTexture from Event.ENTER_FRAME.
Available since: Gideros 2023.2 === Description === Broadcasts a Gideros texture as a Spout sender, so that other Spout-enabled applications on the same Windows computer can display it. require "spout" 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. === Example === require "spout" local W, H = 1280, 720 local sender = SpoutSender.new("Gideros_Live_Output", W, H) local rt = RenderTarget.new(W, H) local scene = Sprite.new() stage:addChild(scene) -- ... populate scene ... stage:addEventListener(Event.ENTER_FRAME, function(e) rt:clear(0x000000, 1.0) rt:draw(scene) local sent = sender:sendTexture(rt) -- sent is false if the frame could not be published end) {|- | style="width: 50%; vertical-align:top;"| === Methods === SpoutSender.new creates a Spout sender SpoutSender:sendTexture broadcasts a texture | style="width: 50%; vertical-align:top;"| === Events === none === Constants === none |} === Method reference === ==== SpoutSender.new ==== Creates a new sender and registers it on the machine. SpoutSender.new(name, width, height) name: (string) the sender name other applications will see, for example "Gideros_Live_Output". It must be unique on the machine, Spout appends _1, _2, … when it is already registered width: (number) width of the shared stream in pixels height: (number) height of the shared stream in pixels Returns (SpoutSender) the new sender object ==== SpoutSender:sendTexture ==== Publishes one frame to every connected receiver. sender:sendTexture(texture) texture: (TextureBase) the texture to broadcast, usually a RenderTarget of the sender's size Returns (boolean) true if the frame has been published The texture is read back to the CPU and written to Spout's shared memory, so the sender size and the texture size should match. The image is flipped vertically on the way out, receivers get it the right way up.
Available since: Gideros 2023.2 === Description === 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. require "spout" The receiving texture must be exactly the size of the sender. Spout reports the sender's real name and size from SpoutReceiver:bind and SpoutReceiver: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. === Example === Receive from a chosen sender and display the stream: require "spout" local receiver = SpoutReceiver.new() -- pick the first sender available on the machine local senders = receiver:findSenders() if #senders == 0 then print("no Spout sender running") return end local ok, name, w, h = receiver:bind(senders[1].name, false) if not ok then print("could not connect to " .. senders[1].name) return end local texW, texH = w, h local rt = RenderTarget.new(texW, texH) local bmp = Bitmap.new(rt) stage:addChild(bmp) stage:addEventListener(Event.ENTER_FRAME, function(e) local connected, actualName, aw, ah = receiver:receiveTexture(rt, name) if actualName and actualName ~= "" then name = actualName end if connected and aw and ah and (aw ~= texW or ah ~= texH) then -- the sender was resized: rebuild the receiving texture texW, texH = aw, ah rt = RenderTarget.new(texW, texH) bmp:setTexture(rt) elseif not connected then -- the sender is gone, keep polling end end) {|- | style="width: 50%; vertical-align:top;"| === Methods === SpoutReceiver.new creates a Spout receiver SpoutReceiver:bind connects the receiver to a sender SpoutReceiver:receiveTexture receives a frame into a texture SpoutReceiver:findSenders lists the available senders | style="width: 50%; vertical-align:top;"| === Events === none === Constants === none |} === Method reference === ==== SpoutReceiver.new ==== Creates a new receiver. SpoutReceiver.new() Returns (SpoutReceiver) the new receiver object. It is not connected to anything until SpoutReceiver:bind or SpoutReceiver:receiveTexture is called ==== SpoutReceiver:bind ==== Connects the receiver to a sender, and reports the sender's real name and size. local ok, name, width, height = receiver:bind(name, active) name: (string) the sender to connect to active: (boolean) when true Spout ignores name and connects to the sender currently flagged as active on the machine. Pass false to connect to the given name (optional, default = false) Returns (boolean) true if the connection succeeded Returns (string) the name of the sender that was actually connected Returns (number) the sender width Returns (number) the sender height Connecting to a name that is not running returns false, call it again later. This method re-creates Gideros' internal GL textures, so use it when connecting or switching sender rather than every frame. ==== SpoutReceiver:receiveTexture ==== Copies the sender's current frame into a texture. Call it once per frame. local ok, name, width, height = receiver:receiveTexture(texture, name) texture: (TextureBase) the texture the frame is copied into, usually a RenderTarget. It must be the sender's size name: (string) the sender to receive from, normally the name returned by the previous call Returns (boolean) true when the receiver is connected to a sender Returns (string) the name of the connected sender Returns (number) the sender width Returns (number) the sender height Call it from Event.ENTER_FRAME. A frame is only copied when the name, the size and the format match the sender the receiver is already connected to. When the sender appears, changes name, changes size or changes format, Spout re-initialises and this call returns true without copying a frame, reporting the new name and size so the caller can adjust its texture. Always store the returned name and rebuild the receiving texture when the size changes, otherwise the picture stays frozen while the call keeps succeeding. ==== SpoutReceiver:findSenders ==== Lists the Spout senders currently registered on the machine. local senders = receiver:findSenders() Returns (table) an array of senders, each one a table with the fields name (string), width (number) and height (number) local senders = SpoutReceiver.new():findSenders() for i, s in ipairs(senders) do print(i, s.name, s.width .. "x" .. s.height) end -- 1 OBS-Studio 1920x1080 -- 2 Gideros_Live_Output 480x360 The list contains every sender registered on the machine, including the one created by the running application.