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
orquit
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 param2 … paramn
\n
Where:
type is
result
,status
ormsg
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.