skulpin

Skia + Vulkan = Skulpin

此crate通过结合vulkan和skia，为硬件加速的2D绘图提供了一个简单选项。

请注意在使用前查看此crate的状态。

此crate主要依赖于

• rafx - 一个易于访问vulkan后端的渲染框架
• skia-safe - Skia的Rust绑定

注意：有关如何获取skia二进制文件的更多信息，请参阅skia-bindings。在许多情况下，此crate将下载由其项目的CI创建的二进制文件。

此crate与raw-window-handle集成，这允许它与sdl2、winit以及任何支持raw-window-handle的窗口框架一起使用。

运行示例

首先，请根据操作系统确保以下要求得到满足。然后，示例可以正常运行。

有关如何获取键盘/鼠标输入的简单方法，可以查看交互式示例。

# winit 0.24
cargo run --example interactive_winit_app --features winit-app,winit-25

# sdl2
cargo run --example interactive_sdl2

物理演示也很有趣。

cargo run --example physics --features winit-app,winit-25

以下是物理和交互式示例的视频。

状态

我将不再使用这个crate进行任何操作，因此只会以极小的规模维护这个crate。我将审查简单的pull请求，并在已打开的问题上提供建议。然而，我可能在任何时候完全停止使用这个仓库，尤其是如果crate停止工作且需要超出常规的更改才能修复。遗憾的是，我在开源项目上的时间有限，所以我希望将重点放在我个人认为最有兴趣的crate上。我愿意将crate的所有权转让给那些提交了几个PR并证明自己值得信赖的人，如果有人创建了分支，我也会很高兴地提供链接。

使用方法

目前有两种方法可以使用这个库与winit一起。

• 应用 - 实现AppHandler特质并启动应用。这很简单，但不够灵活。目前仅在winit中使用时支持。
• 仅渲染器 - 您自行管理窗口和事件循环。然后添加渲染器来绘制。窗口应包装在skulpin::Window的实现中。提供了sdl2和winit的实现。

如果您更愿意使用sdl2，您需要直接使用渲染器。请参阅仅sdl2渲染器

不要忘记安装适用于您平台的以下先决条件！（见“需求”）

功能标志

Skia相关功能

• skia-complete - 包括以下所有Skia功能。** 默认开启 **
• skia-shaper - 启用Harfbuzz和ICU进行文本形状
• skia-svg - 此功能启用SVG渲染后端
• skia-textlayout - 使Skia模块skparagraph可用，其中包含用于布局段落的类型
• 关于这些标志的更多信息可以在skia-safe的readme文件中找到

skia-bindings的预构建二进制文件仅适用于某些功能组合。截至本文写作时，它适用于没有任何功能、每个功能单独或所有功能均启用的情况。需要vulkan功能，并且隐式使用，因此启用任何功能单独都将显著增加构建时间。建议使用所有功能（默认行为），或者禁用所有功能。（使用default-features = false）

Skulpin功能

• winit-app - 包含winit应用包装器。它比直接使用渲染器灵活性低，但易于使用。

如果使用winit-app，您必须指定winit版本功能标志（见下文）

Winit版本功能标志

• winit-21
• winit-22
• winit-23
• winit-24
• winit-25
• winit-latest

（这些功能名称与imgui-rs crate相匹配。）

功能标志使用示例

# Pull in all skia features and support for all backends (sdl2 and winit)
skulpin = "0"

# Pull in all skia features but not the winit app wrapper
skulpin = { version = "0", default-features = false, features = ["skia-complete"] }

# Pull in all skia features and include the winit app wrapper
skulpin = { version = "0", default-features = false, features = ["skia-complete", "winit-app"] }

skia-safe的上游版本控制

Skulpin可以使用许多版本的skia-safe进行构建和使用。为了方便使用这个库的用户，所要求的版本已经被放宽。这允许新项目使用这些库的较新版本，同时不强迫旧项目进行更新。

您可以通过使用cargo update来强制使用特定的skia safe版本

cargo update -p skia-safe --precise 0.32

文档

在docs.rs上构建文档失败，因为skia_safe软件包需要网络连接来构建。（它将抓取skia源代码或抓取预构建的二进制文件。）因此，查看文档的最佳方式是自己构建它们。

cargodoc -pskulpin --open

需求

最低要求的rust版本：1.43.0

Windows

• 如果你使用的是GNU工具链（MSVC是默认的），你可能会在构建curl时遇到问题。（curl是skia-safe绑定的依赖项，用于下载预构建的skia二进制文件。）这里有一些解决方案。再次强调，这只会影响你使用非默认GNU工具链的情况。
• 如果你使用SDL2，请参阅SDL2绑定的要求。最简单的方法是使用“捆绑”和“静态”功能。要做到这一点，将以下内容添加到你的Cargo.toml中：sdl2 = { version = ">=0.33", features = ["bundled", "static-link"] } 这些功能默认对示例启用。
• 启用vulkan验证需要LunarG验证层和可在你的PATH中看到的Vulkan库。一个简单的开始方法是使用LunarG Vulkan SDK

