Spout: Difference between revisions
No edit summary |
No edit summary |
||
| Line 37: | Line 37: | ||
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). | 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)''' | '''Loopback (send and receive in one app)''' | ||
<syntaxhighlight lang="lua"> | <syntaxhighlight lang="lua"> | ||
| Line 94: | Line 94: | ||
end | end | ||
if name and name ~= "" then boundName = name end | if name and name ~= "" then boundName = name end | ||
end) | end) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| Line 151: | Line 120: | ||
[[Spout.sender:sendTexture|sender:sendTexture]] ''publishes one frame to every connected receiver''<br/><!--GIDEROSMTD:sender:sendTexture(texture) publishes one frame to every connected receiver--> | [[Spout.sender:sendTexture|sender:sendTexture]] ''publishes one frame to every connected receiver''<br/><!--GIDEROSMTD:sender:sendTexture(texture) publishes one frame to every connected receiver--> | ||
[[Spout.receiver:bind|receiver:bind]] ''connects the receiver to a sender''<br/><!--GIDEROSMTD:receiver:bind(name, active) connects the receiver to a sender--> | [[Spout.receiver:bind|receiver:bind]] ''connects the receiver to a sender''<br/><!--GIDEROSMTD:receiver:bind(name, active) connects the receiver to a sender--> | ||
[[Spout.receiver:findSenders|receiver:findSenders]] ''lists the Spout senders currently registered on the machine''<br/><!--GIDEROSMTD:receiver:findSenders() lists the Spout senders currently registered on the machine--> | |||
[[Spout.receiver:receiveTexture|receiver:receiveTexture]] ''copies the sender's current frame into a texture''<br/><!--GIDEROSMTD:receiver:receiveTexture(texture, name) copies the sender's current frame into a texture--> | [[Spout.receiver:receiveTexture|receiver:receiveTexture]] ''copies the sender's current frame into a texture''<br/><!--GIDEROSMTD:receiver:receiveTexture(texture, name) copies the sender's current frame into a texture--> | ||
| style="width: 50%; vertical-align:top;"| | | style="width: 50%; vertical-align:top;"| | ||
Revision as of 00:34, 13 November 2026
Supported platforms: ![]()
![]()
Available since: Gideros 2019.5
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.
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
MethodsSpoutSender.new creates a new sender sender:sendTexture publishes one frame to every connected receiver |