Spout: Difference between revisions

From GiderosMobile
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.


Supported platforms:

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.


Supported platforms:

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.