|
|
| (6 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| __NOTOC__ | | __NOTOC__ |
| '''Supported platforms:''' [[File:Platform pc.png]][[File:Platform win32.png]] | | '''Supported platforms:''' [[File:Platform pc.png]][[File:Platform win32.png]]<br/> |
| '''Available since:''' Gideros 2019.5 | | '''Available since:''' Gideros 2018.6.3 |
|
| |
|
| === Description === | | === Description === |
| Spout lets applications on the same Windows computer share live video textures. | | Spout lets applications on the same Windows computer share live video textures. Please see: |
| | *'''https://spout.zeal.co/''' |
| | *'''https://github.com/leadedge/Spout2''' |
| | *https://spoutgl-site.netlify.app/#CClass:Spout (for reference only) |
|
| |
|
| To add Spout support to your application you call: | | To add Spout support to your application you call: |
| Line 11: |
Line 14: |
| </syntaxhighlight> | | </syntaxhighlight> |
|
| |
|
| Enable it in Gideros Studio -> Plugins before use. | | 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. | | 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. |
| Line 33: |
Line 38: |
| 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. | | 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. |
|
| |
|
| === Examples === | | 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 90: |
Line 97: |
| end | | end |
| if name and name ~= "" then boundName = name end | | if name and name ~= "" then boundName = name end |
| end)
| |
| </syntaxhighlight>
| |
|
| |
| '''Receive from another application'''
| |
| <syntaxhighlight lang="lua">
| |
| 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, true, false, false, false, nil, false)
| |
| 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 was resized: rebuild the receiving texture
| |
| texW, texH = aw, ah
| |
| rt = RenderTarget.new(texW, texH, true, false, false, false, nil, false)
| |
| preview:setTexture(rt)
| |
| end
| |
| end) | | end) |
| </syntaxhighlight> | | </syntaxhighlight> |
| Line 139: |
Line 115: |
| *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 | | *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 |
|
| |
|
| | {|- |
| | | style="width: 50%; vertical-align:top;"| |
| | === Methods === |
| | [[Spout.SpoutSender.new|SpoutSender.new]] ''creates a new sender''<br/><!--GIDEROSMTD:SpoutSender.new(name, width, height) creates a new sender--> |
| | [[Spout.SpoutReceiver.new|SpoutReceiver.new]] ''creates a new receiver''<br/><!--GIDEROSMTD:SpoutReceiver.new() creates a new 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: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--> |
|
| |
|
| | | | style="width: 50%; vertical-align:top;"| |
| | | |} |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| | |
| 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 [https://github.com/Off-World-Live/obs-spout2/releases 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. {{GIDEROS IMPORTANT LINKS}} __NOTOC__ '''Supported platforms:''' [[File:Platform win32.png]] | |
| '''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. {{GIDEROS IMPORTANT LINKS}} __NOTOC__ '''Supported platforms:''' [[File:Platform win32.png]]
| |
| '''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.
| |
|
| |
|
| {{GIDEROS IMPORTANT LINKS}} | | {{GIDEROS IMPORTANT LINKS}} |
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:
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