wgpu-info 使用指南枚举 GPU 适配器与多适配器测试利器【免费下载链接】wgpuA cross-platform, safe, pure-Rust graphics API.项目地址: https://gitcode.com/GitHub_Trending/wg/wgpu本指南围绕 wgpu 仓库内置的命令行工具wgpu-info展开讲解它的两大核心能力无参数枚举系统上所有 wgpu 可见的 GPU 适配器及其详细能力信息以及带参数时把任意命令批量跑遍适配器 × 后端的每一种组合。读完本文你将掌握 wgpu-info 的编译、运行、输出控制人类可读 / JSON与多适配器测试协作流程并了解它如何通过WGPU_ADAPTER_NAME/WGPU_BACKEND两个环境变量驱动整个 wgpu 生态的测试体系。wgpu-info 位于仓库的 wgpu-info 目录Cargo 包描述为 A tool to print and process information about available wgpu adapters见 wgpu-info/Cargo.toml。它本身是一个独立可执行二进制通过 wgpu-info/src/main.rs 进入实际逻辑集中在 wgpu-info/src/cli.rs参数解析与主流程、wgpu-info/src/report.rs报告生成与 JSON 序列化、wgpu-info/src/human.rs人类可读输出以及 wgpu-info/src/texture.rs纹理格式相关工具函数中。一、工具定位一个工具两种职责wgpu-info 是 wgpu 生态中一个小而关键的命令行实用程序README 原文This is a command line utility that does two different functions.它的两种职责是枚举适配器Listing Adapters不带任何参数调用时列出 wgpu 能看到的所有适配器及其全部可用信息多适配器批量测试Running Tests on many Adapters带任意参数调用时把参数解释为一条要执行的命令并针对系统上适配器 × 后端的每一种组合分别运行该命令。第二种模式是整个 wgpu 仓库在真实 GPU 上做跨适配器测试的主要手段README 明确写道This is used as the primary means of testing across many adapters.二、模式一列出所有适配器2.1 基本用法在仓库根目录当前工作目录下直接运行cargo run --bin wgpu-info不带任何参数时wgpu-info 会创建 wgpu 实例、枚举系统上所有后端Vulkan、Metal、DX12、GLES、WebGPU 等下的全部适配器并打印出关于它们的全部已知信息。从 wgpu-info/src/report.rs 的实现可以看到其核心流程通过wgpu::Instance::new创建实例默认显式使用Dx12Compiler::StaticDxc、开启wgpu::InstanceFlags::debugging()调试标志并调用desc.with_env()允许通过WGPU_BACKEND等环境变量覆盖实例配置调用instance.enumerate_adapters(wgpu::Backends::all())枚举全部后端的适配器对每个适配器采集四类信息adapter.get_info()基本信息、adapter.features()特性、adapter.limits()上限、adapter.get_downlevel_capabilities()降级能力并逐一为每种TextureFormat查询adapter.get_texture_format_features(format)纹理格式能力。2.2 平台特性开关README 特别指出两个平台相关的 feature 开关OpenGL非 Linux 平台需要启用anglefeature即通过 ANGLE 在 Windows / macOS 上提供 OpenGL ES 后端Vulkan on macOS需要启用vulkan-portabilityfeature通过 Vulkan Portability 在 macOS 上提供 Vulkan 后端。对应地带 feature 的运行方式是# 非 Linux 平台上的 OpenGL经 ANGLE cargo run --bin wgpu-info --features angle # macOS 上的 Vulkan经 Vulkan Portability cargo run --bin wgpu-info --features vulkan-portability2.3 输出内容与信息密度控制wgpu-info 提供了四级信息密度对应三个命令行标志见 wgpu-info/src/cli.rs 的帮助文本与 wgpu-info/src/human.rs 的PrintingVerbosity枚举标志对应枚举输出内容-qNameOnly只打印每个适配器的名称与后端类型默认无标志Information打印适配器基本信息-vInformationFeaturesLimits在默认基础上额外打印全部 features、limits 与 downlevel capabilities-vvInformationFeaturesLimitsTexture在-v基础上额外打印全部纹理格式能力与标志README 强调These settings have no effect on the JSON output. The highest verbosity provided will be used if multiple are passed.——即这些标志对 JSON 输出没有影响JSON 始终包含完整数据并且同时传入多个标志时取最高详细级别。对应源码中 wgpu-info/src/cli.rs 按-vv-v-q的优先级解析并对多余标志打印警告Warning: More than one verbosity flag was passed. Using the most verbose option.。默认级别Information下打印的适配器信息对应 wgpu-info/src/human.rs 的字段包括Backend后端类型Vulkan / Metal / DX12 / GLES / WebGPU 等Name适配器名称Vendor ID/Device ID以十六进制#X格式输出的厂商与设备 IDDevice PCI Bus IDPCI 总线位置为空时显示emptyType设备类型DiscreteGpu / IntegratedGpu / VirtualGpu / Cpu / OtherDriver/Driver Info驱动名称与驱动信息Subgroup Min/Max Size子组subgroup大小范围Transient Saves Memory是否支持 transient 内存节省Limit Bucket限制分桶未启用时显示disabledWebGPU Compliant基于DownlevelCapabilities::is_webgpu_compliant()判断是否满足 WebGPU 合规要求。-v级别会追加两大部分一是把wgpu::Features中的每一个 feature flag 逐行打印flag 名称: true/false二是把wgpu::Limits中的全部数值上限逐项打印涵盖纹理尺寸max_texture_dimension_1d/2d/3d、绑定组max_bind_groups、max_bindings_per_bind_group、缓冲绑定max_uniform_buffer_binding_size、max_storage_buffer_binding_size、计算max_compute_workgroup_size_x/y/z、网格着色器max_mesh_*/max_task_*、光线追踪max_blas_*、max_tlas_instance_count、max_ray_recursion_depth、多视图max_multiview_view_count等几十项。此外还会把DownlevelFlags逐项打印true/false。-vv级别在-v基础上追加纹理格式能力表见 wgpu-info/src/human.rs包括两张以所有纹理格式为行、以 bitflag 为列的 ASCII 表格Texture Format Allowed Usages每种格式允许的TextureUsages如COPY_SRC、COPY_DST、TEXTURE_BINDING、STORAGE_BINDING、RENDER_ATTACHMENT等Texture Format Flags每种格式的TextureFormatFeatureFlags如FILTERABLE、MULTISAMPLE_X2/X4/X8/X16、STORAGE_READ_WRITE、STORAGE_ATOMICS等。这两张表由 wgpu-info/src/texture.rs 辅助生成max_texture_format_string_size计算列宽、texture_format_name格式化格式名对 ASTC 格式输出Astc{block}{channel}:形式。2.4 完整命令行选项wgpu-info --help输出定义于 wgpu-info/src/cli.rsUsage: wgpu-info [--input PATH] [--output PATH] [-q/-v/-vv/--json] Information Density: These settings have no effect on the JSON output. The highest verbosity provided will be used if multiple are passed. -q Quiet mode, only print the names and backends of the adapters. [default] Print the adapter info. -v Additionally print all features, limits, and downlevel capabilities. -vv Additionally print all texture capabilities and flags. Options: -h, --help Print this help message. -i, --input PATH Read a json report to make it human readable. (- reads from stdin) -o, --output PATH Destination to write output to. (- writes to stdout) -j, --json Output JSON information instead of human-readable text.各选项的行为在 wgpu-info/src/cli.rs 的主流程中有完整实现-i, --input PATH不重新探测本机 GPU而是读取之前生成的 JSON 报告将其转换为人或文本可读形式-表示从 stdin 读取-o, --output PATH把输出写到指定文件而不是 stdout-表示写回 stdout-j, --json以 JSON 格式输出serde_json::to_writer_pretty美化输出此时 verbosity 标志不生效未知参数会报错并打印帮助后以退出码 101 结束。一个典型的先存 JSON、再离线转可读组合# 生成本机适配器的 JSON 报告到文件 cargo run --bin wgpu-info --json --output gpu-report.json # 之后任何时候把该 JSON 转成可读文本也可加 -v/-vv cargo run --bin wgpu-info --input gpu-report.json -v2.5 JSON 报告结构JSON 报告的结构定义在 wgpu-info/src/report.rs顶层为GpuReport { devices: VecAdapterReport }每个AdapterReport包含info: AdapterInfo适配器基本信息features: Features全部特性位limits: Limits全部上限值downlevel_caps: DownlevelCapabilities降级能力shader model、limits、flagstexture_format_features: HashMapTextureFormat, TextureFormatFeatures每种纹理格式的能力。两份结构体上都有注释 Must be synchronized with the definition on tests/src/report.rs即与测试端 tests/src/report.rs 中的定义保持同步——这正是 JSON 报告被 wgpu 测试体系消费的基础。报告通过GpuReport::generate()本机探测或GpuReport::from_json()解析输入两种途径产生wgpu-info/src/report.rs。三、模式二在多个适配器上批量运行命令3.1 运行机制README 描述当 wgpu-info 被传入任意数量的参数时它会把所有参数解释为一条要运行的命令然后对系统上适配器 × 后端的每一种组合分别运行该命令 N 次When called with any amount of arguments, it will interpret all of the arguments as a command to run. It will run this command N different times, one for every combination of adapter and backend on the system.对于每一次命令调用wgpu-info 都会设置两个环境变量WGPU_ADAPTER_NAME当前适配器的名称WGPU_BACKEND当前后端的名称。被执行的命令即参数读取这两个环境变量就可以在指定的适配器/后端上初始化 wgpu从而实现同一条命令在多台 GPU 上分别跑一遍的效果。README 评价这是跨多适配器测试的主要手段。典型用法把cargo test --test my_test作为被运行命令cargo run --bin wgpu-info -- cargo test --test my_testwgpu 会为每一对适配器后端组合启动一次该命令每次启动时注入对应的WGPU_ADAPTER_NAME与WGPU_BACKEND。3.2 环境变量在下游如何被消费WGPU_ADAPTER_NAME在 wgpu 公共 API 侧有直接支持仓库的 wgpu/src/util/init.rs 中initialize_adapter_from_env_or_default等工具函数会读取WGPU_ADAPTER_NAME按名称在所有候选适配器中挑选匹配项若设置了该变量却找不到对应适配器会以expect(WGPU_ADAPTER_NAME set but no matching adapter found!)报错。这保证了测试程序无需任何代码改动就能被 wgpu-info 定向到指定 GPU。WGPU_BACKEND则用于限制后端的枚举范围从 wgpu/src/util/init.rs 与 wgpu-types/src/backend.rs 的实现可以推断后端选择既可以通过Backends枚举在代码中显式指定也可以通过WGPU_BACKEND环境变量在运行时过滤。因此 wgpu-info 注入的两个变量恰好覆盖了选哪块卡 用哪个后端这两个维度组合起来即为 README 所说的适配器 × 后端全组合。此外仓库中大量测试与示例都遵循这一约定来消费这两个环境变量例如 tests/src/init.rs、tests/src/native.rs、examples/features/src/utils.rs、benches/README.md 等形成了统一的跨适配器测试协议。3.3 与 .gpuconfig 报告体系的关系wgpu-info 的 JSON 报告还深度参与 wgpu 的 GPU 测试基础设施测试运行前会先生成一份.gpuconfig文件描述当前机器上的 GPU 情况供测试框架决定在哪些设备上运行 GPU 测试、哪些测试需要跳过。生成方式不是直接用 CLI而是通过一个测试来产出——wgpu-info/src/tests.rs 中的generate_gpuconfig_report测试调用GpuReport::generate()生成完整报告未设置WGPU_INFO_SAVE_GPUCONFIG_REPORT环境变量时仅验证报告可生成不写文件避免与其他并发测试的读文件竞争设置该环境变量后把报告 JSON 写入仓库根目录下的.gpuconfig。之所以用测试而非cargo runwgpu-info/src/tests.rs 的注释给出了理由直接运行 CLI 会构建一套不同的依赖集导致增量改动需要把整个 wgpu 栈重复构建两次一次给测试、一次给 CLI 二进制。对应地仓库的测试入口 xtask/src/test.rs 在正式跑 GPU 测试之前会用 nextest 过滤表达式binary(wgpu-info)单独执行该测试并设置WGPU_INFO_SAVE_GPUCONFIG_REPORT1生成.gpuconfig然后统计其中name出现的次数作为可测试的 GPU 数量。这段注释同样强调 Needs to be kept in sync with the test in wgpu-info/src/tests.rs。四、从源码看实现细节4.1 参数解析wgpu-info/src/cli.rs 使用pico_args库解析命令行。值得注意的是其设计上的两个细节帮助优先在正式解析之前先检测-h/--help命中即打印帮助并以退出码 101 退出wgpu-info/src/cli.rsverbosity 标志可重复消费主循环while args.contains(-vv) | args.contains(-v) | args.contains(-q)使用位或注释强调是刻意为之持续吞掉所有 verbosity 标志并打印警告保证即便用户传了多个也只取最详细的一档。4.2 报告生成流程wgpu-info/src/report.rs 的GpuReport::generate()是最核心的一段逻辑值得完整阅读。它依次完成创建带调试标志与 DXC 后端配置的实例 → 枚举全部后端适配器 → 对每个适配器采集 features / limits / downlevel capabilities / 全纹理格式能力 → 组装成GpuReport。其中纹理格式能力遍历借助exhaust::Exhaust特性枚举wgpu::TextureFormat的所有变体wgpu-info/src/report.rs。4.3 人类可读输出的排版wgpu-info/src/human.rs 通过一个FlagsExttrait 为 wgpu 的 bitflags 类型Features、DownlevelFlags、TextureUsages、TextureFormatFeatureFlags提供统一能力name()取第一个 flag 位的名称max_debug_print_width()计算所有 flag 名称的最大宽度用于对齐println_table_header/println_table_footer用┌─┬─┐/└─┴─┘绘制 ASCII 表头/表尾这正是-vv纹理能力表的边框来源。空字符串字段统一显示为emptyprint_empty_string见 wgpu-info/src/human.rs。五、常见使用场景小结场景命令查看本机所有适配器基本信息cargo run --bin wgpu-info只列适配器名称与后端cargo run --bin wgpu-info -q查看某块卡的完整特性/上限/降级能力cargo run --bin wgpu-info -v查看纹理格式的完整能力表cargo run --bin wgpu-info -vv导出 JSON 报告供其他工具消费cargo run --bin wgpu-info --json --output gpu-report.json把已有 JSON 报告转成可读文本cargo run --bin wgpu-info --input gpu-report.json在所有适配器×后端组合上跑测试cargo run --bin wgpu-info -- cargo test --test my_test生成 .gpuconfig测试框架使用WGPU_INFO_SAVE_GPUCONFIG_REPORT1 cargo test --test tests -- generate_gpuconfig_report或通过 xtask 自动完成六、小结wgpu-info 虽小却是 wgpu 生态中承上启下的关键一环向上它以人类可读/JSON 两种形态把适配器的特性、上限、降级能力和纹理格式能力完整呈现给开发者向下它以WGPU_ADAPTER_NAMEWGPU_BACKEND两个环境变量定义了跨适配器测试的统一协议并负责生成.gpuconfig报告支撑 tests 目录下的 GPU 测试决策。无论你是想快速摸清一台机器的图形能力还是要让 CI 在一批异构 GPU 上稳定跑同一套测试wgpu-info 都值得作为首选工具。【免费下载链接】wgpuA cross-platform, safe, pure-Rust graphics API.项目地址: https://gitcode.com/GitHub_Trending/wg/wgpu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考