API mode

Ocean may be run in API mode. This is a special command line mode, designed to be run by another program, as the console output is not human-readable. In this mode, it is possible to start simulations and get intermediate results from another application.

The log output is not shown in the console window, but it is written to the log file, and sent to the piloting program.

Launching Ocean in API mode

The command line syntax is the following:

> ocean.exe --api [options]

The options are listed in Command line syntax

In API mode, Ocean is controlled by the process standard input (stdin) and sends back information via the standard output (stdout)

Standard input commands

General syntax

Each command has the following text format, terminated by the end-of-line character.

command data_size followed by the end of line character \n

Where:

  • command is load, bufferupdate, stop, pause, resume or quit

  • data_size is an integer

  • command and data_size are separated by a space character

If data_size is greater than 0, the command end-of-line character is immediately followed by the corresponding number of bytes.

Then, the next command can begin.

The end-of-line must not contain the carriage return \r but only \n. This means that under Windows, the stream must be open in binary mode. Otherwise, the system will add \r automatically.

Load command

This command loads a scene and starts the simulation immediately. The scene is sent as Ocean XML or Ocean Binary formats.

For loading a scene file, the scene file should just contain a single <import> tag. It is also possible to send the whole scene directly, without using a file.

C++ example:

std::string scene = "<oceanroot version=\"4.0\"><import path=\"myscene.ocxml\"/></oceanroot>";
fprintf(ocean_process, "load %u\n%s", scene.size(), scene.c_str());

Buffer update command

This command asks Ocean to send a result update. It has no data, so data_size should be 0.

C++ example:

fprintf(ocean_process, "bufferupdate 0\n");

Stop command

This command asks Ocean to stop the simulation. The final result will be sent, as if bufferupdate was used. When the renderer is fully stopped, the process exits. It has no data, so data_size should be 0.

C++ example:

fprintf(ocean_process, "stop 0\n");

Pause command

This command pauses the simulation. It has no data, so data_size should be 0.

C++ example:

fprintf(ocean_process, "pause 0\n");

Resume command

This command resumes the simulation after pause was used. It has no data, so data_size should be 0.

C++ example:

fprintf(ocean_process, "resume 0\n");

Kill command

This command stops Ocean immediately, the process will exit and may crash if a render is in progress. To finish a simulation and let Ocean exit cleanly, use the stop command instead.

It has no data, so data_size should be 0.

C++ example:

fprintf(ocean_process, "kill 0\n");

Standard output format

General syntax

Each packet sent by Ocean starts by the identifier OcAp followed by the end of line character \n

Then, the packet has the following text syntax:

type data_size param1 param2paramn \n

Where:

  • type is result, status or msg

  • data_size is an integer

  • type, data_size and params are separated by a space character

If data_size is greater than 0, the last end-of-line character is immediately followed by the corresponding number of bytes.

Then, the next packet can begin.

Result packet

The status packet result sends intermediate simulation results, such as images

It has no parameters. The result data is sent as data_size bytes

The data format corresponds to the Output file formats supported by Ocean and is set by the instrument Output. It is up to the piloting application to check for the proper data format, such as PNG, CSV, OpenDocument SpreadSheet, etc…

Status packet

The status packet status sends simulation statistics such as speed (samples per second, …)

It has seven parameters as floating point values:

  • The simulation time in seconds

  • The samples per pixel (spp) value

  • The average samples per second (sps) value

  • The current samples per second (sps) value

  • The wrong sample rate

  • The halt time condition in seconds

  • The halt spp condition

The status message has no data, so data_size should be 0.

Message(msg) packet

The msg packet transports a log message from the API slave. It has two parameters param1 and param2

param1 is the message type as an integer:

  • 2 for a verbose message

  • 4 for an information message

  • 8 for a warning message

  • 16 for an error message

param2 is a string corresponding to the original message sender. The message sender can be a network node, and not necessarily the API slave node itself.

The message data is sent as the data bytes.

Example projects

C++/Qt

You may download below a simple C++ Qt project demonstrating the use of the API mode. It contains a useful class for handling API mode input and output easily

ocean-api-demo.zip