wallpaper_set_subscriptions

This function subscribes to the given metric(s) from the Companion app. This is used to get real-time system information, and enable mouse input, which is disabled for Live Wallpapers by default.

IMPORTANT See this guide for making a basic Live Wallpaper and (optionally) setting up the Companion app on Windows.

NOTE Graphics drivers must be up-to-date on the target computer for GPU metrics to work correctly.

NOTE Each call to this function cancels any previously active subscriptions, so only those included in the last call remain active.

Arguments

You pass an array into this function, containing one or more of the following strings: "desktop_mouse", "cpu", "gpu", "battery", "ram", "disk", "network", "audio".

"desktop_mouse" enables mouse input for your Live Wallpaper. The other options allow the Wallpaper Subscription Data event to be triggered, where you receive data on the metrics you chose to subscribe to.

Receiving Metrics

Within the Wallpaper Subscription Data event you will receive updates for subscribed metrics, around once every second, except for audio which is ten times a second.

The event will contain a wallpaper_subscription_data variable which is a struct, containing the following members:

cpu (Array): Array of CPU devices. Each entry in this array is a struct, containing the following members:
- name (String): The name of the CPU.
- num_logical_cores (Integer Real): Number of logical cores.
- num_physical_cores (Integer Real): Number of physical cores.
- usage_pct (Integer Real): The load percentage of the CPU.
- current_clock_speed_MHz (Integer Real): The current clock speed of the CPU in MHz.
- max_clock_speed_MHz (Integer Real): The maximum clock speed of the CPU in MHz.
- voltage_V (Integer Real): The current voltage of the CPU in volts.
gpu (Array): Array of GPU devices. Each entry in this array is a struct, containing the following members:
- name (String): The name of the GPU.
- usage_pct (Integer Real): The load percentage of the GPU.
- clock_speed_MHz (Integer Real): The current clock speed of the GPU in MHz.
- fan_speed_pct or fan_speed_rpm (Array of Integer Reals): The target speed of each GPU fan. Expressed as a percentage of the maximum speed on NVIDIA GPUs and in RPM on AMD GPUs (AMD will only return one element in the array).
- power_usage_W (Integer Real): The power usage of the GPU in Watt.
- temperature_C (Integer Real): The temperature of the GPU in Celsius.
- memory_used_bytes (String): How much of the GPU memory is used up in bytes.
- memory_available_bytes (String): How much of the GPU memory is available in bytes.
- memory_total_bytes (String): The total GPU memory in bytes.
battery (Array): Array of battery devices. Each entry in this array is a struct, containing the following members:
- name (String): The name of the battery.
- is_charging (Boolean): Indicates if the battery is charging.
- remaining_charge_pct (Integer Real): Percentage of the charge left in the battery.
- remaining_time_min (Integer Real): The estimated time left of the battery in minutes.
ram (Array): Array of RAM devices. Each entry in this array is a struct, containing the following members:
- name (String): The name of the RAM.
- available_bytes (String): How much of the RAM memory is available in bytes.
- total_bytes (String): The total RAM memory in bytes.
- used_bytes (String): How much of the GPU memory is used up in bytes.
disk (Array): Array of disks. Each entry in this array is a struct, containing the following members:
- name (String): The name of the disk.
- available_bytes (String): How much of the disk memory is available in bytes.
- total_bytes (String): The total disk memory in bytes.
- used_bytes (String): How much of the GPU memory is used up in bytes.
network (Array): Array of network devices. Each entry in this array is a struct, containing the following members:
- bandwidth_bps (String): The bandwidth of the network in bits per second.
- send_bps (Integer Real): The current bytes sent per second on the network.
- received_bps (Integer Real): The current bytes received per second on the network.
audio (Array): Array of audio devices. Each entry in this array is a struct, containing the following members:
- freq_resolution (Integer Real): The frequency resolution, is always 10.
- spectrum_amplitude (Array): Represents a spectrum analysis of measured sound amplitudes on the system. The frequency will span from 0 Hz up to the Nyquist frequency, i.e half that of the system's sampling rate. If it is, for example, 44.1 kHz (the most common), the frequencies will range from 0 Hz to 22050 Hz. Each bin will always represent a range of freq_resolution. E.g. if it is 10, this array will consist of 2205 data points if the sampling rate is 44.1 kHz, and 2400 if it is 48 kHz (also common).

If some information could not be retrieved from the system, its corresponding variable will not be present in this structure. That may cause a crash if you try to access a variable that doesn't exist. To prevent that, use struct_exists to check that a variable exists in a struct, before accessing it.

Syntax:

Returns:

Example:

Argument	Type	Description
subscriptions	Array	An array containing strings, which are the metrics you want to subscribe to

// Create Event
wallpaper_set_subscriptions(["desktop_mouse", "cpu"]);

// Wallpaper Subscription Data Event
var _cpus = wallpaper_subscription_data.cpu;

file = file_text_open_append("sysinfo.txt");
file_text_writeln(file);
file_text_write_string(file, string(date_current_datetime()));
file_text_write_string(file, $"\nCPU count: {array_length(_cpus)}");

array_foreach(_cpus, function(_cpu, _num)
{
   if (!struct_exists(_cpu, "usage_pct")) return;
   var _str = $"\nCPU {_num} load: {_cpu.usage_pct}%";
   file_text_write_string(file, _str);
});

file_text_close(file);

The first line, run in the Create event, enables mouse input and subscribes to CPU metrics.

In the Wallpaper Subscription Data event, it gets the devices array for the CPU, and opens a text file to write metrics to.

In that file, it writes the current datetime, CPU device count (which is the length of the array), and then proceeds to write the load percentage of each CPU device in the array.

This code generates the following text in the sysinfo.txt file, found in the working directory: