TCP is the basis for all the Internet protocols, for example, HTTP. This is an error-checking protocol, which guarantees obtaining valid data and notifying errors. This makes it appropriate for sending big volumes of data from computers, not only in your local network, but also around the world.
For working with TCP in openFrameworks, you need to use the ofxNetwork addon.
Tip
We suggest that the first time, you should try TCP with openFrameworks examples: networkTcpServerExample and networkTcpClientExample, located in openFrameworks's folder examples/addons. Run both of them on one PC, and then activate the window of networkTcpClientExample and press some keys. You will see that the keys will be sent to networkTcpServerExample and printed on its screen.
For linking the ofxNetwork addon, there are three options similar to the ofxOsc addon. Check the beginning of the Using OSC protocol section for details.
The scheme of working with TCP is based on the client-server technology. In one application, you need to create and start a server using the ofxTCPServer server object. In another application, you need to create a client using the ofxTCPClient client object, and establish a connection with the server. After this, you can send string messages and raw data bytes from client to server and from server to client. There can be several clients connecting to one server.
In principle, using the ofxNetwork addon, you can implement your own HTTP or FTP server and do anything such as downloading files from Internet. Though, for serious projects, we strongly recommend not to do this by yourself, because TCP is a very low-level protocol for this. Instead, use some ready-made addons or special libraries for this. Also, openFrameworks core contains several classes, which could be useful for your needs:
- If you need to download images from the Internet, you can use the
image.loadImage( url )function, whereurlis a string specifying URL of an image. Note that it pauses the application execution until the image is downloaded. So, to download the image without pausing (called asynchronously), see the openFrameworks example:examples/graphics/imageLoaderWebExample. - To download arbitrary files, you can use the
ofURLFileLoaderclass. We will not consider it in this book. - To work with HTTP requests and responses, see the functions in the
libs/openFrameworks/utils/ofURLFileLoader.hfile. It's also out side the scope of this book.
We will not consider ofxTCPServer and ofxTCPClient classes in the detail, but we will include an extremely useful example of using it for streaming images between applications by working on the same or different computers.
Let's consider an example that demonstrates sending images between applications using TCP. It consists of two projects—the sender and the receiver.
These two example projects are presented by a number of source .h and .cpp files. Read the beginning of the testApp.h files for detailed instructions on how to create openFrameworks projects from these sources.
Compile and run both the projects. The sender will grab camera images and send them to the receiver. Both projects draw current images on the screen, and also show the current frame's ID. Additionally, the receiver shows the frame rate of the images received (it depends not only on networking, but also on the real frame rate of the camera):
The sender and the receiver use the ofxTCPServer and ofxTCPClient classes for sending and receiving images as uncompressed arrays. See the details of its implementation in the pbNetwork.h and pbNetwork.cpp files, which are included in each of the example's projects.
You can use this example as a sketch for your own projects when you need to send big amounts of information between applications.
Tip
We often use such technology in our interactive installations and performances. We mount two PCs, a Tracker , which works with depth cameras, and a Render , which renders installation visuals. The Tracker gets data from several depth cameras, sticks them into a bigger depth image, and sends it to the Render via TCP. Such separation of tracking and rendering increases the overall system stability and off-loads the Render from analyzing depth data, so we can do more processing and obtain richer visualization.
Normally you can send 320 × 240 grayscale image at 30 fps using wired connections at 100 MBps. For sending bigger images, use faster network equipments, such as 1 GBps and higher. Note that we never use wireless connections during serious concerts and performances because of possible instability induced by viewers' mobile devices.
Tip
If you need to send images from one application to another on a Mac computer, you do not need to use networking. The best option in this case is to use an open library called Syphon, by downloading and installing the ofxSyphon addon. This addon allows the exchange of images between openFrameworks and other applications at OpenGL level, so it works faster than networking.