delight-sys

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 instead.

High Level Bindings

There are high level Rust bindings for this API in the delight crate.

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.

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:

    [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.