MacOS

• 如果你使用SDL2，请参阅SDL2绑定的要求。最简单的方法是使用“捆绑”和“静态”功能。要做到这一点，将以下内容添加到你的Cargo.toml中：sdl2 = { version = ">=0.33", features = ["bundled", "static-link"] } 这些功能默认对示例启用。
• 启用vulkan验证需要LunarG验证层和可在你的PATH中看到的Vulkan库。一个简单的开始方法是使用LunarG Vulkan SDK

Linux

• 如果你使用SDL2，请参阅SDL2绑定的要求。最简单的方法是使用“捆绑”和“静态”功能。要做到这一点，将以下内容添加到你的Cargo.toml中：sdl2 = { version = ">=0.33", features = ["bundled", "static-link"] } 这些功能默认对示例启用。
• 在Linux上，你还需要链接到bz2、GL、fontconfig和freetype。
  • 在Ubuntu上，你可以使用libbz2-dev、libfreetype6-dev、libfontconfig1-dev和libgl-dev。（以及libvulkan-dev以获取Vulkan SDK）
• 启用vulkan验证需要LunarG验证层和可在你的PATH中看到的Vulkan库。一个简单的开始方法是使用LunarG Vulkan SDK

其他平台

可能可以为移动平台构建此软件，但我还没有研究这个问题。

关于高DPI显示器支持的说明

对于常见情况，你可以使用“逻辑”坐标在skia画布上绘图，而不用担心dpi/缩放问题。

内部，skia表面将与swapchain大小匹配，但这个大小不一定是窗口的逻辑大小或物理大小。为了产生一致大小的结果，渲染器将在将其传递给你的绘图实现之前，对skia画布应用一个缩放因子。

重要的配置选择

当配置应用程序的运行方式时，你应该考虑以下几个主要选择

• 坐标系 - 此库可以配置为使用几种不同的坐标系。
  • Logical - 使用逻辑坐标，这是经过缩放因子的像素，以适应高分辨率显示器
  • Physical - 使用原始像素作为坐标
  • VisibleRange - 尝试将给定范围适应到窗口中
  • FixedWidth - 使用给定的X范围和宽高比来计算Y范围
  • None - 不修改画布矩阵
• 显示模式 - 你可能希望使用Fifo（默认）或Mailbox
  • Fifo (VK_PRESENT_MODE_FIFO_KHR)是默认行为，并且始终存在于完全符合规范设备上。这将实现VSync，不应出现屏幕撕裂，并且通常会以显示刷新率运行。
  • Mailbox (VK_PRESENT_MODE_MAILBOX_KHR) 将尽可能快地渲染。帧将被排队，并绘制最新完成的帧。其他帧将被丢弃。这种渲染方法将产生最低的延迟，但并非总是可用，并且可能会对笔记本电脑和移动设备造成不必要的电池消耗。
  • 请参阅 prefer_fifo_present_mode/prefer_mailbox_present_mode 以选择两种推荐选项之一，或使用 present_mode_priority 以进行完全控制。
  • 有关详细信息，请参阅 PresentMode 的文档和 Vulkan 规范。
• 设备类型 - 最常见的设备类型将是专用或集成。默认情况下，如果可用，则选择专用设备。
  • Discrete (VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU) - 如果可用，这可能是性能最佳的设备
  • Integrated (VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU) - 这通常比离散 GPU 更节能。
  • 我认为最可能同时拥有这两种情况的情况是具有离散 GPU 的笔记本电脑。我预计优先考虑集成 GPU 将有利于电池寿命，但会牺牲一些性能。然而，我没有合适的设备进行测试。
  • 请参阅 prefer_integrated_gpu/prefer_discrete_gpu 以选择两种推荐选项之一，或使用 physical_device_type_priority 以进行完全控制。
  • 有关详细信息，请参阅 PhysicalDeviceType 的文档和 Vulkan 规范。
• Vulkan 调试层 - 默认情况下未启用调试日志。
  • use_vulkan_debug_layer 用于打开/关闭所有日志。
  • validation_layer_debug_report_flags 允许选择特定的日志级别。
  • 如果未安装 Vulkan SDK，则如果启用了任何 Vulkan 调试，应用程序将无法启动。

许可证

根据您的选择，受以下任一许可证的许可：

• Apache License，版本 2.0，(LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

任选其一。

字体目录包含受各自许可证许可的几个字体。

• Feather，MIT
• Material Design Icons，SIL OFL 1.1
• FontAwesome 4.7.0，可在 SIL OFL 1.1 下使用。
• mplus-1p-regular.ttf，可在其自己的许可证下使用。

sdl2 使用 zlib 许可证。

贡献

除非您明确声明，否则您有意提交的任何贡献，根据 Apache-2.0 许可证定义的工作，应按上述方式双重许可，没有任何额外的条款或条件。

请参阅 LICENSE-APACHE 和 LICENSE-MIT。