amd-adlx 1.0.3

AMD ADLX Python Bindings

========================



amd-adlx provides Python bindings for the AMD Display Library eXtra (ADLX)

SDK. It allows Python applications to query AMD GPUs and displays, read

performance metrics, and access supported display, 3D graphics, multimedia,

power tuning, and GPU tuning features.



The package is installed as "amd-adlx" and imported as "adlx".





Requirements

------------



- 64-bit Windows

- CPython 3.10, 3.11, 3.12, or 3.13

- A supported AMD GPU

- An AMD Software driver that includes the ADLX runtime



Feature availability depends on the GPU, display, and installed driver. Check

the relevant IsSupported...() method before using an optional feature.





Installation

------------



Install amd-adlx with pip:



    py -m pip install amd-adlx



To install a wheel from a local path:



    py -m pip install C:\path\to\amd_adlx-<version>-<python-tag>-win_amd64.whl



Verify the installation:



    py -m pip show amd-adlx

    py -c "from adlx import ADLX; print('amd-adlx imported successfully')"





Quick Start

-----------



Create an ADLXHelper, initialize it before requesting services, and always

terminate it when finished:



    from adlx import ADLX





    helper = ADLX.ADLXHelper()

    result = helper.Initialize()



    if result != ADLX.ADLX_RESULT.ADLX_OK:

        raise RuntimeError(f"ADLX initialization failed: {result}")



    try:

        system = helper.GetSystemServices()



        print(f"ADLX version: {helper.QueryFullVersion()}")

        for gpu in system.GetGPUs():

            print(f"GPU: {gpu.Name()}")

            print(f"  Device ID: {gpu.DeviceId()}")

            print(f"  Vendor ID: {gpu.VendorId()}")

    finally:

        helper.Terminate()



Do not instantiate interfaces such as IADLXGPU or IADLXDisplay directly.

Obtain them from the system or the corresponding service interface.





List Connected Displays

-----------------------



    from adlx import ADLX





    helper = ADLX.ADLXHelper()

    result = helper.Initialize()

    if result != ADLX.ADLX_RESULT.ADLX_OK:

        raise RuntimeError(f"ADLX initialization failed: {result}")



    try:

        system = helper.GetSystemServices()

        display_services = system.GetDisplaysServices()



        for display in display_services.GetDisplays():

            width, height = display.NativeResolution()

            print(

                f"{display.Name()}: {width}x{height}, "

                f"{display.RefreshRate()} Hz"

            )

    finally:

        helper.Terminate()





Read Current GPU Metrics

------------------------



Metric methods may return None when a value is unavailable. Applications

should handle missing values because metric support can differ between GPUs.



    from adlx import ADLX





    helper = ADLX.ADLXHelper()

    result = helper.Initialize()

    if result != ADLX.ADLX_RESULT.ADLX_OK:

        raise RuntimeError(f"ADLX initialization failed: {result}")



    try:

        system = helper.GetSystemServices()

        monitoring = system.GetPerformanceMonitoringServices()



        for gpu in system.GetGPUs():

            metrics = monitoring.GetCurrentGPUMetrics(gpu)

            print(gpu.Name())

            print(f"  Usage: {metrics.GPUUsage()}%")

            print(f"  Temperature: {metrics.GPUTemperature()} C")

            print(f"  Core clock: {metrics.GPUClockSpeed()} MHz")

            print(f"  VRAM usage: {metrics.GPUVRAM()} MB")

    finally:

        helper.Terminate()





Check Feature Support

---------------------



For example, check whether automatic GPU tuning is supported before using it:



    system = helper.GetSystemServices()

    tuning = system.GetGPUTuningServices()



    for gpu in system.GetGPUs():

        if tuning.IsSupportedAutoTuning(gpu):

            print(f"Auto tuning is supported on {gpu.Name()}")

        else:

            print(f"Auto tuning is not supported on {gpu.Name()}")



Changing tuning, power, display, or 3D settings can affect system behavior.

Validate feature support and accepted ranges before changing a setting.





Main Service Areas

------------------



GetSystemServices() provides access to the main ADLX domains:



- GPU and system information

- Displays and display settings

- Performance monitoring

- GPU tuning and power tuning

- 3D graphics settings

- Multimedia features

- Desktop and Eyefinity features

- I2C access

- Change-event listeners



The Python API follows the ADLX C++ interface naming closely. Refer to the ADLX

SDK documentation for detailed interface behavior, parameters, ranges, and

return values.





Resource Lifetime

-----------------



Keep ADLXHelper initialized while ADLX interface objects are in use. Release

references to those objects before calling Terminate() in long-running or

debugger-hosted applications. Using try/finally ensures that Terminate() is

called when an operation raises an exception.





Troubleshooting

---------------



If Python reports "No module named 'adlx'", confirm that amd-adlx was installed

in the same Python environment that runs the application:



    py -m pip show amd-adlx

    py -c "import sys; print(sys.executable)"



If importing adlx reports a DLL loading error, verify that:



- Python and the installed wheel are both 64-bit.

- The wheel matches the active CPython minor version.

- A current AMD Software driver is installed.

- The required Microsoft Visual C++ runtime is installed.



If a method returns None or a feature is unavailable, the hardware or driver

may not expose that value. Query feature support first and treat unavailable

optional values as normal.





Documentation and Support

-------------------------



ADLX product page:

https://gpuopen.com/adlx/



ADLX SDK documentation:

https://gpuopen.com/manuals/adlx/



Source repository:

https://github.com/GPUOpen-LibrariesAndSDKs/ADLX/tree/main/ADLXPybind



Issue tracker:

https://github.com/GPUOpen-LibrariesAndSDKs/ADLX/issues



ADLX SDK License Agreement:

https://github.com/GPUOpen-LibrariesAndSDKs/ADLX/blob/main/ADLX%20SDK%20License%20Agreement.pdf