Running the examples

Overview

The easiest way to understand and learn RAMSES is to execute few of the examples and play with the code. We encourage to do that before reading up on the more complex use-cases and features of RAMSES.

There are two types of examples found in the /bin folder after building RAMSES:

• Local examples which consist of one executable
• Remote examples which consist of three (or more) executables

Local examples

Local examples are easier to execute, because they require starting a single executable. However, their code is more complex because it has to do two things at once - provide content (ramses client) and render it to a display (ramses renderer). To start one of these examples, just run:

./ramses-example-local-xxx

This will open a window (or several, depending on the example) and render some simple content in it.

Remote examples (localhost)

Remote examples require starting at least three executables to see something on screen. "Remote" means that the executables communicate over network, but it can also be local network (localhost). That is the default case, if no IP addresses are configured. Let's take a look at a simple distributed example with localhost, and take a look at a more realistic deployment with a netowork in the next section.

1. Start the ramses daemon ./ramses-daemon
2. Start a ramses renderer ./ramses-renderer-<platform> where platform is a platform configuration, e.g. windows-wgl-4-5`
3. Start one of the examples ./ramses-example-<someexample>

Hint: in some IDEs, such as Visual Studio, it is possible to select multiple executables for debugging, so that you don't have to manually start several executables each time you want to try out your application. It is also possible to leave the daemon and renderer open, and only restart the example app when debugging.

Each of the executables will have its own console window and will log possible problems. Such problems could be that a firewall is preventing the executables to communicate over the network, or that your computer doesn't support OpenGL. Read the logs and pay attention to errors and warnings. If everything worked fine, all three executables will announce in the logs that they were able to see each other on the network.

Remote examples (with real network)

Running the examples on a real ditributed setup is not much different than running them locally. One more step is necessary - one needs to configure several IP addresses as command line parameters. This includes both the "self" IP address of each executable's host machine and the "remote" IP address of the ramses daemon.

For example, if one would have three machines in a network with IPs 192.168.1.1, 192.168.1.2, and 192.168.1.3, and would start a daemon, a client, and a renderer on those machines respectively, the configuration would look like this:

./ramses-daemon --myipaddress 192.168.1.1

./ramses-client --myipaddress 192.168.1.2 --daemon-ip 192.168.1.1

./ramses-renderer --myipaddress 192.168.1.3 --daemon-ip 192.168.1.1

Notice that the daemon doesn't have a "daemon-ip" setting - because it already knows its own IP address over "myipaddress". The other executables (renderers and clients) have to provide their own IPs to the daemon, because the daemon forwards those addresses so that direct connections can be built between the clients and renderers, and not all traffic has to go over the daemon. The daemon acts as an initial connection broker which connects participants in the RAMSES ecosystem, announces available scenes, publication requests and so on. Therefore, it is important that there are no network restriction between all RAMSES executables, not only to the daemon, in a network setup.