Configuration

Introduction

Since GLXOSD v3, most of configuration is done through a set of Lua scripts that give almost complete control over how the OSD looks and what information is shown in it. Because you are given the complete Lua language to play with, you may define common constants, dynamically determine values, etc...

Paths

By default, GLXOSD looks for configuration scripts in the following directories (in that particular order):

  • $XDG_CONFIG_HOME/glxosd/ (if $XDG_CONFIG_HOME isn't set, the default value of ~/.config/glxosd/ will be used instead)
  • /etc/glxosd/
  • $GLXOSD_SCRIPTS_ROOT/glxosd/conf/ (this is usually /usr/share/glxosd/glxosd/conf/)

You can modify the path by modifying the content of chainload.lua which can be located in one of the directories mentioned above.

Common configuration table types

Colors

Colors are represented by a table with 4 keys: r, g, b and a, which stand for red, green blue and alpha respectively. The values must be numbers between 0 and 1.

  • {r=1, g=0, b=0, a=1} is red.
  • {r=0, g=1, b=0, a=1} is green.
  • {r=0, g=1, b=1, a=1} is cyan.
  • {r=0, g=0, b=0.5, a=0.5} is half-opaque navy.

Key combinations

Key combinations are represented by a table with 2 keys:

  • main_key – the main key of the key combination. For example, for the combination Shift + F10 the main key is F10. The names for the keys should be as defined in X11/keysymdef.h.
  • modifiers – a list of modifier keys that have to be pressed when the main key is pressed. Possible elements include: shift, alt, control, caps.

Examples:

  • Shift + F10

    {
        main_key = "F10",
        modifiers = {"shift"}
    }
  • Ctrl + Alt + K

    {
        main_key = "k",
        modifiers = {"control", "alt"}
    }

Common markup options

Individual pieces of text can be customised using the following configuration:

KeyValue typeValue
font_sizenumber (positive)The text size.
colortable (color)

The color of the text.

background_colortable (color)

The background color of each symbol.

gammanumber (positive)

Value used for gamma correction.

underline overline strikethroughboolean

A table describing the style of an underline/overline/strikethrough.

KeyValue typeValue
enabledboolean

Set to false to disable the underline/overline/strikethrough

colortable (color)

The color of the underline/overline/strikethrough

Config files

glxosd_config.lua

This is the main configuration file. Once it executes, the following global variables should be set:

  • GLXOSD_CONFIG – the main configuration table.
  • CURRENT_PATH_CONFIG – the table that maps library names to their paths. Please see paths.lua for an example.

paths.lua

The default glxosd_config.lua runs a file called paths.lua first. Its purpose is to help the dynamic linker locate the required shared libraries.

The default paths.lua contains logic to locate libnvidia-ml on Ubuntu-based systems.

arch.lua

GLXOSD ships with arch.lua, which is a script that determines the architecture of the host system, as opposed to the architecture of the current application. This is useful for determining paths in multiarch systems.

chainload.lua

chainload.lua is a script that must return the list of configuration paths where to look for further configuration scripts. This essentially allows you to specify custom locations for configuration scripts.

Configuration globals

GLXOSD_CONFIG

GLXOSD_CONFIG is a global table which contains the following keys:

  • plugin – the value should be a list of tables, where each table contains the following keys:

    • path – the path to the plugin's main file.
    • enabled – set to false to disable the plugin and set to true to enable the plugin.
    • config – the configuration table for the plugin.

CURRENT_PATH_CONFIG

CURRENT_PATH_CONFIG must contain paths or names to shared libraries to be used by the dynamic linker. It must contain the following data:

NameDefaultDescription
libGLlibGL.so.1

The path to libGL (the OpenGL shared library)

libX11libX11.so.6

The path to libX11

libfreetype_gllibglxosd-freetype-gl.so.1

The path to freetype-gl.

libfontconfiglibfontconfig.so.1

The path to fontconfig

libsensorslibsensors.so.4

The path to libsensors

libnvidia_mlDetermined programatically

The path to libnvidia-ml (the shared library that contains NVML)

Plugins

OSD

The path for the OSD plugin is plugins/OSD/OSD.

Configuration options (common markup options also apply!):

KeyValue typeValue
refresh_timenumber (positive)The time in milliseconds between OSD redraws. This is done to lower the overhead because reuploading the text to the GPU every frame is expensive.
align_to_h align_to_vstring (enumeration)

The alignment of the OSD's bounding box in respect to the view.

Acceptable values for align_to_h:

  • left – aligns the left side of the OSD to the left side of the view
  • right – aligns the right side of the OSD to the right side of the view
  • right_absolute – aligns the left side of the OSD to the right side of the view.

Acceptable values for align_to_v:

  • top – aligns the top side of the OSD to the top side of the view
  • bottom – aligns the bottom side of the OSD to the bottom side of the view
  • bottom_absolute – aligns the top side of the OSD to the bottom side of the view
offset_x offset_xnumberThe position of the OSD in respect to the corner it's aligned to.
fontstringThe font to be used. This is a Fontconfig font query string.
text_alignmentstring (enumeration)

Text alignment in respect to the OSD's bounding box.

The possible values include:

  • left
  • right
  • center
outlinetable

The configuration table for the OSD text outline.

KeyValue typeValue
typestring

The type of the outline. Possible values include:

  • none – no outline
  • outer – outer rim of the symbols
  • inner – inner rim of the symbols
  • inside – the interior of the symbols
thicknessnumber (non-negative)

The thickness of the outline.

colortable (color)

The color of the outline.

lcd_filter_enabledboolean

LCD filtering may improve the appearance of the text. Set this setting to true to enable LCD filtering and to false to disable it.

toggle_key_combotable (key combination)

The key combination that toggles the OSD visibility. Set to nil to disable.

osd_data_providerstable (color)

The list of data providers to collect data from. This value must be a table of tables with the following keys:

KeyValue typeValue
pathstring

The path to the data provider's main file.

enabledboolean

Set to false to disable the data provider and set to true to enable the data provider.

configtable

The configuration table for the data provider.

Data providers

FrameDataProvider

The FrameDataProvider data provider provides statistics such as FPS and frame duration.

The path to the FrameDataProvider main file is plugins/OSD/dataproviders/FrameDataProvider

FrameDataProvider configuration table options:

KeyValue typeValue
refresh_timenumber (positive)

The FrameDataProvider provides the data from the last complete chunk (timespan) of n milliseconds, where n is the value of refresh_time.

formatter_functionfunction

The function used for formatting the text on the OSD. This can be used to completely customize what data is shown and how it is formatted.

The default formatter function is located in the configuration directory and can be loaded using the following code snippet: ConfigurationManager.config_file("OSD/dataproviders/FrameDataProvider/formatterunction.lua")

The default formatter function has the following options:

KeyValue typeValue
low_fpsnumber

If the FPS is lower than this setting, the default formatter_function will highlight the FPS as a bad value.

acceptable_value_colortable (color)

The color of acceptable values (e.g. high enough FPS).

unacceptable_value_colortable (color)

The color of unacceptable values (e.g. low FPS).

header_styletable

The style of the header of this provider's OSD section.

It has the following options (plus common markup options):

KeyValue typeValue
enabledboolean

Set to false to disable the header.

formattable

The strings and formats for the this data provider. For instance, this allows you to replace the text on the OSD with abbreviations.

It has the following options:

KeyDefault Value
header

"Frame timings"

fps

"FPS: "

fps_number

"%.2f"

average_frame_duration

"AFD: %.2f ms"

osd_averate_time_spent_per_frame

"OSDATSPF: %.2f ms"

no_data

"Collecting..."

data_ordertable (list)

An ordered list of the statistics to be displayed. You can reorder or remove these to customise in what order and what statistics are displayed.

The possible elements include:

NameDescription
FPS

Frames Per Second (over the last timespan).

AFD

Average Frame Duration (over the timespan).

OSDATSPF

OSD Average Time Spent Per Frame - time spent by GLXOSD per frame on average over the last timespan.

LibsensorsDataProvider

The LibsensorsDataProvider data provider provides information from lm-sensors.

The path to the LibsensorsDataProvider main file is plugins/OSD/dataproviders/LibsensorsDataProvider

LibsensorsDataProvider configuration table options:

KeyValue typeValue
formatter_functionfunction

The function used for formatting the text on the OSD. This can be used to completely customize what data is shown and how it is formatted.

The default formatter function is located in the configuration directory and can be loaded using the following code snippet: ConfigurationManager.config_file("OSD/dataproviders/LibsensorsDataProvider/formatterfunction.lua")

The default formatter function has the following options:

KeyValue typeValue
chip_filter_functionfunction

The function used to filter out chips that you don't want to be displayed in the OSD.

This function has two parameters:

  • self – the instance of the data provider
  • chip – the chip to be considered
feature_filter_functionfunction

The function used to filter out features that you don't want to be displayed in the OSD.

This function has three parameters:

  • self – the instance of the data provider
  • chip – the chip to be considered
max_temperature_warning_thresholdnumber

If the temperature is above the maximum temperature for the device minus max_temperature_warning_threshold, the temperature will be highlighted.

default_temperature_colortable (color)

The color to be used in case the maximum acceptable temperature is unknown.

good_temperature_colortable (color)

The color to be used if the color is under the maximum temperature for the device minus the warning threshold.

warning_temperature_colortable (color)

The color to be used if the color is over the maximum temperature for the device minus the warning threshold, but under the maximum temperature for the device.

overheating_temperature_colortable (color)

The color to be used if the color is over the maximum temperature for the device.

formattable

The strings and formats for the this data provider. For instance, this allows you to replace the text on the OSD with abbreviations.

It has the following options:

KeyDefault Value
header

"Sensors"

header_styletable

The style of the header of this provider's OSD section.

It has the following options (plus common markup options):

KeyValue typeValue
enabledboolean

Set to false to disable the header.

NVMLDataProvider

The NVMLDataProvider data provider provides information about NVIDIA GPUs.

The path to the NVMLDataProvider main file is plugins/OSD/dataproviders/NVMLDataProvider

NVMLDataProvider configuration table options:

KeyValue typeValue
formatter_functionfunction

The function used for formatting the text on the OSD. This can be used to completely customize what data is shown and how it is formatted.

The default formatter function is located in the configuration directory and can be loaded using the following code snippet: ConfigurationManager.config_file("OSD/dataproviders/FrameDataProvider/formatterunction.lua")

The default formatter function has the following options:

KeyValue typeValue
default_temperature_colortable (color)

The color to be used in case the slowdown and shutdown temperatures are unknown.

normal_temperature_colortable (color)

The color to be used to represent normal temperatures.

slowdown_temperature_colortable (color)

The color to be used to represent temperatures that cause a slowdown of the graphics card.

formattable

The strings and formats for the this data provider. For instance, this allows you to replace the text on the OSD with abbreviations.

It has the following options:

KeyDefault Value
header

"NVIDIA GPUs",

temperature

"Temperature: ",

throttled

"(thrtl)",

graphics_clock

"Graphics clock: %d",

sm_clock

"SM clock: %d",

memory_clock

"Memory clock: %d",

gpu_utilisation

"GPU utilisation: %d%%",

memory_utilisation

"Memory utilisation: %d%%"

header_styletable

The style of the header of this provider's OSD section.

It has the following options (plus common markup options):

KeyValue typeValue
enabledboolean

Set to false to disable the header.

data_ordertable (list)

An ordered list of the statistics to be displayed. You can reorder or remove these to customise in what order and what statistics are displayed.

The possible elements include:

NameDescription
temperature

GPU temperature sensor readings.

gpu_utilisation

GPU utilisation percentage.

memory_utilisation

Memory utilisation percentage.

graphics_clock

The current GPU clock.

memory_clock

The current memory clock.

sm_clock

The current SM (Streaming Multiprocessor) clock.

TimeRecorder

The path for the TimeRecorder plugin is plugins/TimeRecorder/TimeRecorder.

The TimeRecorder plugin is the plugin responsible for logging frame timings, i.e. creating frame timing logs.

Configuration options:

KeyValue typeValue
benchmark_output_directorystringThe directory to write the time logs to.
start_benchmark_keytable (key combination)

The key combination that starts the frame log recording. Set to nil to disable.

end_benchmark_keytable (key combination)

The key combination that ends the frame log recording. Set to nil to disable. You can use the same key as start_benchmark_key.

enable_minimise_overhead_mode_during_benchmarkboolean

If this is set to true, GLXOSD will not execute potentially expensive tasks such as rendering the OSD while logging frame timings.