3 releases

0.1.2 Nov 16, 2023
0.1.1 Nov 15, 2023
0.1.0 Nov 15, 2023

#373 in Rendering


Used in 2 crates (via delight)

Apache-2.0…

15KB
165 lines

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.

Dependencies

~0.1–2.2MB
~40K SLoC