Stream-Server

Stream-Server is an EGLStream based application that is used to connect different combinations of producers and consumers at runtime. Stream-Server facilitates different types of EGLStream producers (NvMedia, CUDA, OpenGL), producing buffers that can be displayed on EGL consumers running on different window systems (Wayland, X11, egldevice, etc.). Stream-Server loads different dynamic libraries that represent different plugins, depending on the configuration.

Stream-Server Architecture

Stream-Server can run in any VM on the target. Plugins are used to get an EGLStream handle by attaching a consumer or a producer to it using sockets. The plugins then act as hooks and are matched to their partner based on the configuration provided. The configuration can be modified either via command line arguments or by a JSON file.
There are two types of plugins:
1. Input Plugin – This type of plugin is used to connect to an EGLStream producer app. The producer app uses UNIX domain or INET sockets to connect with the respective input plugin. Two important plugins in this category are CrossProcInput and CrossPartInput, which are used to get cross-process and cross-partition EGLStreams from the external producer app.
2. Output Plugin –This type of plugin is used to attach a consumer to an EGLStream coming from an external application via input plugin. This communication is again achieved using UNIX domain or INET sockets. Based on the functionality needed, there are two broad categories of output plugins. The first category is display-based output plugins, which display stream frames on the monitor. The second category is forward- output plugins, which serve as an intermediary for an external EGLStream consumer app.
The following image shows Stream-Server running with different external producers and consumers.

Location of Stream-Server and Plugins

The Stream-Server binary is located in the /usr/local/bin directory. This path is added as a part of the bin $PATH variable and therefore you can run the binary from anywhere on the target. All available plugins have an associated dynamic library in the /usr/lib/streamserver directory. The plugin library names are prefixed by libss to distinguish them from other graphics libraries.

Running Stream-Server

Use the following command to list help options:
$ stream-server -h
Use the following command to list the available plugins:
$ stream-server -l
Use the following command to list help options for a specific plugin:
$ stream-server –pluginHelp <plugin>

Configuring Stream-Server

The configuration may be controlled using one of two methods: JSON file or command line arguments. They are mutually exclusive.

JSON File Based Configuration

