Pipe Extension
Please be sure to read the Overview page to get a general sense of
if the Pipe RoboRealm Extension is a good fit for you.
Pipe programs communicate to/from RoboRealm using a windows named pipe. This communication mechanism
is quicker than network based communication but also requires a unique pipe name
that is shared system wide. If the pipe already exists RoboRealm will connect to
that existing pipe otherwise it will run the
specified program in expectation that it creates the pipe. This allows you
to run your program from a debugged and have RoboRealm connect to that active
process for debugging purposes.
To create your own pipe program to extend RoboRealm download our example pipe program. This
example program (SwapColors) will swap the Red and Blue pixel colors in an effort to show
how image modifications can be performed. Note that the download also includes the Socket and DLL
example implementations. The example pipe program is in the single source file called main.cpp. The other files are used for VC++ project
configuration.
You will need VC++ or other C++ compiler to build the program.
Note that a pre-built executable is in the Release subfolder.
To configure RoboRealm to use a pipe based program click on the Extensions->Pipe_Program module.
The following interface elements can be specified:
Name - indicates the name or function of the module. This name is used for display
in the main RoboRealm program list area for easy identification and is also passed
to the Pipe Program as a 'name' variable that indicates the desired functionality. Using the
name variable you can use a single program to perform multiple tasks.
Program File - The name of the pipe program. This is a windows console executable program
that should create and open a windows named pipe and begin listening on that pipe for
data. Note that RoboRealm checks to see if the pipe exists and connects to it if it does. If not
RoboRealm will execute the specified program in expectation that the pipe is created and active.
Program Arguments - You can specify arguments that are passed to the pipe based program that
will appear in the argc and argv arguments of that program. This can be used to specify additional
parameters to your program in order to customize as needed.
Pipe Name - The communications pipe's name that is used to transfer image pixels and data to and
from your program. The default used is rrpipe.
Available Variables - Shows you the current RoboRealm variables that other modules have created.
Note that the variables are NOT reset during each image call and thus can be used to save information
from past images.
Returned Variables - Shows the variables that your pipe program has returned which were added
to the RoboRealm variables.
Messages - Any system error messages. If your pipe program passes back the 'error' variable
the contents are displayed in this text box.
Reload and Run - While RoboRealm attempts to keep the pipe connection open you may need to
restart the pipe program due to failure of some kind.
To start the program
specify the .exe file using the browse button. RoboRealm will start the program
and pass variables and images to it for processing.
The data format used to pass the image and associated variables to both pipe and socket
based programs is based on the a name value pair. The following is and example of the
data stream:
5 width 4 320 6 height 240 5 image 230400 xxxxx ... 0
The pair format is
length of name | name | length of value | value | next length or 0 to end
and continues until a 0 or -1 is encountered. 0 means end of the current image step
while -1 means end of program.
Note that all variable values are sent as text strings with the exception of
width and height which are stored as a four byte number and the actual image which is
composed on unsigned BGR pixel triplets.
Things to remember:
- Be sure to use a unique pipe name! If you create more than one Pipe program use a different pipe
name or combine the two functions into a single pipe program.
- RoboRealm only processes images when needed! Thus if the RoboRealm window is hidden it will NOT
process images and will not call your pipe program. If you are processing a static image
RoboRealm will call your pipe module when refreshing part of the window.
|
