Utilities module

Printing utilities, command-line parsing, and other conveniences.

Classes

class DartsException
An exception storing a human-readable error description passed in using fmt:format-style arguments.
template<typename T>
class Range
Python-style range: iterates from min to max in range-based for loops.
template<int N, typename T>
class RangeND
Python-style range, but for nested, multi-dimensional loops (up to 4 dimensions).
class Progress
A thread-safe helper object to display and update a progress bar in the terminal.

Functions

template<class To, class From>
auto bit_cast(const From& src) -> std::enable_if_t<sizeof(To)==sizeof(From) && std::is_trivially_copyable_v<From> && std::is_trivially_copyable_v<To>, To> noexcept
std::bit_cast is only available starting with C++20, so we provide a version
template<typename T>
auto range(T end) -> Range<T>
Construct a Python-style range from a single parameter end.
template<typename T>
auto range(T start, T end, T step = T(1)) -> Range<T>
Construct a Python-style range from start, up to but excluding end, in increments of step.
auto get_file_resolver() -> filesystem::resolver&
Return the global file resolver instance.

Formatted printing and logging

Darts provides a convenient way to report information to the user.

This is all based on the spdlog and fmt libraries. You can find extensive documentation for both of these linked from the Code organization section, but in a nutshell:

Formatted printing to the console or to strings:

Darts includes the fmt library to provide a modern replacement for cout or printf.

The two most useful functions are:

fmt::print()
fmt::format()

See the fmt library website for complete documentation.

Logging

The spdlog library provides a number of functions:

  • spdlog::debug
  • spdlog::info
  • spdlog::warn
  • spdlog::err
  • spdlog::critical

These operate just like fmt::print, but colorize the output based on the type of message. Darts can also globally disable messages below a certain threshold to control the verbosity of the output (this is done in darts_init, and controlled by a command-line argument in src/darts.cpp).

Darts also allows you to print and update a nice progress bar (see Progress) for long operations.

void darts_init(int verbosity = spdlog::level::info)
Initialize darts before parsing or rendering a scene.
auto time_string(double time, int precision = 2) -> string
Convert a time value in milliseconds into a human-readable string.
auto indent(const std::string& string, int amount = 2) -> string
Indent a string by the specified number of spaces.
#define put_your_code_here(txt)
Warning signaling unimplemented features.

Function documentation

#include <darts/common.h>
template<class To, class From>
std::enable_if_t<sizeof(To)==sizeof(From) && std::is_trivially_copyable_v<From> && std::is_trivially_copyable_v<To>, To> bit_cast(const From& src) noexcept

std::bit_cast is only available starting with C++20, so we provide a version

#include <darts/common.h>
template<typename T>
Range<T> range(T end)

Construct a Python-style range from a single parameter end.

#include <darts/common.h>
template<typename T>
Range<T> range(T start, T end, T step = T(1))

Construct a Python-style range from start, up to but excluding end, in increments of step.

filesystem::resolver& get_file_resolver()
#include <darts/common.h>

Return the global file resolver instance.

This class is used to locate resource files (e.g. mesh or texture files) referenced by a scene being loaded.

void darts_init(int verbosity = spdlog::level::info)
#include <darts/common.h>

Initialize darts before parsing or rendering a scene.

Parameters
verbosity in specify the verbosity of messages printed to the console

string time_string(double time, int precision = 2)
#include <darts/common.h>

Convert a time value in milliseconds into a human-readable string.

string indent(const std::string& string, int amount = 2)
#include <darts/common.h>

Indent a string by the specified number of spaces.

Parameters
string in The string to indent
amount in The amount of spaces to indent
Returns The indented string

Useful for creating nested indentation within error strings.

Define documentation

#define put_your_code_here(txt)
#include <darts/common.h>

Warning signaling unimplemented features.

Prints out a warning with the line number, but otherwise lets execution continue.