核心crate

luminance 库收集了编写代码所需的所有图形技术逻辑和渲染抽象。它包含抽象实际实现类型的参数化类型和函数——按照惯例，类型变量 B（表示后端）被使用。

后端类型——即 B —— 不是由 luminance 直接提供的。通常，它们由包含技术名称后缀的库提供，例如 luminance-gl，[luminance-webgl]，luminance-vk 等。这些后端库与 luminance 之间的接口在 luminance::backend 中定义。

一般来说，Something<ConcreteType, u8> 是一个单态类型，它将仅在 ConcreteType 后端上使用的代码中可用。如果你想要编写一个接受一个未指定具体类型的 8 位整数的函数，你将不得不写一些类似下面的代码

use luminance::backend::something::Something as SomethingBackend;
use luminance::something::Something;

fn work<B>(b: &Something<B, u8>) where B: SomethingBackend<u8> {
  todo!();
}

这类代码是为编写 luminance 库的人准备的。对于更常见的使用 luminance-front 库的情况，你将得到如下代码

use luminance_front::something::Something;

fn work(b: &Something<u8>) {
  todo()!;
}

在 luminance-front 中，后端类型是在编译和链接时选择的。这通常是人们想要的，但请记住，luminance-front 不允许同时拥有多个后端类型，这可能也是你想要使用的。

后端实现

后端实现 luminance::backend 特性，并为每个实现提供大多数情况下单一类型。重要的是要理解后端库可以提供多个后端（例如，luminance-gl 可以为每个支持的 OpenGL 版本提供一个后端——所以一个类型）。该后端类型将在整个生态系统中被用于推导后续实现者和关联类型。

如果你想实现一个后端，你不需要向任何 luminance 库推送任何代码。 luminance-* 库是 官方 的，但你也可以编写自己的后端。然而，该接口是高度 unsafe 的，主要基于 unsafe impl 在 unsafe trait 上。有关更多信息，请查阅 luminance::backend 模块的文档。

窗口

luminance 对其执行的上下文一无所知。这意味着它不知道它是否用于 SDL、GLFW、glutin、Qt、网页画布或如任天堂 Switch 这样的嵌入式特定硬件。这实际上是非常强大的，因为它允许 luminance 对其运行的执行平台完全无感知：少一个问题。然而，有一个重要的问题需要注意：单个后端类型可以与多个窗口库/实现一起使用。这允许重复使用后端与多个窗口实现。后端通常将说明创建它的条件（例如，在 OpenGL 中，窗口库必须在创建 OpenGL 上下文时设置一些特定的标志）。

luminance 不提供创建窗口的方式，因为它不依赖于窗口库——这样最终用户就可以使用他们喜欢的任何库。此外，这类库通常实现窗口和事件功能，但这些与我们最初的目标无关。

支持亮度功能的平台crate通常通过重新导出符号（类型、函数等）从窗口crate以及使它与亮度兼容所需的代码来提供本地类型。这意味着提供了一种访问后端类型的方法，该类型实现了luminance::backend接口。然而，平台crate不应取代底层平台系统；你通常仍然需要依赖它。

luminance-derive

如果你正在针对"derive"功能编译，你将自动获得对luminance-derive的访问权限，它提供了一套过程宏。

顶点

Vertex derive过程宏。

该过程宏允许你轻松创建自定义顶点类型，而无需担心实现所需的特性。

如果你想要将类型用作顶点（由Tess消费），则必须实现Vertex特质。你可以自行决定实现它，或者让这个crate为你完成这项工作。

重要：由于顶点格式包含有关将发送到后端的数据结构的信息的特性，且不良实现可能导致未定义的行为，所以Vertex特质是unsafe的，这意味着所有实现者都必须是安全的。

如果你的类型满足以下条件，则可以派生Vertex特质

• 它必须是一个具有命名字段的struct。这只是暂时性的限制，一旦crate足够稳定，就会取消。
• 其字段必须具有实现VertexAttrib的类型。这是强制性的，以便后端了解结构体中使用的类型，以便正确对齐内存、选择正确的类型等。
• 其字段必须具有实现HasSemantics的类型。这个特质只是一个类型族，它将单个常量（即语义）与顶点属性关联起来。
• 每个字段的类型必须不同。

一旦满足所有这些要求，就可以轻松派生Vertex特质。

注意：也可以查看Semantics过程宏，它提供了一种生成语义类型的方法，以便完全为你的选择实现Semantics，同时生成定义你的顶点类型时可以使用的行为类型。

语法如下

use luminance::{Vertex, Semantics};

// visit the Semantics proc-macro documentation for further details
#[derive(Clone, Copy, Debug, PartialEq, Semantics)]
pub enum Semantics {
  #[sem(name = "position", repr = "[f32; 3]", wrapper = "VertexPosition")]
  Position,
  #[sem(name = "color", repr = "[f32; 4]", wrapper = "VertexColor")]
  Color,
}

#[derive(Clone, Copy, Debug, PartialEq, Vertex)]
#[vertex(sem = "Semantics")] // specify the semantics to use for this type
struct MyVertex {
  position: VertexPosition,
  color: VertexColor,
}

注意：由于HasSemantics特质的实现，Semantics枚举必须是公共的。

除了与Semantics相关的代码，这还将

• 创建一个名为MyVertex的类型，一个将包含单个顶点的结构。
• 实现Vertex for MyVertex。

该proc-macro还支持一个可选的#[vertex(instanced = "<bool>")]结构属性。该属性允许您指定字段是否要进行实例化。更多详情，请参阅VertexInstancing。

语义

Semantics derive proc-macro。

UniformInterface

UniformInterface derive proc-macro。

该过程宏非常简单易用。您就像通常声明结构一样声明一个结构

use luminance::{shader::{types::Vec4, Uniform}, UniformInterface};

#[derive(Debug, UniformInterface)]
struct MyIface {
  time: Uniform<f32>,
  resolution: Uniform<Vec4<f32>>,
}

此声明的效果是声明了MyIface结构，并附带了一个有效的UniformInterface实现，该实现将尝试获取相应着色器程序中的"time"和"resolution"统一变量。如果其中任何一个统一变量无法映射（例如，非活动统一变量），则整个结构无法生成，并引发错误（有关详细信息，请参阅UniformInterface::uniform_interface的文档）。

#[derive(Debug, UniformInterface)]
struct MyIface {
  #[uniform(unbound)]
  time: Uniform<f32>, // if this field cannot be mapped, it’ll be ignored
  resolution: Uniform<Vec4<f32>>,
}

#[derive(Debug, UniformInterface)]
struct MyIface {
  time: Uniform<f32>,
  #[uniform(name = "res")]
  resolution: Uniform<Vec4<f32>>, // maps "res" from the shader program
}

#[derive(Debug, UniformInterface)]
struct MyIface {
  time: Uniform<f32>,
  #[uniform(name = "res", unbound)]
  resolution: Uniform<Vec4<f32>>,
}