SetMonitorBrightness是Windows 10+唯一绕过显卡驱动直接控制物理显示器亮度的API，需管理员权限、合法HMONITOR句柄、SE_SHUTDOWN_NAME权限，亮度范围0–100，多屏需逐个调用。
Windows 上用 SetMonitorBrightness 调亮度最直接
Windows 10+ 系统下，SetMonitorBrightness 是唯一能绕过显卡驱动、直接控制物理显示器亮度的 API（需管理员权限）。它作用于指定的 HMONITOR，不是整个桌面或显卡驱动层。常见错误是传入无效句柄或忽略返回值——该函数失败时几乎不报错，只返回 FALSE，且不填充 GetLastError()。
- 必须先用
EnumDisplayMonitors获取合法HMONITOR，不能硬编码或用GetDesktopWindow - 亮度范围固定为 0–100，传 50 表示 50%，不是 0–255 或百分比字符串
- 调用前需启用
SE_SHUTDOWN_NAME权限（通过AdjustTokenPrivileges），否则静默失败 - 多显示器场景下，每个
HMONITOR需单独调用，不能批量设置
macOS 上只能走 IODisplayWrangler 私有 API
Apple 官方不提供公开的屏幕亮度控制接口，IODisplayWrangler 是唯一稳定可用的私有框架（从 macOS 10.6 沿用至今）。它依赖 IOKit，必须链接 -framework IOKit，且在 macOS 10.15+ 上需关闭 SIP 才能写入（开发调试可行，生产环境不可行）。
- 核心函数是
IODisplaySetFloatParameter，参数名固定为kIODisplayBrightnessKey - 值域为 0.0–1.0 浮点数，0.5 表示中间亮度，不是整数百分比
- 必须先用
IODisplayCreateInfoDictionary获取 display service handle，不能用 CGDisplayID 直接转换 - 没有错误码返回，失败时函数直接返回
kIOReturnSuccess但无实际效果——建议配合IODisplayGetFloatParameter读回验证
Linux 下靠 sysfs 文件系统暴露的亮度接口
绝大多数 Linux 发行版（包括 Ubuntu、Fedora、Arch）都通过 /sys/class/backlight/ 下的子目录暴露亮度控制能力，无需 root 权限（但需用户属于 video 组）。路径和最大值因驱动而异：intel_backlight、acpi_video0、amdgpu_bl0 都可能同时存在，但只有一个是生效的。
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
- 先读
/sys/class/backlight/*/max_brightness找出非零值的目录，再写actual_brightness - 写入值必须是整数，且在 0 到
max_brightness之间（注意：有些设备最小值不是 0，而是 1） - 不要用
echo命令测试——C++ 中必须用open()+write()，避免 shell 重定向引入缓冲或权限问题 - 部分 Wayland 环境（如 GNOME on Wayland）会拦截 sysfs 写入，此时应 fallback 到
org.freedesktop.UPowerD-Bus 接口
跨平台封装的关键难点不在调用，而在发现与容错
真正难的是让一个 C++ 类在不同系统上“找到可操作的亮度控制点”，而不是简单 if-else 分支调用。比如 Windows 可能有多个显示器但只有主屏支持亮度调节；macOS 在外接显示器上通常失效；Linux 的 backlight 目录可能为空或权限拒绝。
立即学习“C++免费学习笔记（深入）”；
- 初始化阶段必须做探测：Windows 枚举所有 monitor 并逐个
GetMonitorBrightness验证是否支持；macOS 尝试获取每个 display service；Linux 扫描所有 backlight 子目录并尝试 open + write - 不暴露原始错误码，统一返回枚举如
BrightnessResult::UNSUPPORTED、BrightnessResult::PERMISSION_DENIED - 亮度值抽象为 0.0–1.0 归一化浮点，内部按平台映射：Windows 映射到 0–100，macOS 直接传递，Linux 插值到
max_brightness - 别试图监听亮度变化事件——Windows/macOS/Linux 均无可靠通知机制，轮询代价高且不准
跨平台亮度类不是把三个平台 API 包一层就完事，而是得接受“某些设备根本没法调”这个事实，并安静地 fallback 到不可用状态。用户看到的只是一个 setLevel(0.7f)，背后要处理的其实是权限、驱动兼容性、多显示器拓扑、甚至 BIOS 层限制。
