# `delight-sys`

<!-- cargo-rdme start -->

Auto-generated Rust bindings for *Illumination Research*'s 3Delight
renderer's utility API.

You should not need to use this crate directly except for two
reasons. You are likely either:

* a masochist who wants to use the C-API directly from Rust.

* Not happy with my high level Rust binding (see below) – consider
  opening an issue [here](https://github.com/virtualritz/delight-helpers/issues)
  instead.

## High Level Bindings

There are high level Rust bindings for this API in the
[`delight` crate](https://crates.io/crates/delight/).

## Compile- vs. Runtime

The crate builds as-is, with default features.

However, at runtime this crate requires a library/renderer that
implements the resp. C-API to link against. Currently the only
renderer that does is [*3Delight*](https://www.3delight.com/).

## Cargo Features

* `download_lib3delight` -- Fetches the dynamic library version of
  3Delight for Linux, macOS or Windows. This can be used as a fallback, to
  build against, if you do not have the renderer installed on your system.
  But it is an old version of 3Delight and foremost a CI feature.

  It is instead suggested that you download a 3Delight package for your
  platform & install it. This will set the `DELIGHT` environment variable
  that the build script is looking for to find a locally installed library
  to link against.

  This will also install *3Delight Display* which you can render to,
  progressively -- useful for debugging.

  The free version renders with up to 12 cores.

* `link_lib3delight` -- Statucally link against `lib3dlight`` during build.

  This requires a 3Delight installation unless `download_lib3delight` is
  set. See also next section.

## Linking Style

The 3Delight dynamic library (`lib3delight`) can either be linked to,
during build, or loaded at runtime.

* By default `lib3deligh` is loaded at runtime. This has several
  advantages:

  1. If you ship your application or library you can ship it without the
     library. It can still run and will print an informative error if the
     library cannot be loaded.

  2. A user can install an updated version of the renderer and stuff will
     ‘just work’.

* Dynamically link against `lib3delight`.

  * The feature is called `link_lib3delight`. You should disable default
    features (they are not needed/used) in this case:

    ```toml
    [dependencies]
    delight-sys = {
        version = "0.8",
        default-features = false,
        features = ["link_lib3delight"]
    }
    ```

  * `lib3delight` becomes a dependency. If it cannot be found by the
    system's dynamic linker at runtime, your lib/app will not load/start.

<!-- cargo-rdme end -->