Spout: Difference between revisions
wip |
wip |
||
| Line 4: | Line 4: | ||
=== Description === | === Description === | ||
Spout Plugin Documentation for Gideros | |||
===================================== | |||
Supported platforms: Windows (win32) | |||
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, vMix, 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. | |||
To add Spout support to your application you call: | |||
require "spout" | |||
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. | |||
Methods: | |||
SpoutSender.new(name, width, height) | |||
Creates a new sender and registers it on the machine. | |||
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. | |||
sender:sendTexture(texture) | |||
Publishes one frame to every connected receiver. | |||
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. | |||
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). | |||
Methods: | |||
SpoutReceiver.new() | |||
Creates a new receiver. It is not connected to anything until bind() or | |||
receiveTexture() is called. | |||
Returns: (SpoutReceiver) the new receiver object. | |||
receiver:bind(name, active) | |||
Connects the receiver to a sender, and reports the sender's real name and | |||
size. | |||
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. | |||
receiver:receiveTexture(texture, name) | |||
Copies the sender's current frame into a texture. Call it once per frame. | |||
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. | |||
receiver:findSenders() | |||
Lists the Spout senders currently registered on the machine. | |||
Returns: (table) an array of senders, each one a table with the fields | |||
name (string), width (number) and height (number). | |||
The list contains every sender registered on the machine, including the | |||
one created by the running application, which is what makes a loopback | |||
test possible. | |||
Events | |||
------ | |||
none | |||
Constants | |||
--------- | |||
none | |||
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) | |||
Example: receive from another application | |||
---------------------------------------- | |||
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) | |||
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. | |||
- The receiving RenderTarget must be created with extend = false: | |||
RenderTarget.new(w, h, true, false, false, false, nil, false), or | |||
RenderTarget.new(w, h, true, { extend = false }) on Gideros 2024.3 and later. | |||
A render target left at its default (extended to a power of two) accepts the | |||
frames (receiveTexture returns true and keeps doing so) but the copied pixels | |||
never appear where the target is displayed, so the picture stays black. | |||
- 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. | |||
Spout lets applications on the same Windows computer share live video textures. | Spout lets applications on the same Windows computer share live video textures. | ||
Revision as of 14:25, 12 November 2026
Supported platforms:
Available since: Gideros 2023.2
Description
Spout Plugin Documentation for Gideros
=========================
Supported platforms: Windows (win32) 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, vMix, 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.
To add Spout support to your application you call:
require "spout"
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.
Methods:
SpoutSender.new(name, width, height)
Creates a new sender and registers it on the machine.
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.
sender:sendTexture(texture)
Publishes one frame to every connected receiver.
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.
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).
Methods:
SpoutReceiver.new()
Creates a new receiver. It is not connected to anything until bind() or
receiveTexture() is called.
Returns: (SpoutReceiver) the new receiver object.
receiver:bind(name, active)
Connects the receiver to a sender, and reports the sender's real name and
size.
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.
receiver:receiveTexture(texture, name)
Copies the sender's current frame into a texture. Call it once per frame.
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.
receiver:findSenders()
Lists the Spout senders currently registered on the machine.
Returns: (table) an array of senders, each one a table with the fields
name (string), width (number) and height (number).
The list contains every sender registered on the machine, including the
one created by the running application, which is what makes a loopback
test possible.
Events
none
Constants
none
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)
Example: receive from another application
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)
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.
- The receiving RenderTarget must be created with extend = false:
RenderTarget.new(w, h, true, false, false, false, nil, false), or
RenderTarget.new(w, h, true, { extend = false }) on Gideros 2024.3 and later.
A render target left at its default (extended to a power of two) accepts the
frames (receiveTexture returns true and keeps doing so) but the copied pixels
never appear where the target is displayed, so the picture stays black.
- 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.
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.