This is the more versatile means of configuring Stream-Server. Any number of inputs and outputs may be created and connected.
A JSON formatted file must be referenced at startup using the -c, --config option. The JSON file is broken into sections, one per component to initialize.
Here is a sample test.json configuration file:
{
"Inputs": [{
"name": "CrossProcInput1",
"type": "CrossProcInput",
"output": "EGLOutputOutput1",
"socket": "/tmp/ss/ss1"
},{
"name": "CrossPartInput1",
"type": "CrossPartInput",
"output": "EGLOutputOutput2",
"port": "8889"
}],
"Outputs": [{
"name": "EGLOutputOutput1",
"type": "EGLOutputOutput",
"windowSize": "1920X1080",
"dispNo": "1",
"layerNo": "0"
},{
"name": "EGLOutputOutput2",
"type": "EGLOutputOutput",
"windowSize": "1080X720",
"dispNo": "1",
"layerNo": "1"
}]
}
There are two input and two output plugins that are mentioned in the test.json configuration file above. Between the two input plugins, one is of type CrossProcInput and the second is of type CrossPartInput, named CrossProcInput1 and CrossPartInput1, respectively. For the output plugins, both plugins have the same type, EGLOutputOutput, and are named EGLOutputOutput1 and EGLOutputOutput2.
For the input plugin, there is a parameter called output that tells the Stream-Server to form mapping between input and output plugins. CrossProcInput1 and CrossPartInput1 connect to EGLOutputOutput1 and EGLOutputOutput2, respectively.
The CrossprocInput1 plugin uses path /tmp/ss to create a socket name ss1 to listen for the incoming cross-process EGLStream producer client’s connect request. In the same manner, CrossPartInput1 uses port number 8889 to bind a socket and uses this socket to listen for the incoming cross-partition EGLStream producer client’s connect request.
1. Create socket path on VM0:
$ mkdir –p /tmp/ss/
2. Run Stream-Server with this configuration file on VM0:
$ stream-server -c test.json
3. Run first producer on VM0:
$ ./gears –eglstreamsocket /tmp/ss/ss1 -1
4. Run second producer on VM1, assuming the IP of VM0 as seen by VM1 is 12.0.0.1:
$ ./gears –proctype producer –ip 12.0.0.1 –port 8889 -1
The first gears instance is now connected to CrossProcInput1, which in turn is connected to EGLOutputOutput1. The parameters windowsize, dispNo, and layerNo of EGLOutputOutput1 determine the display number and overlay layer number of connected displays on which a window of dimension windowsize appears.
The first gears instance appears in a window of dimension 1920 x 1080 on the 0th layer of 0th display. Likewise, the second gears instance appears in a window of dimensions 1080 x 720 on the 1st layer of 0th display.
There are many more parameters for different kinds of plugins, which are explained in the table below.
Plugin
Parameter
Optional
Description
Example
For All Plugins
name
Required
Name of the plugin.
"name": "EGLOutputOutput1"
type
Required
Type of the plugin.
"type": "EGLOutputOutput"
For All Input Plugins
output
Required
Name of the output plugin to connect with this input plugin.
"output": "EGLOutputOutput1"
For All Output Plugins
windowSize
Optional
Size of window to appear on the display or to send out through EGLStream.
"windowSize": "1920X1080"
CrossPartInput
port
Required
Port number to listen for incoming EGLStream producer.
{
"name": " CrossPartInput1",
"type": " CrossPartInput ",
"output": "ImageFileWriter",
"port": "8889"
}
CrossProcInput
socketName
Required
Socket path to listen for incoming EGLStream producer. This socket path must be created explicitly.
{
"name": " CrossProcInput1",
"type": " CrossProcInput ",
"output": "ImageFileWriter",
"socketName": "/tmp/ss/ss1"
}
TestInput
size
Required
Size of frames to be generated.
{
"name": " TestInput1",
"type": " TestInput ",
"output": "ImageFileWriter",
"size": "600X400",
"frames": "10"
}
frames
Required
Number of frames to be generated.
EGLOutputOutput
dispNo
Optional
Number of displays to show window.
{
"name": "EGLOutputOutput1",
"type": "EGLOutputOutput",
"windowSize": "1920X1080",
"dispNo": "1",
"layerNo": "0"
}
layerNo
Optional
Number of layers to show window.
ImageFileWriter
frames
Required
Number of frames to dump of disk.
{
"name": "ImageFileWriter1",
"type": "ImageFileWriter",
"windowSize": "1920X1080",
"frames": "10",
"outpath": "/tmp/ss/out"
}
 
 
outpath
Required
Directory path to dump frames into. This path must be explicitly created prior to invoking Stream-Server.
ScreenOutput
dispNo
Optional
Specifies which display to show Screen window on.
{
"name": "ScreenOutput1",
"type": "ScreenOutput",
"windowSize": "1920X1080",
"dispNo": "1",
"layerNo": "0"
}
layerNo
Optional
Specifies which layer number to show Screen window on.
WaylandOutput
ivisurfaceid
Optional
ID number of an IVI surface when used with ivi-shell.
{
"name": "WaylandOutput1",
"type": "WaylandOutput",
"windowSize": "1920X1080",
"x": "100",
"y": "100"
}
x
Optional
x offset (ivi-shell only)
y
Optional
y offset (ivi-shell only)
CrossProcOutput
socketName
Required
Socket path on which cross-process consumer client is listening.
{
"name": "CrossProcOutput1",
"type": "CrossProcOutput",
"windowSize": "1920X1080",
"socketName": "/tmp/ss/ss1"
}
CrossPartOutput
ip
Required
IP address VM where cross- partition consumer client is running.
{
"name": "CrossPartOutput1",
"type": "CrossProcOutput",
"windowSize": "1920X1080",
"ip": "12.1",
"port": "8888"
}
port
Required
Port number on which cross-partition consumer client is listening.
 
Note:
Every plugin has a name and type attribute associated with it that uniquely identifies it in the config object. The other options for the plugin are either optional or required, as indicated in the table.

Command-Line Configuration

This is the more accessible but limited means of configuring Stream-Server. It only permits configurations with precisely one input and one output.
Example:
$ stream-server --in <input_type> <input options> --out <output_type> <output options>
 
input_type: TestInput, <additional Input type plugin names as queried from modules>
output_type: ImageFileWriter, <additional output types>
 
Examples:
$ stream-server --in TestInput --size 200x200 --frames 10 --out ImageFileWriter --frames 10 --outputpath /tmp/ss/out
 
$ stream-server --in CrossPartInput -p 8888 --out EGLOutputOutput –dispNo 1 –layerNo 0