实用工具

设备实用工具

device.color()

此函数是您从 canvas 获取颜色数据的方式。它接受相对于设备在 canvas 上的像素缓冲区内的 X、Y 位置，并返回该像素颜色的 [R,G,B] 数组。

参数	类型	描述	示例
X	Int	表示设备像素缓冲区内 X 坐标的整数值	5
Y	Int	表示设备像素缓冲区内 Y 坐标的整数值	3

• 注意：发送的 X、Y 坐标必须在 Size() 导出设置的像素缓冲区内

返回值	类型	描述	示例
ColorArray	1D 数组	包含坐标 [R, G, B] 值（范围 0-255，HEX 00-FF）的长度为 3 的数组	[128,158,255]

以下是在典型情况下使用该函数的简化示例。

for(var iIdx = 0; iIdx < vLedPositions.length; iIdx++) //For each Led on the device
        {
            var iPxX = vLedPositions[iIdx][0]; //Get the X and Y values from the [X,Y] array
            var iPxY = vLedPositions[iIdx][1];
            var col; // create a variable to contain the [R.G.B] array data
            if(shutdown){       // Check for some settings that can override the Device.color() call
                col = hexToRgb(shutdownColor)
            }else if (LightingMode == "Forced") {
                col = hexToRgb(forcedColor)
            }else{
                col = device.color(iPxX, iPxY);  //Calling Device.color with the X and Y values
            }
            //Saving the Color data in order into a larger Array of all the LED's data
            RGBdata[iIdx*3] = col[0]; // Red Channel
            RGBdata[iIdx*3+1] = col[1]; //Green Channel
            RGBdata[iIdx*3+2] = col[2]; //Blue Channel
            TotalLedCount += 1;
        }

device.getBrightness()

返回设备在 SignalRGB 中的当前亮度级别。此值已应用于 device.color() 或类似函数返回的任何颜色。

返回值	类型	描述	示例
Brightness	int	范围 0-100 内的当前亮度	42

device.getMotherboardName()

返回当前系统主板的 WMI 名称。

返回值	类型	描述	示例
MotherboardName	string	系统的主板名称	B550 Aorus Elite

device.pause()

此函数尝试将设备线程暂停给定的时长。由于操作系统处理线程休眠的方式，这些暂停不保证精确。

参数	类型	描述	示例
Duration	Int	请求的暂停时长（毫秒）	1

• 注意：Windows 的最小休眠时间为 1-2ms，随着休眠时间增长会开始出现偏差，因此不要用于精确计时。

packet[89] = CalculateCrc(packet);
    device.send_report(packet, 91);
    device.pause(1); // We need a pause here (between packets), otherwise the ornata can't keep up.

device.set_endpoint()

此函数更改所有读写命令的活动端点。这对于具有多个打开端点用于不同命令的设备很有用。一个常见的例子是 Logitech 设备，它有一个 RGB 数据端点和一个用于 DPI 设置等系统命令的端点。

参数	类型	描述	示例
interface	HEX	表示要打开的端点接口的十六进制值	0x0002
usage	HEX	表示要打开的端点用法的十六进制值	0x0006
usage_page	HEX	表示要打开的端点用法页面的十六进制值	0x0080
collection	HEX	表示要打开的端点集合的十六进制值	0x0001

function Apply()
{
    var packet = [];

    packet[0] = 0x11;
    packet[1] = 0xFF;
    packet[2] = 0x0C;
    packet[3] = 0x5E;

    device.set_endpoint(1, 0x0602, 0xff43); // System Interface
    device.write(packet, 20);
}

device.log()

此函数是插件版本的 console.log。它接受字符串、数字、对象或数组，并将其记录在设备控制台中，用于调试和用户信息。这对于列出 DPI 更改、错误，或在开发过程中显示数据包布局或读取命令的输入特别有用。

• 注意：此函数将尽可能尝试将 JavaScript 变量转换为字符串。使用 parseInt()、toString() 或 JSON.stringify 记录 JavaScript 模板字面量可以让您更好地控制转换和格式化。

参数	类型	描述	示例	默认值
Item	Javascript 值	要记录的字符串、数字、数组或其他 JavaScript 值
Options	JavaScript 对象	包含设置参数的 JavaScript 对象	{hex: True}	{}

选项	描述	类型	默认值
Hex	设置整数是否应以十进制或十六进制格式打印	Boolean	False
toFile	设置打印的项目是否应出现在调试日志中，或仅在设备控制台中	Boolean	False

let ImportantData = "i have really important info here";
    device.log(ImportantData, {toFile: true})

警报

警报可用于在设备出现问题时向用户发出可见提示。应谨慎使用这些功能，并将其保留给关键问题，例如设备未正确配置。

device.notify()

为用户创建新警报。返回值可用于选择性地删除警报，如果用户修复了警报中的问题，则应这样做。

注意

警报文本应保持一致，以免向用户发送大量警报。

警报优先级	描述	值
Info	普通警报	0
Important	关键（高亮）警报	1

参数	类型	描述	示例
Title	String	警报标题	Firmware Incompatible
Description	String	警报描述	Firmware Version must be >= 2.0.0
Priority	Int	警报优先级	0 | 1

返回值	类型	描述
AlertId	String	创建的警报 ID 字符串

let Alertid = device.notify("Really Important Issue", "Please Fix", 1);

device.denotify()

删除给定警报（如果存在）。

参数	类型	描述
AlertId	String	device.notify 返回的 AlertId

let Alertid = device.notify("Really Important Issue", "Please Fix", 1);
  // Do stuff and recheck if the alerted issue is fixed
  device.denotify(AlertId);

消息

设备消息提供了一种向用户传递重要但非关键信息的方式。这些消息只会出现在设备页面上。

device.addMessage()

添加具有给定 MessageId 的新设备消息。

参数	类型	描述	示例
messageId	string	与设备消息关联的 MessageId	”mymessage”
message	string	要显示的消息文本	”The message”
tooltip	string	悬停时显示的附加文本	”Some more info”

device.addMessage("message1", "Hey Dude you should know this", "Here's some extra info about it too");

device.removeMessage()

删除使用给定 MessageId 创建的消息（如果存在）。

参数	类型	描述
messageId	string	要删除的 MessageId

device.addMessage("message1", "Hey Dude you should know this", "Here's some extra info about it too");

  // message is no longer relevant
  device.removeMessage("message1");