Utilities module

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.

class Progress

A thread-safe helper object to display and update a progress bar in the terminal.

Functions

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.

Gathering and reporting runtime statistics

Darts makes it very easy to gather runtime statistics about what happens during the executation of the program.

This functionality is largely based off of that in PBRT and adapted to our codebase.

Using the below macros, you can easily create statistics that you'd like to track during execution, and have summaries printed out after rendering. Available statitic types include:

• Integer counter (STAT_COUNTER), optionally formatted as an amount of memory (STAT_MEMORY_COUNTER)
• A fractional value which can be reported either as a ratio (STAT_RATIO) or as a percentage (STAT_PERCENT)
• A distribution of floating point (STAT_FLOAT_DISTRIBUTION) or integer (STAT_INT_DISTRIBUTION) values

These macros take a string that will be used as a title in the statistics report returned by stats_report(), and the names(s) for the global variables to create for tracking this statistic.

For instance, to keep track of the number of camera rays traced during rendering we call the following macro at the top of camera.cpp to create a counter:

STAT_COUNTER("Integrator/Camera rays traced", num_camera_rays);

This creates a global variable named num_camera_rays. During rendering we can simply increment it:

++num_camera_rays

whenever we trace a new camera ray.

At the end of rendering, this will be reported as follows (assuming we print the report generated by stats_report):

——————————————————————————————————————————————————————————————————————————
 Statistics:
——————————————————————————————————————————————————————————————————————————
  Integrator
    Camera rays traced                                            3002370
——————————————————————————————————————————————————————————————————————————

auto stats_report() -> std::string

Return a string containing a report about all globally registered statistics.

void clear_stats()

Clear all statistics.

void accumulate_thread_stats()

Accumulate the statistics gathered in separate threads together.

#define STAT_COUNTER(title, var)

Create a thread-safe integer statistic counting some quantity.

#define STAT_MEMORY_COUNTER(title, var)

Create a thread-safe integer statistic counting memory usage.

#define STAT_INT_DISTRIBUTION(title, var)

Create a thread-safe statistic keeping track of a distribution of integer values.

#define STAT_FLOAT_DISTRIBUTION(title, var)

Create a thread-safe statistic keeping track of a distribution of floating-point values.

#define STAT_PERCENT(title, num_var, denom_var)

Create a thread-safe statistic keeping track of a floating point value expressed as a percentage.

#define STAT_RATIO(title, num_var, denom_var)

Create a thread-safe statistic keeping track of a floating point value expressed as a ratio.

Function documentation

accumulate_thread_stats();                // main thread
for_each_thread(accumulate_thread_stats); // worker threads
spdlog::info(stats_report());
clear_stats();

Define documentation