Skip to main content

Getting started

CMake​

In order to use SGCT, it has to be included in the CMakeLists.txt of your project. This can be done either by including SGCT as a submodule in your project or by using the vcpkg port:

find_package(sgct CONFIG REQUIRED)
target_link_libraries(OpenSpace PRIVATE sgct::sgct)

In that case, SGCT will automatically be included in your project file when generating it.

Commandline argument​

You can find the available commandline arguments by either looking at the commandline.cpp file's helpMessage() function, or by executing your application with the commandline argument --help, which will print that message and immediately terminate the application. The most important setting that might be useful for the user is the --config parameter which accepts a single argument that is the path to an JSON configuration file that is loaded and applied at application startup. The file format of the configuration files are described in greater detail in the Reference section. If no configuration file is provided, SGCT will create a "cluster" consisting of a single node with a single 1280x720 window.

When running multiple instances of the application on the same machine (if your configuration file is configured to support that), you will also need the --local n and --client parameters. As the automatic IP detection cannot determine which of the nodes to use, the --local n parameter has to be used to distinguish the nodes, starting with the number 0, using --local 0 for the node identified by the IP address 127.0.0.1, --local 1 for the address 127.0.0.2 and so forth. Each node that is not the server also needs to be started with the -client parameter or it will think it is the server and not try to connect to the actual server node. Commandline arguments contains more detailed information about the available commandline arguments that can be passed to SGCT applications.

First application​

Creating applications using SGCT is very simple and requires only a bit of coding. Here is an example that opens a window and sets its color to white. Please note that SGCT only supports modern OpenGL versions (3.3 and newer), which means that the legacy fixed-pipeline functions will not work.

See also the Calibrator application that is included in the repository. It is build by enabling the SGCT_BUILD_CALIBRATOR CMake setting.

This is a simple application that will render the viewport in white:

#include "sgct/sgct.h"

void drawFun(const RenderData& data) {
  glClearColor(1.f, 1.f, 1.f, 1.f);
  glClear();
}

int main(int argc, char** argv) {
  std::vector<std::string> arg(argv + 1, argv + argc);
  Configuration config = parseArguments(arg);
  config::Cluster cluster = loadCluster(config.configFilename);

  Engine::Callbacks callbacks;
  callbacks.draw = drawFun;

  try {
    Engine::create(cluster, callbacks, config);
  }
  catch (const std::runtime_error& e) {
    Log::Error("%s", e.what());
    Engine::destroy();
    return EXIT_FAILURE;
  }

  Engine::instance().render();
  Engine::destroy();
  return EXIT_SUCCESS;
}

The control flow in SGCT is explained in the How it works section of this documentation.

Engine::instance().render() will cause a frameloop to start that will only end when the last window has been closed or the Engine::terminate function was called. During this farameloop the callbacks passed into the Engine::create functions are called at the appropriate times as shown in the diagram of the How it works page.