openFrameworks Tutorial - shiffman/Most-Pixels-Ever-Processing GitHub Wiki

Tutorial on how to create a MostPixelsEver client in openFrameworks

Introduction

This tutorial demonstrates how to use MPEClient using openFrameworks (or oF) version 0.0061. Before you try this tutorial, you probably want to read HowThisWorks, as well as ProcessingTutorial. To develop a project using MPE, it's recommended that you start by running the server and your client application locally.

Also, you can get the OF sample apps and OF addon by checking out the source or visiting the downloads page (download links to come!)

1. Make sure you have the addon

The addon folder "ofxMostPixelsEver" must be in the OF addons directory for any of this to work!

2. Make sure you are running the server

Before you can test the client, you'll need to run the server (which is written in Java). You have two options for running the server app. Option number one is to checkout the source via subversion and compile and run mpe.server.WallServer.

The second option is to download and extract the MPE server application (download links to come!). The file contains the server application in a jar.

Run the server via the command line.

java -jar mpeServer.jar -verbose -framerate30 -screens2

The server can be configured by changing the command line arguments.

3. Add client and frameEvent() function to your .h file

You'll need to have an instance of an mpeClientTCP as well as a frameEvent() function in your .h file.

    public:
        void frameEvent();
    
    private:
        mpeClientTCP  client; 

4. MPEClient calls in setup()

In oF's setup function, we tell the client to load an xml file containing its network settings (see below for an example file). Most importantly, this file sets the client ID and the IP address and port of the MPE server.

Note: you must change the client ID for each client that connects to the server. The first client should have an ID of 0.

The call to client.start() tells the client to open up a connection with the server and send a handshake. Once all of the clients have connected the server will start running and tell the clients to draw their first frame.

void testApp::setup(){

     // setup upd client
     client.setup("networkSettings.xml");
	
     // start client
     client.start();
}

The .xml file allows you to set the size of your client's window ("local_dimensions"), the size of the entire project's window ("master_dimensions"), and the vertical and horizontal location of the client within the entire project ("local_location").

If "debug" is set to true, the client will print out all of its debug messages -- so you can see if it has connected to the server, what messages were sent and received, etc.

If "go_fullscreen" is set to true, your client will jump into fullscreen mode as soon as it starts up.

If "offset_window" is set to true, the position of the client window will be set to the x and y values in the "local_location" tag. This is useful for testing out multiple smaller windows on a single computer.

<settings>
	<client_id>0</client_id>
	<server>
		<ip>127.0.0.1</ip>
		<port>9002</port>
	</server>
	<local_dimensions>
		<width>400</width>
		<height>400</height>
	</local_dimensions>
	<local_location>
		<x>0</x>
		<y>0</y>
	</local_location>
	<master_dimensions>
		<width>800</width>
		<height>400</height>
	</master_dimensions>
	<go_fullscreen>true</go_fullscreen>
	<offset_window>false</offset_window>
	<debug>0</debug>
</settings>

Also, The MPEClient is structured so that it only draws a new frame when a new frame message has been received from the server. Otherwise it leaves the canvas alone, untouched. For this reason, automatic clearing of the background should be disabled. This is done automatically in mpeClient.setup() ... so don't change it elsewhere in your application (you'll get unwanted flickering if you don't).

ofSetBackgroundAuto(false);

5. MPEClient calls in frameEvent()

oF is structured so that calculations are done in update() and drawing is done in draw(). However, the add-on allows you simply ignore update() and draw(). Instead, you write a frameEvent() function which is executed only when the server says it's time to do so.

You can also check to see if the server is including a message with the frameEvent(). It's up to you to design your own messaging protocol to control events in your application.

//--------------------------------------------------------------
void testApp::update() {	
}

//--------------------------------------------------------------
void testApp::draw() {
}

//--------------------------------------------------------------
void testApp::frameEvent() {

    // do your update and draw here! 

    // read any incoming messages
    if (client.messageAvailable()) {
        vector<string> msg = client.getDataMessage();
    }
}

6. Broadcasting messages to other clients

MPEClient supports broadcasting string messages to other MPE clients connected on the same server. This can be done by calling client.broadcast("this is my message").

Often you'll need to take a few integers and place them into a string. This can be done with using the c function sprintf.

// create a new char array
char newString[40];

// create a string using two integers, separated by a comma
sprintf(newString, "%i,%i", x, y);

// broadcast that the new string.
client.broadcast(newString);
⚠️ **GitHub.com Fallback** ⚠️