Metadata-Version: 2.4
Name: amd-adlx
Version: 1.0.3
Summary: Python bindings for ADLX SDK
Author-email: AMD <adlx@amd.com>
License: ADLX SDK License Agreement
Project-URL: Homepage, https://gpuopen.com/adlx/
Project-URL: Repository, https://github.com/GPUOpen-LibrariesAndSDKs/ADLX/tree/main/ADLXPybind
Project-URL: License, https://github.com/GPUOpen-LibrariesAndSDKs/ADLX/blob/main/ADLX%20SDK%20License%20Agreement.pdf
Keywords: adlx
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Description-Content-Type: text/plain
Dynamic: requires-python

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
