實用工具

裝置實用工具

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] 值的長度為 3 的陣列，範圍從 0-255（十六進位 00-FF）	[128,158,255]

以下是函式在典型情況下使用的精簡範例。

for(var iIdx = 0; iIdx < vLedPositions.length; iIdx++) // 對裝置上的每個 LED
        {
            var iPxX = vLedPositions[iIdx][0]; // 從 [X,Y] 陣列中取得 X 和 Y 值
            var iPxY = vLedPositions[iIdx][1];
            var col; // 建立變數以包含 [R.G.B] 陣列資料
            if(shutdown){       // 檢查可以覆寫 Device.color() 呼叫的一些設定
                col = hexToRgb(shutdownColor)
            }else if (LightingMode == "Forced") {
                col = hexToRgb(forcedColor)
            }else{
                col = device.color(iPxX, iPxY);  // 使用 X 和 Y 值呼叫 Device.color
            }
            // 按順序將顏色資料儲存到所有 LED 資料的更大陣列中
            RGBdata[iIdx*3] = col[0]; // 紅色通道
            RGBdata[iIdx*3+1] = col[1]; // 綠色通道
            RGBdata[iIdx*3+2] = col[2]; // 藍色通道
            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); // 這裡需要暫停（在封包之間），否則 ornata 跟不上。

device.set_endpoint()

此函式更改所有讀取和寫入命令的活動端點。這對於有多個不同命令開放端點的裝置很有用。一個常見的例子是 Logitech 裝置，它有一個 RGB 資料端點和一個用於 DPI 設定等系統命令的端點。

參數	類型	說明	範例
interface	HEX	表示要開啟的端點介面的 0x 十六進位值	0x0002
usage	HEX	表示要開啟的端點用途的 0x 十六進位值	0x0006
usage_page	HEX	表示要開啟的端點 usage_page 的 0x 十六進位值	0x0080
collection	HEX	表示要開啟的端點集合的 0x 十六進位值	0x0001

function Apply()
{
    var packet = [];

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

    device.set_endpoint(1, 0x0602, 0xff43); // 系統介面
    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);
  // 執行一些操作並重新檢查警示的問題是否已修復
  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");

  // 訊息不再相關
  device.removeMessage("message1");