Control API

Control API Specification - Version 1

Common

Common Functions

ctlInit

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlInit(ctl_init_args_t *pInitDesc, ctl_api_handle_t *phAPIHandle)

Control Api Init.

  • Control Api Init

Parameters:

  • pInitDesc – [in][out] App’s control API version

  • phAPIHandle – [in][out][release] Control API handle

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pInitDesc

    • nullptr == phAPIHandle

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlClose

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlClose(ctl_api_handle_t hAPIHandle)

Control Api Destroy.

  • Control Api Close

Parameters:

hAPIHandle – [in][release] Control API implementation handle obtained during init call

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hAPIHandle

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlSetRuntimePath

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlSetRuntimePath(ctl_runtime_path_args_t *pArgs)

Runtime path.

  • Control Api set runtime path. Optional call from a loader which allows the loaded runtime to enumerate only the adapters which the specified runtime is responsible for. This is done usually by a loader or by callers who know how to get the specific runtime of interest. This call right now is reserved for use by Intel components.

Parameters:

pArgs – [in] Runtime path

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pArgs

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlWaitForPropertyChange

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlWaitForPropertyChange(ctl_device_adapter_handle_t hDeviceAdapter, ctl_wait_property_change_args_t *pArgs)

Wait for a property change. Note that this is a blocking call.

  • Wait for a property change in display, 3d, media etc.

Parameters:

  • hDeviceAdapter – [in][release] handle to control device adapter

  • pArgs – [in] Argument containing information about which property changes to listen for

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceAdapter

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pArgs

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlReservedCall

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlReservedCall(ctl_device_adapter_handle_t hDeviceAdapter, ctl_reserved_args_t *pArgs)

Reserved function.

  • Reserved function

Parameters:

  • hDeviceAdapter – [in][release] handle to control device adapter

  • pArgs – [in] Argument containing information

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceAdapter

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pArgs

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

Common Enums

ctl_init_flags_t

enum ctl_init_flag_t

Values:

enumerator CTL_INIT_FLAG_USE_LEVEL_ZERO

Use Level0 or not. This is usually required for telemetry, performance, frequency related APIs.

enumerator CTL_INIT_FLAG_MAX

ctl_property_value_type_t

enum ctl_property_value_type_t

Value type.

Values:

enumerator CTL_PROPERTY_VALUE_TYPE_BOOL

Boolean.

enumerator CTL_PROPERTY_VALUE_TYPE_FLOAT

Float.

enumerator CTL_PROPERTY_VALUE_TYPE_INT32

Int32.

enumerator CTL_PROPERTY_VALUE_TYPE_UINT32

Unsigned Int32.

enumerator CTL_PROPERTY_VALUE_TYPE_ENUM

Enum.

enumerator CTL_PROPERTY_VALUE_TYPE_CUSTOM

Custom argument.

enumerator CTL_PROPERTY_VALUE_TYPE_MAX

ctl_result_t

enum ctl_result_t

Defines Return/Error codes. All generic error (bit30) codes are between 0x40000000-0x4000FFFF. All 3D (bit 29) specific error codes are between 0x60000000-0x6000FFFF. All media (bit 28) specific error codes are between 0x50000000-0x5000FFFF. All display (bit 27) specific error codes are between 0x48000000-0x4800FFFF All core (bit 26) specific error codes are between 0x44000000-0x4400FFFF Success result code with additional info are between 0x00000001-0x0000FFFF.

Values:

enumerator CTL_RESULT_SUCCESS

success

enumerator CTL_RESULT_SUCCESS_STILL_OPEN_BY_ANOTHER_CALLER

success but still open by another caller

enumerator CTL_RESULT_ERROR_SUCCESS_END

“Success group error code end value, not to be used

”

enumerator CTL_RESULT_ERROR_GENERIC_START

Generic error code starting value, not to be used.

enumerator CTL_RESULT_ERROR_NOT_INITIALIZED

Result not initialized.

enumerator CTL_RESULT_ERROR_ALREADY_INITIALIZED

Already initialized.

enumerator CTL_RESULT_ERROR_DEVICE_LOST

Device hung, reset, was removed, or driver update occurred.

enumerator CTL_RESULT_ERROR_OUT_OF_HOST_MEMORY

Insufficient host memory to satisfy call.

enumerator CTL_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

Insufficient device memory to satisfy call.

enumerator CTL_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

Access denied due to permission level.

enumerator CTL_RESULT_ERROR_NOT_AVAILABLE

Resource was removed.

enumerator CTL_RESULT_ERROR_UNINITIALIZED

Library not initialized.

enumerator CTL_RESULT_ERROR_UNSUPPORTED_VERSION

Generic error code for unsupported versions.

enumerator CTL_RESULT_ERROR_UNSUPPORTED_FEATURE

Generic error code for unsupported features.

enumerator CTL_RESULT_ERROR_INVALID_ARGUMENT

Generic error code for invalid arguments.

enumerator CTL_RESULT_ERROR_INVALID_API_HANDLE

API handle in invalid.

enumerator CTL_RESULT_ERROR_INVALID_NULL_HANDLE

Handle argument is not valid.

enumerator CTL_RESULT_ERROR_INVALID_NULL_POINTER

Pointer argument may not be nullptr.

enumerator CTL_RESULT_ERROR_INVALID_SIZE

Size argument is invalid (e.g., must not be zero)

enumerator CTL_RESULT_ERROR_UNSUPPORTED_SIZE

Size argument is not supported by the device (e.g., too large)

enumerator CTL_RESULT_ERROR_UNSUPPORTED_IMAGE_FORMAT

Image format is not supported by the device.

enumerator CTL_RESULT_ERROR_DATA_READ

Data read error.

enumerator CTL_RESULT_ERROR_DATA_WRITE

Data write error.

enumerator CTL_RESULT_ERROR_DATA_NOT_FOUND

Data not found error.

enumerator CTL_RESULT_ERROR_NOT_IMPLEMENTED

Function not implemented.

enumerator CTL_RESULT_ERROR_OS_CALL

Operating system call failure.

enumerator CTL_RESULT_ERROR_KMD_CALL

Kernel mode driver call failure.

enumerator CTL_RESULT_ERROR_UNLOAD

Library unload failure.

enumerator CTL_RESULT_ERROR_ZE_LOADER

Level0 loader not found.

enumerator CTL_RESULT_ERROR_INVALID_OPERATION_TYPE

Invalid operation type.

enumerator CTL_RESULT_ERROR_NULL_OS_INTERFACE

Null OS interface.

enumerator CTL_RESULT_ERROR_NULL_OS_ADAPATER_HANDLE

Null OS adapter handle.

enumerator CTL_RESULT_ERROR_NULL_OS_DISPLAY_OUTPUT_HANDLE

Null display output handle.

enumerator CTL_RESULT_ERROR_WAIT_TIMEOUT

Timeout in Wait function.

enumerator CTL_RESULT_ERROR_PERSISTANCE_NOT_SUPPORTED

Persistance not supported.

enumerator CTL_RESULT_ERROR_PLATFORM_NOT_SUPPORTED

Platform not supported.

enumerator CTL_RESULT_ERROR_UNKNOWN_APPLICATION_UID

Unknown Appplicaion UID in Initialization call.

enumerator CTL_RESULT_ERROR_INVALID_ENUMERATION

The enum is not valid.

enumerator CTL_RESULT_ERROR_FILE_DELETE

Error in file delete operation.

enumerator CTL_RESULT_ERROR_RESET_DEVICE_REQUIRED

The device requires a reset.

enumerator CTL_RESULT_ERROR_FULL_REBOOT_REQUIRED

The device requires a full reboot.

enumerator CTL_RESULT_ERROR_LOAD

Library load failure.

enumerator CTL_RESULT_ERROR_UNKNOWN

Unknown or internal error.

enumerator CTL_RESULT_ERROR_RETRY_OPERATION

Operation failed, retry previous operation again.

enumerator CTL_RESULT_ERROR_GENERIC_END

“Generic error code end value, not to be used

”

enumerator CTL_RESULT_ERROR_CORE_START

Core error code starting value, not to be used.

enumerator CTL_RESULT_ERROR_CORE_OVERCLOCK_NOT_SUPPORTED

The Overclock is not supported.

enumerator CTL_RESULT_ERROR_CORE_OVERCLOCK_VOLTAGE_OUTSIDE_RANGE

The Voltage exceeds the acceptable min/max.

enumerator CTL_RESULT_ERROR_CORE_OVERCLOCK_FREQUENCY_OUTSIDE_RANGE

The Frequency exceeds the acceptable min/max.

enumerator CTL_RESULT_ERROR_CORE_OVERCLOCK_POWER_OUTSIDE_RANGE

The Power exceeds the acceptable min/max.

enumerator CTL_RESULT_ERROR_CORE_OVERCLOCK_TEMPERATURE_OUTSIDE_RANGE

The Temperature exceeds the acceptable min/max.

enumerator CTL_RESULT_ERROR_CORE_OVERCLOCK_IN_VOLTAGE_LOCKED_MODE

The Overclock is in voltage locked mode.

enumerator CTL_RESULT_ERROR_CORE_OVERCLOCK_RESET_REQUIRED

It indicates that the requested change will not be applied until the device is reset.

enumerator CTL_RESULT_ERROR_CORE_OVERCLOCK_WAIVER_NOT_SET

The $OverclockWaiverSet function has not been called.

enumerator CTL_RESULT_ERROR_CORE_OVERCLOCK_DEPRECATED_API

The error indicates to switch to newer API version if applicable.

enumerator CTL_RESULT_ERROR_CORE_END

“Core error code end value, not to be used

”

enumerator CTL_RESULT_ERROR_3D_START

3D error code starting value, not to be used

enumerator CTL_RESULT_ERROR_3D_END

“3D error code end value, not to be used

”

enumerator CTL_RESULT_ERROR_MEDIA_START

Media error code starting value, not to be used.

enumerator CTL_RESULT_ERROR_MEDIA_END

“Media error code end value, not to be used

”

enumerator CTL_RESULT_ERROR_DISPLAY_START

Display error code starting value, not to be used.

enumerator CTL_RESULT_ERROR_INVALID_AUX_ACCESS_FLAG

Invalid flag for Aux access.

enumerator CTL_RESULT_ERROR_INVALID_SHARPNESS_FILTER_FLAG

Invalid flag for Sharpness.

enumerator CTL_RESULT_ERROR_DISPLAY_NOT_ATTACHED

Error for Display not attached.

enumerator CTL_RESULT_ERROR_DISPLAY_NOT_ACTIVE

Error for display attached but not active.

enumerator CTL_RESULT_ERROR_INVALID_POWERFEATURE_OPTIMIZATION_FLAG

Error for invalid power optimization flag.

enumerator CTL_RESULT_ERROR_INVALID_POWERSOURCE_TYPE_FOR_DPST

DPST is supported only in DC Mode.

enumerator CTL_RESULT_ERROR_INVALID_PIXTX_GET_CONFIG_QUERY_TYPE

Invalid query type for pixel transformation get configuration.

enumerator CTL_RESULT_ERROR_INVALID_PIXTX_SET_CONFIG_OPERATION_TYPE

Invalid operation type for pixel transformation set configuration.

enumerator CTL_RESULT_ERROR_INVALID_SET_CONFIG_NUMBER_OF_SAMPLES

Invalid number of samples for pixel transformation set configuration.

enumerator CTL_RESULT_ERROR_INVALID_PIXTX_BLOCK_ID

Invalid block id for pixel transformation.

enumerator CTL_RESULT_ERROR_INVALID_PIXTX_BLOCK_TYPE

Invalid block type for pixel transformation.

enumerator CTL_RESULT_ERROR_INVALID_PIXTX_BLOCK_NUMBER

Invalid block number for pixel transformation.

enumerator CTL_RESULT_ERROR_INSUFFICIENT_PIXTX_BLOCK_CONFIG_MEMORY

Insufficient memery allocated for BlockConfigs.

enumerator CTL_RESULT_ERROR_3DLUT_INVALID_PIPE

Invalid pipe for 3dlut.

enumerator CTL_RESULT_ERROR_3DLUT_INVALID_DATA

Invalid 3dlut data.

enumerator CTL_RESULT_ERROR_3DLUT_NOT_SUPPORTED_IN_HDR

3dlut not supported in HDR

enumerator CTL_RESULT_ERROR_3DLUT_INVALID_OPERATION

Invalid 3dlut operation.

enumerator CTL_RESULT_ERROR_3DLUT_UNSUCCESSFUL

3dlut call unsuccessful

enumerator CTL_RESULT_ERROR_AUX_DEFER

AUX defer failure.

enumerator CTL_RESULT_ERROR_AUX_TIMEOUT

AUX timeout failure.

enumerator CTL_RESULT_ERROR_AUX_INCOMPLETE_WRITE

AUX incomplete write failure.

enumerator CTL_RESULT_ERROR_I2C_AUX_STATUS_UNKNOWN

I2C/AUX unkonown failure.

enumerator CTL_RESULT_ERROR_I2C_AUX_UNSUCCESSFUL

I2C/AUX unsuccessful.

enumerator CTL_RESULT_ERROR_LACE_INVALID_DATA_ARGUMENT_PASSED

Lace Incorrrect AggressivePercent data or LuxVsAggressive Map data passed by user.

enumerator CTL_RESULT_ERROR_EXTERNAL_DISPLAY_ATTACHED

External Display is Attached hence fail the Display Switch.

enumerator CTL_RESULT_ERROR_CUSTOM_MODE_STANDARD_CUSTOM_MODE_EXISTS

Standard custom mode exists.

enumerator CTL_RESULT_ERROR_CUSTOM_MODE_NON_CUSTOM_MATCHING_MODE_EXISTS

Non custom matching mode exists.

enumerator CTL_RESULT_ERROR_CUSTOM_MODE_INSUFFICIENT_MEMORY

Custom mode insufficent memory.

enumerator CTL_RESULT_ERROR_ADAPTER_ALREADY_LINKED

Adapter is already linked.

enumerator CTL_RESULT_ERROR_ADAPTER_NOT_IDENTICAL

Adapter is not identical for linking.

enumerator CTL_RESULT_ERROR_ADAPTER_NOT_SUPPORTED_ON_LDA_SECONDARY

Adapter is LDA Secondary, so not supporting requested operation.

enumerator CTL_RESULT_ERROR_SET_FBC_FEATURE_NOT_SUPPORTED

Set FBC Feature not supported.

enumerator CTL_RESULT_ERROR_DISPLAY_END

“Display error code end value, not to be used

”

enumerator CTL_RESULT_MAX

ctl_units_t

enum ctl_units_t

General Physical Units.

Values:

enumerator CTL_UNITS_FREQUENCY_MHZ

Type is Frequency with units in MHz.

enumerator CTL_UNITS_OPERATIONS_GTS

Type is Frequency with units in GT/s (gigatransfers per second).

enumerator CTL_UNITS_OPERATIONS_MTS

Type is Frequency with units in MT/s (megatransfers per second).

enumerator CTL_UNITS_VOLTAGE_VOLTS

Type is Voltage with units in Volts.

enumerator CTL_UNITS_POWER_WATTS

Type is Power with units in Watts.

enumerator CTL_UNITS_TEMPERATURE_CELSIUS

Type is Temperature with units in Celsius.

enumerator CTL_UNITS_ENERGY_JOULES

Type is Energy with units in Joules.

enumerator CTL_UNITS_TIME_SECONDS

Type is Time with units in Seconds.

enumerator CTL_UNITS_MEMORY_BYTES

Type is Memory with units in Bytes.

enumerator CTL_UNITS_ANGULAR_SPEED_RPM

Type is Angular Speed with units in Revolutions per Minute.

enumerator CTL_UNITS_POWER_MILLIWATTS

Type is Power with units in MilliWatts.

enumerator CTL_UNITS_PERCENT

Type is Percentage.

enumerator CTL_UNITS_MEM_SPEED_GBPS

Type is Memory Speed in Gigabyte per Seconds (Gbps)

enumerator CTL_UNITS_VOLTAGE_MILLIVOLTS

Type is Voltage with units in milliVolts.

enumerator CTL_UNITS_UNKNOWN

Type of units unknown.

enumerator CTL_UNITS_MAX

ctl_data_type_t

enum ctl_data_type_t

General Data Types.

Values:

enumerator CTL_DATA_TYPE_INT8

The data type is 8 bit signed integer.

enumerator CTL_DATA_TYPE_UINT8

The data type is 8 bit unsigned integer.

enumerator CTL_DATA_TYPE_INT16

The data type is 16 bit signed integer.

enumerator CTL_DATA_TYPE_UINT16

The data type is 16 bit unsigned integer.

enumerator CTL_DATA_TYPE_INT32

The data type is 32 bit signed integer.

enumerator CTL_DATA_TYPE_UINT32

The data type is 32 bit unsigned integer.

enumerator CTL_DATA_TYPE_INT64

The data type is 64 bit signed integer.

enumerator CTL_DATA_TYPE_UINT64

The data type is 64 bit unsigned integer.

enumerator CTL_DATA_TYPE_FLOAT

The data type is 32 bit floating point.

enumerator CTL_DATA_TYPE_DOUBLE

The data type is 64 bit floating point.

enumerator CTL_DATA_TYPE_STRING_ASCII

The data type is an array of 8 bit unsigned integers.

enumerator CTL_DATA_TYPE_STRING_UTF16

The data type is an array of 16 bit unsigned integers.

enumerator CTL_DATA_TYPE_STRING_UTF132

The data type is an array of 32 bit unsigned integers.

enumerator CTL_DATA_TYPE_UNKNOWN

The data type is unknown.

enumerator CTL_DATA_TYPE_MAX

ctl_supported_functions_flags_t

enum ctl_supported_functions_flag_t

Values:

enumerator CTL_SUPPORTED_FUNCTIONS_FLAG_DISPLAY

[out] Is Display supported

enumerator CTL_SUPPORTED_FUNCTIONS_FLAG_3D

[out] Is 3D supported

enumerator CTL_SUPPORTED_FUNCTIONS_FLAG_MEDIA

[out] Is Media supported

enumerator CTL_SUPPORTED_FUNCTIONS_FLAG_MAX

ctl_device_type_t

enum ctl_device_type_t

DeviceType.

Values:

enumerator CTL_DEVICE_TYPE_GRAPHICS

Graphics Device type.

enumerator CTL_DEVICE_TYPE_SYSTEM

System Device type.

enumerator CTL_DEVICE_TYPE_MAX

ctl_adapter_properties_flags_t

enum ctl_adapter_properties_flag_t

Values:

enumerator CTL_ADAPTER_PROPERTIES_FLAG_INTEGRATED

[out] Is Integrated Graphics adapter

enumerator CTL_ADAPTER_PROPERTIES_FLAG_LDA_PRIMARY

[out] Is Primary (Lead) adapter in a Linked Display Adapter (LDA) chain

enumerator CTL_ADAPTER_PROPERTIES_FLAG_LDA_SECONDARY

[out] Is Secondary (Linked) adapter in a Linked Display Adapter (LDA) chain

enumerator CTL_ADAPTER_PROPERTIES_FLAG_MAX

ctl_operation_type_t

enum ctl_operation_type_t

OperationType.

Values:

enumerator CTL_OPERATION_TYPE_READ

Read operation.

enumerator CTL_OPERATION_TYPE_WRITE

Write operation.

enumerator CTL_OPERATION_TYPE_MAX

ctl_property_type_flags_t

enum ctl_property_type_flag_t

Values:

enumerator CTL_PROPERTY_TYPE_FLAG_DISPLAY

Display type. Supported scenarios: Sharpness/gamma/CSC.

enumerator CTL_PROPERTY_TYPE_FLAG_3D

3D type. Supported scenarios: All set calls via IGCL’s 3D APIs

enumerator CTL_PROPERTY_TYPE_FLAG_MEDIA

Media type. Supported scenarios: All set calls via IGCL’s media APIs.

enumerator CTL_PROPERTY_TYPE_FLAG_CORE

For future: Core graphic event types like clocking, frequency etc.

enumerator CTL_PROPERTY_TYPE_FLAG_MAX

ctl_display_orientation_t

enum ctl_display_orientation_t

Display orientation (rotation)

Values:

enumerator CTL_DISPLAY_ORIENTATION_0

0 Degree

enumerator CTL_DISPLAY_ORIENTATION_90

90 Degree

enumerator CTL_DISPLAY_ORIENTATION_180

180 Degree

enumerator CTL_DISPLAY_ORIENTATION_270

270 Degree

enumerator CTL_DISPLAY_ORIENTATION_MAX

Common Structures

ctl_base_interface_t

struct ctl_base_interface_t

Base for all properties types.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_property_range_info_t

struct ctl_property_range_info_t

Property range details, a generic struct to hold min/max/step size information of various feature properties.

Public Members

float min_possible_value

[out] Minimum possible value

float max_possible_value

[out] Maximum possible value

float step_size

[out] Step size possible

float default_value

[out] Default value

ctl_property_range_info_int_t

struct ctl_property_range_info_int_t

Property range details of integer type, a generic struct to hold min/max/step size information of various feature properties.

Public Members

int32_t min_possible_value

[out] Minimum possible value

int32_t max_possible_value

[out] Maximum possible value

int32_t step_size

[out] Step size possible

int32_t default_value

[out] Default value

ctl_property_range_info_uint_t

struct ctl_property_range_info_uint_t

Property range details of unsigned integer type, a generic struct to hold min/max/step size information of various feature properties.

Public Members

uint32_t min_possible_value

[out] Minimum possible value

uint32_t max_possible_value

[out] Maximum possible value

uint32_t step_size

[out] Step size possible

uint32_t default_value

[out] Default value

ctl_property_info_boolean_t

struct ctl_property_info_boolean_t

Bool feature details.

Public Members

bool DefaultState

[out] Default state

ctl_property_boolean_t

struct ctl_property_boolean_t

Bool feature for get/set.

Public Members

bool Enable

[in,out] Enable

ctl_property_info_enum_t

struct ctl_property_info_enum_t

Enumeration feature details.

Public Members

uint64_t SupportedTypes

[out] Supported possible values represented as a bitmask

uint32_t DefaultType

[out] Default type

ctl_property_enum_t

struct ctl_property_enum_t

Enumeration feature for get/set.

Public Members

uint32_t EnableType

[in,out] Enable with specific type

ctl_property_info_float_t

struct ctl_property_info_float_t

Float feature details.

Public Members

bool DefaultEnable

[in,out] DefaultEnable

ctl_property_range_info_t RangeInfo

[out] Min/max/default/step details

ctl_property_float_t

struct ctl_property_float_t

Float feature for get/set.

Public Members

bool Enable

[in,out] Enable

float Value

[in,out] Value

ctl_property_info_int_t

struct ctl_property_info_int_t

Int32 feature details.

Public Members

bool DefaultEnable

[in,out] DefaultEnable

ctl_property_range_info_int_t RangeInfo

[out] Min/max/default/step details

ctl_property_int_t

struct ctl_property_int_t

Int32 feature for get/set.

Public Members

bool Enable

[in,out] Enable

int32_t Value

[in,out] Value

ctl_property_info_uint_t

struct ctl_property_info_uint_t

Int32 feature details.

Public Members

bool DefaultEnable

[in,out] DefaultEnable

ctl_property_range_info_uint_t RangeInfo

[out] Min/max/default/step details

ctl_property_uint_t

struct ctl_property_uint_t

Int32 feature for get/set.

Public Members

bool Enable

[in,out] Enable

uint32_t Value

[in,out] Value

ctl_property_info_t

union ctl_property_info_t
#include <igcl_api.h>

Feature element details, union of bool/float/enum property_info structs. Used for feature specific capability check.

Public Members

ctl_property_info_boolean_t BoolType

[in,out] Boolean type fields

ctl_property_info_float_t FloatType

[in,out] Float type fields

ctl_property_info_int_t IntType

[in,out] Int type fields

ctl_property_info_enum_t EnumType

[in,out] Enum type fields

ctl_property_info_uint_t UIntType

[in,out] Unsigned Int type fields

ctl_property_t

union ctl_property_t
#include <igcl_api.h>

Feature element details, union of bool/float/enum property structs. Used for get/set calls.

Public Members

ctl_property_boolean_t BoolType

[in,out] Boolean type fields

ctl_property_float_t FloatType

[in,out] Float type fields

ctl_property_int_t IntType

[in,out] Int type fields

ctl_property_enum_t EnumType

[in,out] Enum type fields

ctl_property_uint_t UIntType

[in,out] Unsigned Int type fields

ctl_data_value_t

union ctl_data_value_t
#include <igcl_api.h>

Union for Generic Data.

  • The telemetry data items could be of different types.

  • Refer to ctl_data_type_t to find the current type.

Public Members

int8_t data8

[out] The data type is 8 bit signed integer.

uint8_t datau8

[out] The data type is 8 bit unsigned integer.

int16_t data16

[out] The data type is 16 bit signed integer.

uint16_t datau16

[out] The data type is 16 bit unsigned integer.

int32_t data32

[out] The data type is 32 bit signed integer.

uint32_t datau32

[out] The data type is 32 bit unsigned integer.

int64_t data64

[out] The data type is 64 bit signed integer.

uint64_t datau64

[out] The data type is 64 bit unsigned integer.

float datafloat

[out] The data type is 32 bit floating point.

double datadouble

[out] The data type is 64 bit floating point.

ctl_base_properties_t

struct ctl_base_properties_t

Base for all properties types.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_application_id_t

struct ctl_application_id_t

Application Unique ID.

Public Members

uint32_t Data1

[in] Data1

uint16_t Data2

[in] Data2

uint16_t Data3

[in] Data3

uint8_t Data4[8]

[in] Data4

ctl_init_args_t

struct ctl_init_args_t

Init arguments.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_version_info_t AppVersion

[in][release] App’s IGCL version

ctl_init_flags_t flags

[in][release] Caller version

ctl_version_info_t SupportedVersion

[out][release] IGCL implementation version

ctl_application_id_t ApplicationUID

[in] Application Provided Unique ID.Application can pass all 0’s as the default ID

ctl_reserved_args_t

struct ctl_reserved_args_t

Reserved struct.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

void *pSpecialArg

[in] Reserved struct

uint32_t ArgSize

[in] struct size

ctl_reserved_args_base_t

struct ctl_reserved_args_base_t

Reserved base struct.

Public Members

ctl_application_id_t ReservedFuncID

[in] Unique ID for reserved/special function

ctl_unlock_capability_t

struct ctl_unlock_capability_t

Reserved - Unlock function capability.

Public Members

ctl_application_id_t ReservedFuncID

[in] Unique ID for reserved/special function

ctl_application_id_t UnlockCapsID

[in] Unique ID to unlock a specific function

ctl_runtime_path_args_t

struct ctl_runtime_path_args_t

Used by loader like modules to specify runtime implementation details.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_application_id_t UnlockID

[in] Unique ID for reserved/special function

wchar_t *pRuntimePath

[in] Path to runtime DLL

uint16_t DeviceID

[in] Device ID of interest to caller. pRuntimePath should not be NULL.

uint8_t RevID

[in] Revision ID of interest to caller. pRuntimePath should not be NULL.

ctl_firmware_version_t

struct ctl_firmware_version_t

Firmware version.

Public Members

uint64_t major_version

[out] Major version

uint64_t minor_version

[out] Minor version

uint64_t build_number

[out] Build number

ctl_adapter_bdf_t

struct ctl_adapter_bdf_t

Adapter Pci Bus, Device, Function.

Public Members

uint8_t bus

[out] PCI Bus Number

uint8_t device

[out] PCI device number

uint8_t function

[out] PCI function

ctl_device_adapter_properties_t

struct ctl_device_adapter_properties_t

Device Adapter properties.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

void *pDeviceID

[in,out] OS specific Device ID

uint32_t device_id_size

[in] size of the device ID

ctl_device_type_t device_type

[out] Device Type

ctl_supported_functions_flags_t supported_subfunction_flags

[out] Supported functions

uint64_t driver_version

[out] Driver version

ctl_firmware_version_t firmware_version

[out] Firmware version

uint32_t pci_vendor_id

[out] PCI Vendor ID

uint32_t pci_device_id

[out] PCI Device ID

uint32_t rev_id

[out] PCI Revision ID

uint32_t num_eus_per_sub_slice

[out] Number of EUs per sub-slice

uint32_t num_sub_slices_per_slice

[out] Number of sub-slices per slice

uint32_t num_slices

[out] Number of slices

char name[CTL_MAX_DEVICE_NAME_LEN]

[out] Device name

ctl_adapter_properties_flags_t graphics_adapter_properties

[out] Graphics Adapter Properties

uint32_t Frequency

[out] Clock frequency for this device. Supported only for Version > 0

uint16_t pci_subsys_id

[out] PCI SubSys ID, Supported only for Version > 1

uint16_t pci_subsys_vendor_id

[out] PCI SubSys Vendor ID, Supported only for Version > 1

ctl_adapter_bdf_t adapter_bdf

[out] Pci Bus, Device, Function. Supported only for Version > 1

char reserved[CTL_MAX_RESERVED_SIZE]

[out] Reserved

ctl_generic_void_datatype_t

struct ctl_generic_void_datatype_t

Generic Structure for Void* datatypes.

Public Members

void *pData

[in,out]void pointer to memory

uint32_t size

[in,out]size of the allocated memory

ctl_revision_datatype_t

struct ctl_revision_datatype_t

Generic Structure for Revision datatypes.

Public Members

uint8_t major_version

[in,out]Major Version

uint8_t minor_version

[in,out]Minor Version

uint8_t revision_version

[in,out]Revision Version

ctl_wait_property_change_args_t

struct ctl_wait_property_change_args_t

Arguments related to wait for a property change function.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_property_type_flags_t PropertyType

[in] Type of the property

uint32_t TimeOutMilliSec

[in][release] Time-out interval in milliseconds. Specify 0xFFFFFFFF if time-out is not desired

uint32_t EventMiscFlags

[in][release] Event flags for future use

void *pReserved

[in][release] Reserved for future use

uint64_t ReservedOutFlags

[out] Reserved out argument for future use

ctl_rect_t

struct ctl_rect_t

Rectangle.

Public Members

int32_t Left

[in,out] Left

int32_t Top

[in,out] Top

int32_t Right

[in,out] Right

int32_t Bottom

[in,out] Bottom

_3d

_3d Functions

ctlGetSupported3DCapabilities

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetSupported3DCapabilities(ctl_device_adapter_handle_t hDAhandle, ctl_3d_feature_caps_t *pFeatureCaps)

Get 3D capabilities.

  • The application gets 3D properties

Parameters:

  • hDAhandle – [in][release] Handle to display adapter

  • pFeatureCaps – [in,out][release] 3D properties

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pFeatureCaps

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetSet3DFeature

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetSet3DFeature(ctl_device_adapter_handle_t hDAhandle, ctl_3d_feature_getset_t *pFeature)

Get/Set 3D feature.

  • 3D feature details

Parameters:

  • hDAhandle – [in][release] Handle to display adapter

  • pFeature – [in][release] 3D feature get/set parameter

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pFeature

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

_3d Enums

ctl_3d_feature_t

enum ctl_3d_feature_t

Feature type.

Values:

enumerator CTL_3D_FEATURE_FRAME_PACING

Frame pacing. Contains generic enum type fields.

enumerator CTL_3D_FEATURE_ENDURANCE_GAMING

Endurance gaming. Contains generic integer type fields. Value will be interpreted as the max FPS to be used when in DC mode globally or per application.

enumerator CTL_3D_FEATURE_FRAME_LIMIT

Frame limit for games. Contains generic integer type fields. Value will be interpreted as the max FPS to be used independent of system power state.

enumerator CTL_3D_FEATURE_ANISOTROPIC

ANISOTROPIC. Contains generic enum type fields.

enumerator CTL_3D_FEATURE_CMAA

CMAA. Contains generic enum type fields.

enumerator CTL_3D_FEATURE_TEXTURE_FILTERING_QUALITY

Texture filtering quality. Contains generic enum type fields.

enumerator CTL_3D_FEATURE_ADAPTIVE_TESSELLATION

Adaptive tessellation quality. Contains generic integer type fields.

enumerator CTL_3D_FEATURE_SHARPENING_FILTER

Sharpening Filter. Contains generic integer type fields.

enumerator CTL_3D_FEATURE_MSAA

Msaa. Contains generic enum type fields.

enumerator CTL_3D_FEATURE_GAMING_FLIP_MODES

Various Gaming flip modes like speed frame, smooth sync & force async flip. Contains generic enum type fields.

enumerator CTL_3D_FEATURE_ADAPTIVE_SYNC_PLUS

Adaptive sync plus. Refer custom field ctl_adaptivesync_caps_t & ctl_adaptivesync_getset_t.

enumerator CTL_3D_FEATURE_APP_PROFILES

Game Compatibility & Performance Profiles. Refer custom field ctl_3d_app_profiles_caps_t & ctl_3d_app_profiles_t.

enumerator CTL_3D_FEATURE_APP_PROFILE_DETAILS

Game Profile Customization. Refer custom field ctl_3d_tier_details_t.

enumerator CTL_3D_FEATURE_EMULATED_TYPED_64BIT_ATOMICS

Emulated Typed 64bit Atomics support in DG2.

enumerator CTL_3D_FEATURE_VRR_WINDOWED_BLT

VRR windowed blt. Control VRR for windowed mode game.

enumerator CTL_3D_FEATURE_GLOBAL_OR_PER_APP

Set global settings or per application settings.

enumerator CTL_3D_FEATURE_MAX

ctl_3d_feature_misc_flags_t

enum ctl_3d_feature_misc_flag_t

Values:

enumerator CTL_3D_FEATURE_MISC_FLAG_DX11

Feature supported on DX11.

enumerator CTL_3D_FEATURE_MISC_FLAG_DX12

Feature supported on DX12.

enumerator CTL_3D_FEATURE_MISC_FLAG_VULKAN

Feature supported on VULKAN.

enumerator CTL_3D_FEATURE_MISC_FLAG_LIVE_CHANGE

User can change feature live without restarting the game.

enumerator CTL_3D_FEATURE_MISC_FLAG_MAX

ctl_3d_anisotropic_types_t

enum ctl_3d_anisotropic_types_t

Anisotropic values possible.

Values:

enumerator CTL_3D_ANISOTROPIC_TYPES_APP_CHOICE

Application choice.

enumerator CTL_3D_ANISOTROPIC_TYPES_2X

2X

enumerator CTL_3D_ANISOTROPIC_TYPES_4X

4X

enumerator CTL_3D_ANISOTROPIC_TYPES_8X

8X

enumerator CTL_3D_ANISOTROPIC_TYPES_16X

16X

enumerator CTL_3D_ANISOTROPIC_TYPES_MAX

ctl_3d_texture_filtering_quality_types_t

enum ctl_3d_texture_filtering_quality_types_t

Texture filtering values possible.

Values:

enumerator CTL_3D_TEXTURE_FILTERING_QUALITY_TYPES_PERFORMANCE

Performance.

enumerator CTL_3D_TEXTURE_FILTERING_QUALITY_TYPES_BALANCED

Balanced.

enumerator CTL_3D_TEXTURE_FILTERING_QUALITY_TYPES_QUALITY

Quality.

enumerator CTL_3D_TEXTURE_FILTERING_QUALITY_TYPES_MAX

ctl_3d_frame_pacing_types_t

enum ctl_3d_frame_pacing_types_t

Frame pacing values possible.

Values:

enumerator CTL_3D_FRAME_PACING_TYPES_DISABLE

Disable.

enumerator CTL_3D_FRAME_PACING_TYPES_ENABLE_MODE_FRAME_NO_SMOOTHENING

Enable with scheduler without any frame smoothening.

enumerator CTL_3D_FRAME_PACING_TYPES_ENABLE_MODE_FRAME_MAX_SMOOTHENING

Enable with scheduler with maximum smoothness.

enumerator CTL_3D_FRAME_PACING_TYPES_ENABLE_MODE_COMPETITIVE_GAMING

Enable with scheduler in competitive gaming mode.

enumerator CTL_3D_FRAME_PACING_TYPES_MAX

ctl_3d_endurance_gaming_control_t

enum ctl_3d_endurance_gaming_control_t

Endurance Gaming control possible.

Values:

enumerator CTL_3D_ENDURANCE_GAMING_CONTROL_TURN_OFF

Endurance Gaming disable.

enumerator CTL_3D_ENDURANCE_GAMING_CONTROL_TURN_ON

Endurance Gaming enable.

enumerator CTL_3D_ENDURANCE_GAMING_CONTROL_AUTO

Endurance Gaming auto.

enumerator CTL_3D_ENDURANCE_GAMING_CONTROL_MAX

ctl_3d_endurance_gaming_mode_t

enum ctl_3d_endurance_gaming_mode_t

Endurance Gaming modes possible.

Values:

enumerator CTL_3D_ENDURANCE_GAMING_MODE_BETTER_PERFORMANCE

Endurance Gaming better performance mode.

enumerator CTL_3D_ENDURANCE_GAMING_MODE_BALANCED

Endurance Gaming balanced mode.

enumerator CTL_3D_ENDURANCE_GAMING_MODE_MAXIMUM_BATTERY

Endurance Gaming maximum battery mode.

enumerator CTL_3D_ENDURANCE_GAMING_MODE_MAX

ctl_3d_cmaa_types_t

enum ctl_3d_cmaa_types_t

Cmaa values possible.

Values:

enumerator CTL_3D_CMAA_TYPES_TURN_OFF

Turn off.

enumerator CTL_3D_CMAA_TYPES_OVERRIDE_MSAA

Override MSAA.

enumerator CTL_3D_CMAA_TYPES_ENHANCE_APPLICATION

Enhance Application.

enumerator CTL_3D_CMAA_TYPES_MAX

ctl_3d_adaptive_tessellation_types_t

enum ctl_3d_adaptive_tessellation_types_t

Adaptive Tessellation.

Values:

enumerator CTL_3D_ADAPTIVE_TESSELLATION_TYPES_TURN_OFF

Turn off.

enumerator CTL_3D_ADAPTIVE_TESSELLATION_TYPES_TURN_ON

Turn on.

enumerator CTL_3D_ADAPTIVE_TESSELLATION_TYPES_MAX

ctl_3d_sharpening_filter_types_t

enum ctl_3d_sharpening_filter_types_t

Sharpening filter values possible.

Values:

enumerator CTL_3D_SHARPENING_FILTER_TYPES_TURN_OFF

Turn off.

enumerator CTL_3D_SHARPENING_FILTER_TYPES_TURN_ON

Turn on.

enumerator CTL_3D_SHARPENING_FILTER_TYPES_MAX

ctl_3d_msaa_types_t

enum ctl_3d_msaa_types_t

MSAA values possible.

Values:

enumerator CTL_3D_MSAA_TYPES_APP_CHOICE

Application choice.

enumerator CTL_3D_MSAA_TYPES_DISABLED

Disabled. MSAA count 1.

enumerator CTL_3D_MSAA_TYPES_2X

2X

enumerator CTL_3D_MSAA_TYPES_4X

4X

enumerator CTL_3D_MSAA_TYPES_8X

8X

enumerator CTL_3D_MSAA_TYPES_16X

16X

enumerator CTL_3D_MSAA_TYPES_MAX

ctl_gaming_flip_mode_flags_t

enum ctl_gaming_flip_mode_flag_t

Values:

enumerator CTL_GAMING_FLIP_MODE_FLAG_APPLICATION_DEFAULT

Application Default.

enumerator CTL_GAMING_FLIP_MODE_FLAG_VSYNC_OFF

Convert all sync flips to async on the next possible scanline.

enumerator CTL_GAMING_FLIP_MODE_FLAG_VSYNC_ON

Convert all async flips to sync flips.

enumerator CTL_GAMING_FLIP_MODE_FLAG_SMOOTH_SYNC

Reduce tearing effect with async flips.

enumerator CTL_GAMING_FLIP_MODE_FLAG_SPEED_FRAME

Application unaware triple buffering.

enumerator CTL_GAMING_FLIP_MODE_FLAG_CAPPED_FPS

Limit the game FPS to panel RR.

enumerator CTL_GAMING_FLIP_MODE_FLAG_MAX

ctl_3d_tier_type_flags_t

enum ctl_3d_tier_type_flag_t

Values:

enumerator CTL_3D_TIER_TYPE_FLAG_COMPATIBILITY

Compatibility Tier.

enumerator CTL_3D_TIER_TYPE_FLAG_PERFORMANCE

Performance Tier.

enumerator CTL_3D_TIER_TYPE_FLAG_MAX

ctl_3d_tier_profile_flags_t

enum ctl_3d_tier_profile_flag_t

Values:

enumerator CTL_3D_TIER_PROFILE_FLAG_TIER_1

Tier 1 Profile.

enumerator CTL_3D_TIER_PROFILE_FLAG_TIER_2

Tier 2 Profile.

enumerator CTL_3D_TIER_PROFILE_FLAG_TIER_RECOMMENDED

Recommended Tier Profile. If set other tier values shouldn’t be set.

enumerator CTL_3D_TIER_PROFILE_FLAG_MAX

ctl_emulated_typed_64bit_atomics_types_t

enum ctl_emulated_typed_64bit_atomics_types_t

Emulated Typed 64bit Atomics.

Values:

enumerator CTL_EMULATED_TYPED_64BIT_ATOMICS_TYPES_DEFAULT

Default settings is based on workload/driver decision.

enumerator CTL_EMULATED_TYPED_64BIT_ATOMICS_TYPES_TURN_ON

Force Turn on.

enumerator CTL_EMULATED_TYPED_64BIT_ATOMICS_TYPES_TURN_OFF

Force Turn off.

enumerator CTL_EMULATED_TYPED_64BIT_ATOMICS_TYPES_MAX

ctl_3d_vrr_windowed_blt_reserved_t

enum ctl_3d_vrr_windowed_blt_reserved_t

VRR windowed BLT control possible. Reserved functionality.

Values:

enumerator CTL_3D_VRR_WINDOWED_BLT_RESERVED_AUTO

VRR windowed BLT auto.

enumerator CTL_3D_VRR_WINDOWED_BLT_RESERVED_TURN_ON

VRR windowed BLT enable.

enumerator CTL_3D_VRR_WINDOWED_BLT_RESERVED_TURN_OFF

VRR windowed BLT disable.

enumerator CTL_3D_VRR_WINDOWED_BLT_RESERVED_MAX

ctl_3d_global_or_per_app_types_t

enum ctl_3d_global_or_per_app_types_t

Global or per app values possible.

Values:

enumerator CTL_3D_GLOBAL_OR_PER_APP_TYPES_NONE

none

enumerator CTL_3D_GLOBAL_OR_PER_APP_TYPES_PER_APP

Opt for per app settings.

enumerator CTL_3D_GLOBAL_OR_PER_APP_TYPES_GLOBAL

Opt for global settings.

enumerator CTL_3D_GLOBAL_OR_PER_APP_TYPES_MAX

_3d Structures

ctl_endurance_gaming_caps_t

struct ctl_endurance_gaming_caps_t

Endurance Gaming caps.

Public Members

ctl_property_info_enum_t EGControlCaps

[out] Endurance Gaming control capability

ctl_property_info_enum_t EGModeCaps

[out] Endurance Gaming mode capability

ctl_endurance_gaming_t

struct ctl_endurance_gaming_t

Endurance Gaming Get/Set.

Public Members

ctl_3d_endurance_gaming_control_t EGControl

[in,out] Endurance Gaming control - Off/On/Auto

ctl_3d_endurance_gaming_mode_t EGMode

[in,out] Endurance Gaming mode - Better Performance/Balanced/Maximum Battery

ctl_endurance_gaming2_t

struct ctl_endurance_gaming2_t

Endurance Gaming version2 Get/Set.

Public Members

ctl_3d_endurance_gaming_control_t EGControl

[in,out] Endurance Gaming control - Off/On/Auto

ctl_3d_endurance_gaming_mode_t EGMode

[in,out] Endurance Gaming mode - Better Performance/Balanced/Maximum Battery

bool IsFPRequired

[out] Is frame pacing required, dynamic state

double TargetFPS

[out] Target FPS for frame pacing

double RefreshRate

[out] Refresh rate used to calculate target fps

uint32_t Reserved[4]

[out] Reserved fields

ctl_adaptivesync_caps_t

struct ctl_adaptivesync_caps_t

Adaptive sync plus caps.

Public Members

bool AdaptiveBalanceSupported

[out] Adaptive balance supported

ctl_property_info_float_t AdaptiveBalanceStrengthCaps

[out] Strength of adaptive balance algorithm - min/max/steps/default

ctl_adaptivesync_getset_t

struct ctl_adaptivesync_getset_t

Adaptive sync plus.

Public Members

bool AdaptiveSync

[in,out] Adaptive sync. Note that in Windows, OS controls state of adaptive sync and which game gets the feature using it’s own policies

bool AdaptiveBalance

[in,out] Adaptive balance

bool AllowAsyncForHighFPS

[in,out] Allow async flips when FPS is higher than max refresh rate of the panel

float AdaptiveBalanceStrength

[in,out] Adaptive balance strength

ctl_3d_app_profiles_caps_t

struct ctl_3d_app_profiles_caps_t

Game Profile Capabilities. Typically these remain the same across games.

Public Members

ctl_3d_tier_type_flags_t SupportedTierTypes

[out] Tier of interest for capability check

uint64_t Reserved

[in,out] Reserved for future

ctl_3d_app_profiles_t

struct ctl_3d_app_profiles_t

Game Profile tiers.

Public Members

ctl_3d_tier_type_flag_t TierType

[in] Tier type

ctl_3d_tier_profile_flags_t SupportedTierProfiles

[out] Supported tier profiles bitmask

ctl_3d_tier_profile_flags_t DefaultEnabledTierProfiles

[out] Default tiers which driver will enable if there is no user specific setting for global or per application

ctl_3d_tier_profile_flags_t CustomizationSupportedTierProfiles

[out] Tiers supporting customization - reserved for future

ctl_3d_tier_profile_flags_t EnabledTierProfiles

[in,out] Tier profile(s) to be enabled/disabled in the case of a set call. For a get call this will return the currently enabled tiers

ctl_3d_tier_profile_flags_t CustomizationEnabledTierProfiles

[in,out] Tier profile(s) which are customized. Caller shall call ctl_3d_tier_details_t to get specifics if any.

uint64_t Reserved

[in,out] Reserved for future

ctl_3d_tier_details_t

struct ctl_3d_tier_details_t

Game Profile tiers details.

Public Members

ctl_3d_tier_type_flag_t TierType

[in] Tier type

ctl_3d_tier_profile_flag_t TierProfile

[in] Tier profile(s) for get/set details

uint64_t Reserved[4]

[in,out] Reserved for future

ctl_3d_feature_details_t

struct ctl_3d_feature_details_t

3D feature capability details which will have range/supported and default values

Public Members

ctl_3d_feature_t FeatureType

[out] 3D feature type

ctl_property_value_type_t ValueType

[out] Type of value

ctl_property_info_t Value

[out] Union of various type of values for 3D features. For enum types this can be anisotropic/frame pacing etc. This member is valid iff ValueType is not CTL_PROPERTY_VALUE_TYPE_CUSTOM

int32_t CustomValueSize

[in] CustomValue buffer size. Typically for a feature requiring custom struct, caller will know of it upfront and can provide the right size info here

void *pCustomValue

[in,out] Pointer to a custom structure. Caller should allocate this buffer with known custom feature structure size. This member is valid iff ValueType is CTL_PROPERTY_VALUE_TYPE_CUSTOM

bool PerAppSupport

[out] Flag indicating whether the feature is supported per application or not

int64_t ConflictingFeatures

[out] Mask of ctl_3d_feature_t values which can’t be enabled along with the mentioned FeatureType. If this is 0, it meant the feature doesn’t have any conflicts with other features

int16_t FeatureMiscSupport

[out] 3D Feature Miscellaneous support flags. This will be based on ctl_3d_feature_misc_flags_t

int16_t Reserved

[out] Reserved

int16_t Reserved1

[out] Reserved

int16_t Reserved2

[out] Reserved

ctl_3d_feature_caps_t

struct ctl_3d_feature_caps_t

3D feature which are controllable

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint32_t NumSupportedFeatures

[in,out] Number of elements in supported features array

ctl_3d_feature_details_t *pFeatureDetails

[in,out] Array of feature details

ctl_3d_feature_getset_t

struct ctl_3d_feature_getset_t

3D feature for get/set

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_3d_feature_t FeatureType

[in] Features interested in

char *ApplicationName

[in] Application name for which the property type is applicable. If this is an empty string then this will get/set global settings for the given adapter. Note that this should contain only the name of the application and not the system specific path

int8_t ApplicationNameLength

[in] Length of ApplicationName string

bool bSet

[in] Set this if it’s a set call

ctl_property_value_type_t ValueType

[in] Type of value. Caller has to ensure it provides the right value type which decides how one read the union structure below

ctl_property_t Value

[in,out] Union of various type of values for 3D features. For enum types this can be anisotropic/frame pacing etc. This member is valid iff ValueType is not CTL_PROPERTY_VALUE_TYPE_CUSTOM

int32_t CustomValueSize

[in] CustomValue buffer size. Typically for a feature requiring custom struct, caller will know of it upfront and cn provide the right size info here

void *pCustomValue

[in,out] Pointer to a custom structure. Caller should allocate this buffer with known custom feature structure size. This member is valid iff ValueType is CTL_PROPERTY_VALUE_TYPE_CUSTOM

ctl_kmd_load_features_t

struct ctl_kmd_load_features_t

Load KMD gaming features. Restricted function.

Public Members

ctl_application_id_t ReservedFuncID

[in] Unique ID for reserved/special function

bool bLoad

[in] If set, will load known KMD features. If not set will reset known KMD features to default

int64_t SubsetFeatureMask

[in,out] Mask indicating the subset of KMD features within ctl_3d_feature_t values. Default of 0 indicate all KMD features

char *ApplicationName

[in] Application name for which the KMD properties are loaded for. If this is an empty string then this will load global settings for the given adapter. Note that this should contain only the name of the application and not the system specific path

int8_t ApplicationNameLength

[in] Length of ApplicationName string

int8_t CallerComponent

[in] Caller component

int64_t Reserved[4]

[in] Reserved field

Display

Display Functions

ctlCheckDriverVersion

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlCheckDriverVersion(ctl_device_adapter_handle_t hDeviceAdapter, ctl_version_info_t version_info)

Check Driver version.

  • The application checks driver version

Parameters:

  • hDeviceAdapter – [in][release] handle to control device adapter

  • version_info – [in][release] Driver version info

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceAdapter

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlEnumerateDevices

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlEnumerateDevices(ctl_api_handle_t hAPIHandle, uint32_t *pCount, ctl_device_adapter_handle_t *phDevices)

Enumerate devices.

  • The application enumerates all device adapters in the system

Parameters:

  • hAPIHandle – [in][release] Applications should pass the Control API handle returned by the CtlInit function

  • pCount – [in,out][release] pointer to the number of device instances. If count is zero, then the api will update the value with the total number of drivers available. If count is non-zero, then the api will only retrieve the number of drivers. If count is larger than the number of drivers available, then the api will update the value with the correct number of drivers available.

  • phDevices – [in,out][optional][release][range(0, *pCount)] array of driver instance handles

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hAPIHandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pCount

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlEnumerateDisplayOutputs

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlEnumerateDisplayOutputs(ctl_device_adapter_handle_t hDeviceAdapter, uint32_t *pCount, ctl_display_output_handle_t *phDisplayOutputs)

Enumerate display outputs.

  • Enumerates display output capabilities

Parameters:

  • hDeviceAdapter – [in][release] handle to control device adapter

  • pCount – [in,out][release] pointer to the number of display output instances. If count is zero, then the api will update the value with the total number of outputs available. If count is non-zero, then the api will only retrieve the number of outputs. If count is larger than the number of drivers available, then the api will update the value with the correct number of drivers available.

  • phDisplayOutputs – [in,out][optional][release][range(0, *pCount)] array of display output instance handles

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceAdapter

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pCount

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlEnumerateI2CPinPairs

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlEnumerateI2CPinPairs(ctl_device_adapter_handle_t hDeviceAdapter, uint32_t *pCount, ctl_i2c_pin_pair_handle_t *phI2cPinPairs)

Enumerate I2C Pin Pairs.

  • Returns available list of I2C Pin-Pairs on a requested adapter

Parameters:

  • hDeviceAdapter – [in][release] handle to device adapter

  • pCount – [in,out][release] pointer to the number of i2c pin-pair instances. If count is zero, then the api will update the value with the total number of i2c pin-pair instances available. If count is non-zero and matches the avaialble number of pin-pairs, then the api will only return the avaialble number of i2c pin-pair instances in phI2cPinPairs.

  • phI2cPinPairs – [out][optional][release][range(0, *pCount)] array of i2c pin pair instance handles. Need to be allocated by Caller when supplying the *pCount > 0. If Count is not equal to actual number of i2c pin-pair instances, it will return CTL_RESULT_ERROR_INVALID_SIZE.

Returns:

ctlGetDeviceProperties

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetDeviceProperties(ctl_device_adapter_handle_t hDAhandle, ctl_device_adapter_properties_t *pProperties)

Get Device Properties.

  • The application gets device properties

Parameters:

  • hDAhandle – [in][release] Handle to control device adapter

  • pProperties – [in,out][release] Query result for device properties

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pProperties

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetDisplayProperties

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetDisplayProperties(ctl_display_output_handle_t hDisplayOutput, ctl_display_properties_t *pProperties)

Get Display Properties.

  • The application gets display properties

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pProperties – [in,out][release] Query result for display properties

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDisplayOutput

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pProperties

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetAdaperDisplayEncoderProperties

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetAdaperDisplayEncoderProperties(ctl_display_output_handle_t hDisplayOutput, ctl_adapter_display_encoder_properties_t *pProperties)

Get Adapter Display encoder Properties.

  • The application gets the graphic adapters display encoder properties

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pProperties – [in,out][release] Query result for adapter display encoder properties

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDisplayOutput

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pProperties

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetZeDevice

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetZeDevice(ctl_device_adapter_handle_t hDAhandle, void *pZeDevice, void **hInstance)

Get Level0 Device handle.

  • The application gets OneAPI Level0 Device handles

Parameters:

  • hDAhandle – [in][release] Handle to display adapter

  • pZeDevice – [out][release] ze_device handle

  • hInstance – [out][release] Module instance which caller can use to get export functions directly

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pZeDevice

    • nullptr == hInstance

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetSharpnessCaps

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetSharpnessCaps(ctl_display_output_handle_t hDisplayOutput, ctl_sharpness_caps_t *pSharpnessCaps)

Get Sharpness capability.

  • Returns sharpness capability

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pSharpnessCaps – [in,out][release] Query result for sharpness capability

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDisplayOutput

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pSharpnessCaps

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetCurrentSharpness

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetCurrentSharpness(ctl_display_output_handle_t hDisplayOutput, ctl_sharpness_settings_t *pSharpnessSettings)

Get Sharpness setting.

  • Returns current sharpness settings

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pSharpnessSettings – [in,out][release] Query result for sharpness current settings

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDisplayOutput

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pSharpnessSettings

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlSetCurrentSharpness

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlSetCurrentSharpness(ctl_display_output_handle_t hDisplayOutput, ctl_sharpness_settings_t *pSharpnessSettings)

Set Sharpness setting.

  • Set current sharpness settings

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pSharpnessSettings – [in][release] Set sharpness current settings

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDisplayOutput

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pSharpnessSettings

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlI2CAccess

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlI2CAccess(ctl_display_output_handle_t hDisplayOutput, ctl_i2c_access_args_t *pI2cAccessArgs)

I2C Access.

  • Interface to access I2C using display handle as identifier.

Parameters:

  • hDisplayOutput – [in] Handle to display output

  • pI2cAccessArgs – [in,out] I2c access arguments

Returns:

ctlI2CAccessOnPinPair

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlI2CAccessOnPinPair(ctl_i2c_pin_pair_handle_t hI2cPinPair, ctl_i2c_access_pinpair_args_t *pI2cAccessArgs)

I2C Access On Pin Pair.

  • Interface to access I2C using pin-pair handle as identifier.

Parameters:

  • hI2cPinPair – [in] Handle to I2C pin pair.

  • pI2cAccessArgs – [in,out] I2c access arguments.

Returns:

ctlAUXAccess

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlAUXAccess(ctl_display_output_handle_t hDisplayOutput, ctl_aux_access_args_t *pAuxAccessArgs)

Aux Access.

  • The application does Aux access, PSR needs to be disabled for AUX call.

Parameters:

  • hDisplayOutput – [in] Handle to display output

  • pAuxAccessArgs – [in,out] Aux access arguments

Returns:

ctlGetPowerOptimizationCaps

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetPowerOptimizationCaps(ctl_display_output_handle_t hDisplayOutput, ctl_power_optimization_caps_t *pPowerOptimizationCaps)

Get Power optimization features.

  • Returns power optimization capabilities

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pPowerOptimizationCaps – [in,out][release] Query result for power optimization features

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDisplayOutput

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pPowerOptimizationCaps

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetPowerOptimizationSetting

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetPowerOptimizationSetting(ctl_display_output_handle_t hDisplayOutput, ctl_power_optimization_settings_t *pPowerOptimizationSettings)

Get Power optimization setting.

  • Returns power optimization setting for a specific feature

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pPowerOptimizationSettings – [in,out][release] Power optimization data to be fetched

Returns:

ctlSetPowerOptimizationSetting

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlSetPowerOptimizationSetting(ctl_display_output_handle_t hDisplayOutput, ctl_power_optimization_settings_t *pPowerOptimizationSettings)

Set Power optimization setting.

  • Set power optimization setting for a specific feature

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pPowerOptimizationSettings – [in][release] Power optimization data to be applied

Returns:

ctlSetBrightnessSetting

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlSetBrightnessSetting(ctl_display_output_handle_t hDisplayOutput, ctl_set_brightness_t *pSetBrightnessSetting)

Set Brightness on companion display.

  • Set Brightness for a target display. Currently support is only for companion display.

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pSetBrightnessSetting – [in][release] Brightness settings to be applied

Returns:

ctlGetBrightnessSetting

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetBrightnessSetting(ctl_display_output_handle_t hDisplayOutput, ctl_get_brightness_t *pGetBrightnessSetting)

Get Brightness setting.

  • Get Brightness for a target display. Currently support is only for companion display.

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pGetBrightnessSetting – [out][release] Brightness settings data to be fetched

Returns:

ctlPixelTransformationGetConfig

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlPixelTransformationGetConfig(ctl_display_output_handle_t hDisplayOutput, ctl_pixtx_pipe_get_config_t *pPixTxGetConfigArgs)

Pixel transformation get pipe configuration.

  • The application does pixel transformation get pipe configuration

Parameters:

  • hDisplayOutput – [in] Handle to display output

  • pPixTxGetConfigArgs – [in,out] Pixel transformation get pipe configiguration arguments

Returns:

ctlPixelTransformationSetConfig

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlPixelTransformationSetConfig(ctl_display_output_handle_t hDisplayOutput, ctl_pixtx_pipe_set_config_t *pPixTxSetConfigArgs)

Pixel transformation set pipe configuration.

  • The application does pixel transformation set pipe configuration

Parameters:

  • hDisplayOutput – [in] Handle to display output

  • pPixTxSetConfigArgs – [in,out] Pixel transformation set pipe configiguration arguments

Returns:

ctlPanelDescriptorAccess

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlPanelDescriptorAccess(ctl_display_output_handle_t hDisplayOutput, ctl_panel_descriptor_access_args_t *pPanelDescriptorAccessArgs)

Panel Descriptor Access.

  • The application does EDID or Display ID access

Parameters:

  • hDisplayOutput – [in] Handle to display output

  • pPanelDescriptorAccessArgs – [in,out] Panel descriptor access arguments

Returns:

ctlGetSupportedRetroScalingCapability

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetSupportedRetroScalingCapability(ctl_device_adapter_handle_t hDAhandle, ctl_retro_scaling_caps_t *pRetroScalingCaps)

Get Supported Retro Scaling Types.

  • Returns supported retro scaling capabilities

Parameters:

  • hDAhandle – [in][release] Handle to adapter

  • pRetroScalingCaps – [in,out][release] Query result for supported retro scaling types

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pRetroScalingCaps

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetSetRetroScaling

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetSetRetroScaling(ctl_device_adapter_handle_t hDAhandle, ctl_retro_scaling_settings_t *pGetSetRetroScalingType)

Get/Set Retro Scaling.

  • Get or Set the status of retro scaling.This Api will do a physical modeset resulting in flash on the screen

Parameters:

  • hDAhandle – [in][release] Handle to adapter

  • pGetSetRetroScalingType – [in,out][release] Get or Set the retro scaling type

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pGetSetRetroScalingType

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetSupportedScalingCapability

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetSupportedScalingCapability(ctl_display_output_handle_t hDisplayOutput, ctl_scaling_caps_t *pScalingCaps)

Get Supported Scaling Types.

  • Returns supported scaling capabilities

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pScalingCaps – [in,out][release] Query result for supported scaling types

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDisplayOutput

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pScalingCaps

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetCurrentScaling

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetCurrentScaling(ctl_display_output_handle_t hDisplayOutput, ctl_scaling_settings_t *pGetCurrentScalingType)

Get Current Scaling.

  • Returns current active scaling

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pGetCurrentScalingType – [in,out][release] Query result for active scaling types

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDisplayOutput

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pGetCurrentScalingType

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlSetCurrentScaling

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlSetCurrentScaling(ctl_display_output_handle_t hDisplayOutput, ctl_scaling_settings_t *pSetScalingType)

Set Scaling Type.

  • Returns current active scaling

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pSetScalingType – [in,out][release] Set scaling types

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDisplayOutput

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pSetScalingType

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetLACEConfig

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetLACEConfig(ctl_display_output_handle_t hDisplayOutput, ctl_lace_config_t *pLaceConfig)

Get LACE Config.

  • Returns current LACE Config

Parameters:

  • hDisplayOutput – [in] Handle to display output

  • pLaceConfig – [out]Lace configuration

Returns:

ctlSetLACEConfig

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlSetLACEConfig(ctl_display_output_handle_t hDisplayOutput, ctl_lace_config_t *pLaceConfig)

Sets LACE Config.

  • Sets LACE Config

Parameters:

  • hDisplayOutput – [in]Handle to display output

  • pLaceConfig – [in]Lace configuration

Returns:

ctlSoftwarePSR

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlSoftwarePSR(ctl_display_output_handle_t hDisplayOutput, ctl_sw_psr_settings_t *pSoftwarePsrSetting)

Get Software PSR caps/Set software PSR State.

  • Returns Software PSR status or Sets Software PSR capabilities. This is a reserved capability. By default, software PSR is not supported/will not be enabled, need application to activate it, please contact Intel for activation.

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pSoftwarePsrSetting – [in,out][release] Get Software PSR caps/state or Set Software PSR state

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDisplayOutput

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pSoftwarePsrSetting

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetIntelArcSyncInfoForMonitor

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetIntelArcSyncInfoForMonitor(ctl_display_output_handle_t hDisplayOutput, ctl_intel_arc_sync_monitor_params_t *pIntelArcSyncMonitorParams)

Get Intel Arc Sync information for monitor.

  • Returns Intel Arc Sync information for selected monitor

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pIntelArcSyncMonitorParams – [in,out][release] Intel Arc Sync params for monitor

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDisplayOutput

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pIntelArcSyncMonitorParams

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlEnumerateMuxDevices

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlEnumerateMuxDevices(ctl_api_handle_t hAPIHandle, uint32_t *pCount, ctl_mux_output_handle_t *phMuxDevices)

Enumerate Display MUX Devices on this system across adapters.

  • The application enumerates all MUX devices in the system

Parameters:

  • hAPIHandle – [in][release] Applications should pass the Control API handle returned by the CtlInit function

  • pCount – [in,out][release] pointer to the number of MUX device instances. If input count is zero, then the api will update the value with the total number of MUX devices available and return the Count value. If input count is non-zero, then the api will only retrieve the number of MUX Devices. If count is larger than the number of MUX devices available, then the api will update the value with the correct number of MUX devices available.

  • phMuxDevices – [out][range(0, *pCount)] array of MUX device instance handles

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hAPIHandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pCount

    • nullptr == phMuxDevices

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetMuxProperties

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetMuxProperties(ctl_mux_output_handle_t hMuxDevice, ctl_mux_properties_t *pMuxProperties)

Get Display Mux properties.

  • Get the propeties of the Mux device

Parameters:

  • hMuxDevice – [in] MUX device instance handle

  • pMuxProperties – [in,out] MUX device properties

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hMuxDevice

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pMuxProperties

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlSwitchMux

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlSwitchMux(ctl_mux_output_handle_t hMuxDevice, ctl_display_output_handle_t hInactiveDisplayOutput)

Switch Mux output.

  • Switches the MUX output

Parameters:

  • hMuxDevice – [in] MUX device instance handle

  • hInactiveDisplayOutput – [out] Input selection for this MUX, which if active will drive the output of this MUX device. This should be one of the display output handles reported under this MUX device’s properties.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hMuxDevice

    • nullptr == hInactiveDisplayOutput

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetIntelArcSyncProfile

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetIntelArcSyncProfile(ctl_display_output_handle_t hDisplayOutput, ctl_intel_arc_sync_profile_params_t *pIntelArcSyncProfileParams)

Get Intel Arc Sync profile.

  • Returns Intel Arc Sync profile for selected monitor

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pIntelArcSyncProfileParams – [in,out][release] Intel Arc Sync params for monitor

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDisplayOutput

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pIntelArcSyncProfileParams

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlSetIntelArcSyncProfile

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlSetIntelArcSyncProfile(ctl_display_output_handle_t hDisplayOutput, ctl_intel_arc_sync_profile_params_t *pIntelArcSyncProfileParams)

Set Intel Arc Sync profile.

  • Sets Intel Arc Sync profile for selected monitor. In a mux situation, this API should be called for all display IDs associated with a physical display.

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pIntelArcSyncProfileParams – [in][release] Intel Arc Sync params for monitor

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDisplayOutput

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pIntelArcSyncProfileParams

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlEdidManagement

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlEdidManagement(ctl_display_output_handle_t hDisplayOutput, ctl_edid_management_args_t *pEdidManagementArgs)

EDID Management allows managing an output’s EDID or Plugged Status.

  • To manage output’s EDID or Display ID. Supports native DP SST and HDMI Display types.

Parameters:

  • hDisplayOutput – [in] Handle to display output

  • pEdidManagementArgs – [in,out] EDID management arguments

Returns:

ctlGetSetCustomMode

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetSetCustomMode(ctl_display_output_handle_t hDisplayOutput, ctl_get_set_custom_mode_args_t *pCustomModeArgs)

Get/Set Custom mode.

  • To get or set custom mode.

  • Add custom source mode operation supports only single mode additon at a time.

  • Remove custom source mode operation supports single or multiple mode removal at a time.

Parameters:

  • hDisplayOutput – [in] Handle to display output

  • pCustomModeArgs – [in,out] Custom mode arguments

Returns:

ctlGetSetCombinedDisplay

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetSetCombinedDisplay(ctl_device_adapter_handle_t hDeviceAdapter, ctl_combined_display_args_t *pCombinedDisplayArgs)

Get/Set Combined Display.

  • To get or set combined display with given Child Targets on a Single GPU or across identical GPUs. Multi-GPU(MGPU) combined display is reserved i.e. it is not public and requires special application GUID. MGPU Combined Display will get activated or deactivated in next boot. MGPU scenario will internally link the associated adapters via Linked Display Adapter Call, with supplied hDeviceAdapter being the LDA Primary. If Genlock and enabled in Driver registry and supported by given Display Config, MGPU Combined Display will enable MGPU Genlock with supplied hDeviceAdapter being the Genlock Primary Adapter and the First Child Display being the Primary Display.

Parameters:

  • hDeviceAdapter – [in][release] Handle to control device adapter

  • pCombinedDisplayArgs – [in,out] Setup and get combined display arguments

Returns:

ctlGetSetDisplayGenlock

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetSetDisplayGenlock(ctl_device_adapter_handle_t *hDeviceAdapter, ctl_genlock_args_t *pGenlockArgs, uint32_t AdapterCount, ctl_device_adapter_handle_t *hFailureDeviceAdapter)

Get/Set Display Genlock.

  • To get or set Display Genlock.

Parameters:

  • hDeviceAdapter – [in][release] Handle to control device adapter

  • pGenlockArgs – [in,out] Display Genlock operation and information

  • AdapterCount – [in] Number of device adapters

  • hFailureDeviceAdapter – [out] Handle to address the failure device adapter in an error case

Returns:

ctlGetVblankTimestamp

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetVblankTimestamp(ctl_display_output_handle_t hDisplayOutput, ctl_vblank_ts_args_t *pVblankTSArgs)

Get Vblank Timestamp.

  • To get a list of vblank timestamps in microseconds for each child target of a display.

Parameters:

  • hDisplayOutput – [in] Handle to display output

  • pVblankTSArgs – [out] Get vblank timestamp arguments

Returns:

ctlLinkDisplayAdapters

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlLinkDisplayAdapters(ctl_device_adapter_handle_t hPrimaryAdapter, ctl_lda_args_t *pLdaArgs)

Link Display Adapters.

  • To Link Display Adapters.

Parameters:

  • hPrimaryAdapter – [in][release] Handle to Primary adapter in LDA chain

  • pLdaArgs – [in] Link Display Adapters Arguments

Returns:

ctlUnlinkDisplayAdapters

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlUnlinkDisplayAdapters(ctl_device_adapter_handle_t hPrimaryAdapter)

Unlink Display Adapters.

  • To Unlink Display Adapters

Parameters:

hPrimaryAdapter – [in][release] Handle to Primary adapter in LDA chain

Returns:

ctlGetLinkedDisplayAdapters

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetLinkedDisplayAdapters(ctl_device_adapter_handle_t hPrimaryAdapter, ctl_lda_args_t *pLdaArgs)

Get Linked Display Adapters.

  • To return list of Linked Display Adapters.

Parameters:

  • hPrimaryAdapter – [in][release] Handle to Primary adapter in LDA chain

  • pLdaArgs – [out] Link Display Adapters Arguments

Returns:

ctlGetSetDynamicContrastEnhancement

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetSetDynamicContrastEnhancement(ctl_display_output_handle_t hDisplayOutput, ctl_dce_args_t *pDceArgs)

Get/Set Dynamic Contrast Enhancement.

  • To get the DCE feature status and, if feature is enabled, returns the current histogram, or to set the brightness at the phase-in speed

Parameters:

  • hDisplayOutput – [in] Handle to display output

  • pDceArgs – [in,out] Dynamic Contrast Enhancement arguments

Returns:

ctlGetSetWireFormat

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetSetWireFormat(ctl_display_output_handle_t hDisplayOutput, ctl_get_set_wire_format_config_t *pGetSetWireFormatSetting)

Get/Set Color Format and Color Depth.

  • Get and Set the Color Format and Color Depth of a target

Parameters:

  • hDisplayOutput – [in][release] Handle to display output

  • pGetSetWireFormatSetting – [in][release] Get/Set Wire Format settings to be fetched/applied

Returns:

ctlGetSetDisplaySettings

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetSetDisplaySettings(ctl_display_output_handle_t hDisplayOutput, ctl_display_settings_t *pDisplaySettings)

Get/Set Display settings.

  • To get/set end display settings like low latency, HDR10+ signaling etc. which are controlled via info-frames/secondary data packets

Parameters:

  • hDisplayOutput – [in] Handle to display output

  • pDisplaySettings – [in,out] End display capabilities

Returns:

Display Enums

ctl_display_output_types_t

enum ctl_display_output_types_t

Various display types.

Values:

enumerator CTL_DISPLAY_OUTPUT_TYPES_INVALID

Invalid.

enumerator CTL_DISPLAY_OUTPUT_TYPES_DISPLAYPORT

DisplayPort.

enumerator CTL_DISPLAY_OUTPUT_TYPES_HDMI

HDMI.

enumerator CTL_DISPLAY_OUTPUT_TYPES_DVI

DVI.

enumerator CTL_DISPLAY_OUTPUT_TYPES_MIPI

MIPI.

enumerator CTL_DISPLAY_OUTPUT_TYPES_CRT

CRT.

enumerator CTL_DISPLAY_OUTPUT_TYPES_MAX

ctl_output_bpc_flags_t

enum ctl_output_bpc_flag_t

Values:

enumerator CTL_OUTPUT_BPC_FLAG_6BPC

[out] Is 6bpc supported

enumerator CTL_OUTPUT_BPC_FLAG_8BPC

[out] Is 8bpc supported

enumerator CTL_OUTPUT_BPC_FLAG_10BPC

[out] Is 10bpc supported

enumerator CTL_OUTPUT_BPC_FLAG_12BPC

[out] Is 12bpc supported

enumerator CTL_OUTPUT_BPC_FLAG_MAX

ctl_std_display_feature_flags_t

enum ctl_std_display_feature_flag_t

Values:

enumerator CTL_STD_DISPLAY_FEATURE_FLAG_HDCP

[out] Is HDCP supported

enumerator CTL_STD_DISPLAY_FEATURE_FLAG_HD_AUDIO

[out] Is HD Audio supported

enumerator CTL_STD_DISPLAY_FEATURE_FLAG_PSR

[out] Is VESA PSR supported

enumerator CTL_STD_DISPLAY_FEATURE_FLAG_ADAPTIVESYNC_VRR

[out] Is VESA Adaptive Sync or HDMI VRR supported

enumerator CTL_STD_DISPLAY_FEATURE_FLAG_VESA_COMPRESSION

[out] Is display compression (VESA DSC) supported

enumerator CTL_STD_DISPLAY_FEATURE_FLAG_HDR

[out] Is HDR supported

enumerator CTL_STD_DISPLAY_FEATURE_FLAG_HDMI_QMS

[out] Is HDMI QMS supported

enumerator CTL_STD_DISPLAY_FEATURE_FLAG_HDR10_PLUS_CERTIFIED

[out] Is HDR10+ certified

enumerator CTL_STD_DISPLAY_FEATURE_FLAG_VESA_HDR_CERTIFIED

[out] Is VESA HDR certified - for future use

enumerator CTL_STD_DISPLAY_FEATURE_FLAG_MAX

ctl_intel_display_feature_flags_t

enum ctl_intel_display_feature_flag_t

Values:

enumerator CTL_INTEL_DISPLAY_FEATURE_FLAG_DPST

[out] Is DPST supported

enumerator CTL_INTEL_DISPLAY_FEATURE_FLAG_LACE

[out] Is LACE supported

enumerator CTL_INTEL_DISPLAY_FEATURE_FLAG_DRRS

[out] Is DRRS supported

enumerator CTL_INTEL_DISPLAY_FEATURE_FLAG_ARC_ADAPTIVE_SYNC_CERTIFIED

[out] Is Intel Arc certified adaptive sync display

enumerator CTL_INTEL_DISPLAY_FEATURE_FLAG_MAX

ctl_attached_display_mux_type_t

enum ctl_attached_display_mux_type_t

Attached Display Mux Type.

Values:

enumerator CTL_ATTACHED_DISPLAY_MUX_TYPE_NATIVE

[out] Native DP / HDMI

enumerator CTL_ATTACHED_DISPLAY_MUX_TYPE_THUNDERBOLT

[out] Thunderbolt

enumerator CTL_ATTACHED_DISPLAY_MUX_TYPE_TYPE_C

[out] USB Type C

enumerator CTL_ATTACHED_DISPLAY_MUX_TYPE_USB4

[out] USB4

enumerator CTL_ATTACHED_DISPLAY_MUX_TYPE_MAX

ctl_signal_standard_type_t

enum ctl_signal_standard_type_t

Signal Standard.

Values:

enumerator CTL_SIGNAL_STANDARD_TYPE_UNKNOWN

[out] Unknown Signal Standard

enumerator CTL_SIGNAL_STANDARD_TYPE_CUSTOM

[out] Custom added timing

enumerator CTL_SIGNAL_STANDARD_TYPE_DMT

[out] DMT timing

enumerator CTL_SIGNAL_STANDARD_TYPE_GTF

[out] GTF Timing

enumerator CTL_SIGNAL_STANDARD_TYPE_CVT

[out] CVT Timing

enumerator CTL_SIGNAL_STANDARD_TYPE_CTA

[out] CTA Timing

enumerator CTL_SIGNAL_STANDARD_TYPE_MAX

ctl_protocol_converter_location_flags_t

enum ctl_protocol_converter_location_flag_t

Values:

enumerator CTL_PROTOCOL_CONVERTER_LOCATION_FLAG_ONBOARD

[out] OnBoard Protocol Converter

enumerator CTL_PROTOCOL_CONVERTER_LOCATION_FLAG_EXTERNAL

[out] External Dongle

enumerator CTL_PROTOCOL_CONVERTER_LOCATION_FLAG_MAX

ctl_display_config_flags_t

enum ctl_display_config_flag_t

Values:

enumerator CTL_DISPLAY_CONFIG_FLAG_DISPLAY_ACTIVE

[out] DisplayActive 0: InActive 1: Active

enumerator CTL_DISPLAY_CONFIG_FLAG_DISPLAY_ATTACHED

[out] DisplayAttached.This Bit indicates if any dongle/display/hub is attached to the encoder. 0: Not Attached 1: Attached

enumerator CTL_DISPLAY_CONFIG_FLAG_IS_DONGLE_CONNECTED_TO_ENCODER

[out] This BIT will be set if a dongle/hub/onboard protocol converter , is attached to the encoder

enumerator CTL_DISPLAY_CONFIG_FLAG_DITHERING_ENABLED

[out] This BIT will be set if dithering is enabled on the encoder

enumerator CTL_DISPLAY_CONFIG_FLAG_MAX

ctl_encoder_config_flags_t

enum ctl_encoder_config_flag_t

Values:

enumerator CTL_ENCODER_CONFIG_FLAG_INTERNAL_DISPLAY

[out] Internal connection or not

enumerator CTL_ENCODER_CONFIG_FLAG_VESA_TILED_DISPLAY

[out] VESA DisplayID based tiled display which is driven by either multiple physical connections (DisplayPort SST) or virtual streams (DisplayPort MST)

enumerator CTL_ENCODER_CONFIG_FLAG_TYPEC_CAPABLE

[out] This is set if encoder supports type c display

enumerator CTL_ENCODER_CONFIG_FLAG_TBT_CAPABLE

[out] This is set if encoder supports Thunderbolt display

enumerator CTL_ENCODER_CONFIG_FLAG_DITHERING_SUPPORTED

[out] This BIT will be set if encoder supports dithering

enumerator CTL_ENCODER_CONFIG_FLAG_VIRTUAL_DISPLAY

[out] This BIT will be set if this is a virtual display.Hardware based features will not be applicable to this display.For collage display this will be set for the virtual output created by driver. For split display this will be set for the virtual split displays created out of one single physical display

enumerator CTL_ENCODER_CONFIG_FLAG_HIDDEN_DISPLAY

[out] This BIT will be set if display is hidden from OS

enumerator CTL_ENCODER_CONFIG_FLAG_COLLAGE_DISPLAY

[out] This BIT will be set if this is a collage display

enumerator CTL_ENCODER_CONFIG_FLAG_SPLIT_DISPLAY

[out] This BIT will be set if this is a split display

enumerator CTL_ENCODER_CONFIG_FLAG_COMPANION_DISPLAY

[out] This BIT will be set if this is a companion display

enumerator CTL_ENCODER_CONFIG_FLAG_MGPU_COLLAGE_DISPLAY

[out] This BIT will be set if this is a Multi GPU collage display

enumerator CTL_ENCODER_CONFIG_FLAG_MAX

ctl_sharpness_filter_type_flags_t

enum ctl_sharpness_filter_type_flag_t

Values:

enumerator CTL_SHARPNESS_FILTER_TYPE_FLAG_NON_ADAPTIVE

Non-adaptive sharpness.

enumerator CTL_SHARPNESS_FILTER_TYPE_FLAG_ADAPTIVE

Adaptive sharpness.

enumerator CTL_SHARPNESS_FILTER_TYPE_FLAG_MAX

ctl_i2c_flags_t

enum ctl_i2c_flag_t

Values:

enumerator CTL_I2C_FLAG_ATOMICI2C

Force Atomic I2C.

enumerator CTL_I2C_FLAG_1BYTE_INDEX

1-byte Indexed operation. If no Index Size flag set, decided based on Offset Value.

enumerator CTL_I2C_FLAG_2BYTE_INDEX

2-byte Indexed operation. If no Index Size flag set, decided based on Offset Value.

enumerator CTL_I2C_FLAG_4BYTE_INDEX

4-byte Indexed operation. If no Index Size flag set, decided based on Offset Value.

enumerator CTL_I2C_FLAG_SPEED_SLOW

If no Speed Flag is set, defaults to Best Option possible.

enumerator CTL_I2C_FLAG_SPEED_FAST

If no Speed Flag is set, defaults to Best Option possible.

enumerator CTL_I2C_FLAG_SPEED_BIT_BASH

Uses Slower access using SW bit bashing method. If no Speed Flag is set, defaults to Best Option possible.

enumerator CTL_I2C_FLAG_MAX

ctl_i2c_pinpair_flags_t

enum ctl_i2c_pinpair_flag_t

Values:

enumerator CTL_I2C_PINPAIR_FLAG_ATOMICI2C

Force Atomic I2C.

enumerator CTL_I2C_PINPAIR_FLAG_1BYTE_INDEX

1-byte Indexed operation. If no Index Size flag set, decided based on Offset Value.

enumerator CTL_I2C_PINPAIR_FLAG_2BYTE_INDEX

2-byte Indexed operation. If no Index Size flag set, decided based on Offset Value.

enumerator CTL_I2C_PINPAIR_FLAG_4BYTE_INDEX

4-byte Indexed operation. If no Index Size flag set, decided based on Offset Value.

enumerator CTL_I2C_PINPAIR_FLAG_SPEED_SLOW

If no Speed Flag is set, defaults to Best Option possible.

enumerator CTL_I2C_PINPAIR_FLAG_SPEED_FAST

If no Speed Flag is set, defaults to Best Option possible.

enumerator CTL_I2C_PINPAIR_FLAG_SPEED_BIT_BASH

Uses Slower access using SW bit bashing method. If no Speed Flag is set, defaults to Best Option possible.

enumerator CTL_I2C_PINPAIR_FLAG_MAX

ctl_aux_flags_t

enum ctl_aux_flag_t

Values:

enumerator CTL_AUX_FLAG_NATIVE_AUX

For Native AUX operation.

enumerator CTL_AUX_FLAG_I2C_AUX

For I2C AUX operation.

enumerator CTL_AUX_FLAG_I2C_AUX_MOT

For I2C AUX MOT operation.

enumerator CTL_AUX_FLAG_MAX

ctl_power_optimization_flags_t

enum ctl_power_optimization_flag_t

Values:

enumerator CTL_POWER_OPTIMIZATION_FLAG_FBC

Frame buffer compression.

enumerator CTL_POWER_OPTIMIZATION_FLAG_PSR

Panel self refresh.

enumerator CTL_POWER_OPTIMIZATION_FLAG_DPST

Display power saving technology (Panel technology dependent)

enumerator CTL_POWER_OPTIMIZATION_FLAG_LRR

Low refresh rate (LRR/ALRR/UBRR), UBRR is supported only for IGCC and NDA clients. UBZRR and UBLRR both can not be enabled at the same time, only one can be enabled at a given time.

enumerator CTL_POWER_OPTIMIZATION_FLAG_LACE

Lighting Aware Contrast Enhancement.

enumerator CTL_POWER_OPTIMIZATION_FLAG_MAX

ctl_power_optimization_dpst_flags_t

enum ctl_power_optimization_dpst_flag_t

Values:

enumerator CTL_POWER_OPTIMIZATION_DPST_FLAG_BKLT

Intel DPST with Backlight control.

enumerator CTL_POWER_OPTIMIZATION_DPST_FLAG_PANEL_CABC

Panel TCON specific Content Adaptive Control mechanism.

enumerator CTL_POWER_OPTIMIZATION_DPST_FLAG_OPST

Intel OLED Power Saving Technology.

enumerator CTL_POWER_OPTIMIZATION_DPST_FLAG_ELP

TCON based Edge Luminance Profile.

enumerator CTL_POWER_OPTIMIZATION_DPST_FLAG_EPSM

Extra power saving mode.

enumerator CTL_POWER_OPTIMIZATION_DPST_FLAG_APD

Adaptive Pixel Dimming.

enumerator CTL_POWER_OPTIMIZATION_DPST_FLAG_PIXOPTIX

TCON+ based DPST like solution.

enumerator CTL_POWER_OPTIMIZATION_DPST_FLAG_MAX

ctl_power_source_t

enum ctl_power_source_t

Power Source.

Values:

enumerator CTL_POWER_SOURCE_AC

Power Source AC.

enumerator CTL_POWER_SOURCE_DC

Power Source DC.

enumerator CTL_POWER_SOURCE_MAX

ctl_power_optimization_plan_t

enum ctl_power_optimization_plan_t

Power Optimization Plan.

Values:

enumerator CTL_POWER_OPTIMIZATION_PLAN_BALANCED

Balanced mode.

enumerator CTL_POWER_OPTIMIZATION_PLAN_HIGH_PERFORMANCE

High Performance Mode.

enumerator CTL_POWER_OPTIMIZATION_PLAN_POWER_SAVER

Power Saver Mode.

enumerator CTL_POWER_OPTIMIZATION_PLAN_MAX

ctl_power_optimization_lrr_flags_t

enum ctl_power_optimization_lrr_flag_t

Values:

enumerator CTL_POWER_OPTIMIZATION_LRR_FLAG_LRR10

LRR 1.0.

enumerator CTL_POWER_OPTIMIZATION_LRR_FLAG_LRR20

LRR 2.0.

enumerator CTL_POWER_OPTIMIZATION_LRR_FLAG_LRR25

LRR 2.5.

enumerator CTL_POWER_OPTIMIZATION_LRR_FLAG_ALRR

Autonomous LRR.

enumerator CTL_POWER_OPTIMIZATION_LRR_FLAG_UBLRR

User based low refresh rate.

enumerator CTL_POWER_OPTIMIZATION_LRR_FLAG_UBZRR

User based zero refresh rate.

enumerator CTL_POWER_OPTIMIZATION_LRR_FLAG_MAX

ctl_pixtx_pipe_set_config_flags_t

enum ctl_pixtx_pipe_set_config_flag_t

Values:

enumerator CTL_PIXTX_PIPE_SET_CONFIG_FLAG_PERSIST_ACROSS_POWER_EVENTS

For maintaining persistance across power events.

enumerator CTL_PIXTX_PIPE_SET_CONFIG_FLAG_MAX

ctl_pixtx_block_type_t

enum ctl_pixtx_block_type_t

Pixel transformation block types.

Values:

enumerator CTL_PIXTX_BLOCK_TYPE_1D_LUT

Block type 1D LUT.

enumerator CTL_PIXTX_BLOCK_TYPE_3D_LUT

Block type 3D LUT.

enumerator CTL_PIXTX_BLOCK_TYPE_3X3_MATRIX

Block type 3x3 matrix.

enumerator CTL_PIXTX_BLOCK_TYPE_3X3_MATRIX_AND_OFFSETS

Block type 3x3 matrix and offsets.

enumerator CTL_PIXTX_BLOCK_TYPE_MAX

ctl_pixtx_lut_sampling_type_t

enum ctl_pixtx_lut_sampling_type_t

Pixel transformation LUT sampling types.

Values:

enumerator CTL_PIXTX_LUT_SAMPLING_TYPE_UNIFORM

Uniform LUT sampling.

enumerator CTL_PIXTX_LUT_SAMPLING_TYPE_NONUNIFORM

Non uniform LUT sampling, Required mainly in HDR mode.

enumerator CTL_PIXTX_LUT_SAMPLING_TYPE_MAX

ctl_pixtx_config_query_type_t

enum ctl_pixtx_config_query_type_t

Configuration query types.

Values:

enumerator CTL_PIXTX_CONFIG_QUERY_TYPE_CAPABILITY

Get complete pixel processing pipeline capability.

enumerator CTL_PIXTX_CONFIG_QUERY_TYPE_CURRENT

Get the configuration set through last set call.

enumerator CTL_PIXTX_CONFIG_QUERY_TYPE_MAX

ctl_pixtx_config_opertaion_type_t

enum ctl_pixtx_config_opertaion_type_t

Configuration operation types.

Values:

enumerator CTL_PIXTX_CONFIG_OPERTAION_TYPE_RESTORE_DEFAULT

Restore block by block or entire pipe line. Use NumBlocks = 0 to restore all.

enumerator CTL_PIXTX_CONFIG_OPERTAION_TYPE_SET_CUSTOM

Custom LUT or matrix can be set thorugh this option.

enumerator CTL_PIXTX_CONFIG_OPERTAION_TYPE_MAX

ctl_pixtx_gamma_encoding_type_t

enum ctl_pixtx_gamma_encoding_type_t

Pixel transformation gamma encoding types.

Values:

enumerator CTL_PIXTX_GAMMA_ENCODING_TYPE_SRGB

Gamma encoding SRGB.

enumerator CTL_PIXTX_GAMMA_ENCODING_TYPE_REC709

Gamma encoding REC709, Applicable for REC2020 as well.

enumerator CTL_PIXTX_GAMMA_ENCODING_TYPE_ST2084

Gamma encoding ST2084.

enumerator CTL_PIXTX_GAMMA_ENCODING_TYPE_HLG

Gamma encoding HLG.

enumerator CTL_PIXTX_GAMMA_ENCODING_TYPE_LINEAR

Gamma encoding linear.

enumerator CTL_PIXTX_GAMMA_ENCODING_TYPE_MAX

ctl_pixtx_color_space_t

enum ctl_pixtx_color_space_t

Pixel transformation color space types.

Values:

enumerator CTL_PIXTX_COLOR_SPACE_REC709

Color space REC709.

enumerator CTL_PIXTX_COLOR_SPACE_REC2020

Color space REC2020.

enumerator CTL_PIXTX_COLOR_SPACE_ADOBE_RGB

Color space AdobeRGB.

enumerator CTL_PIXTX_COLOR_SPACE_P3_D65

Color space P3_D65.

enumerator CTL_PIXTX_COLOR_SPACE_P3_DCI

Color space P3_DCI.

enumerator CTL_PIXTX_COLOR_SPACE_P3_D60

Color space P3_D60.

enumerator CTL_PIXTX_COLOR_SPACE_CUSTOM

Color space custom, Refer ctl_pixtx_color_primaries_t for color primary details.

enumerator CTL_PIXTX_COLOR_SPACE_MAX

ctl_pixtx_color_model_t

enum ctl_pixtx_color_model_t

Pixel transformation color model types.

Values:

enumerator CTL_PIXTX_COLOR_MODEL_RGB_FR

Color model RGB full range.

enumerator CTL_PIXTX_COLOR_MODEL_RGB_LR

Color model RGB limited range.

enumerator CTL_PIXTX_COLOR_MODEL_YCBCR_422_FR

Color model YCBCR 422 full range.

enumerator CTL_PIXTX_COLOR_MODEL_YCBCR_422_LR

Color model YCBCR 422 limited range.

enumerator CTL_PIXTX_COLOR_MODEL_YCBCR_420_FR

Color model YCBCR 420 full range.

enumerator CTL_PIXTX_COLOR_MODEL_YCBCR_420_LR

Color model YCBCR 420 limited range.

enumerator CTL_PIXTX_COLOR_MODEL_YCBCR_444_FR

Color model YCBCR 444 full range.

enumerator CTL_PIXTX_COLOR_MODEL_YCBCR_444_LR

Color model YCBCR 444 limited range.

enumerator CTL_PIXTX_COLOR_MODEL_MAX

ctl_retro_scaling_type_flags_t

enum ctl_retro_scaling_type_flag_t

Values:

enumerator CTL_RETRO_SCALING_TYPE_FLAG_INTEGER

Integer Scaling.

enumerator CTL_RETRO_SCALING_TYPE_FLAG_NEAREST_NEIGHBOUR

Nearest Neighbour Scaling.

enumerator CTL_RETRO_SCALING_TYPE_FLAG_MAX

ctl_scaling_type_flags_t

enum ctl_scaling_type_flag_t

Values:

enumerator CTL_SCALING_TYPE_FLAG_IDENTITY

No scaling is applied and display manages scaling itself when possible.

enumerator CTL_SCALING_TYPE_FLAG_CENTERED

Source is not scaled but place in the center of the target display.

enumerator CTL_SCALING_TYPE_FLAG_STRETCHED

Source is stretched to fit the target size.

enumerator CTL_SCALING_TYPE_FLAG_ASPECT_RATIO_CENTERED_MAX

The aspect ratio is maintained with the source centered.

enumerator CTL_SCALING_TYPE_FLAG_CUSTOM

None of the standard types match this .Additional parameters are required which should be set via a private driver interface.

enumerator CTL_SCALING_TYPE_FLAG_MAX

ctl_get_operation_flags_t

enum ctl_get_operation_flag_t

Values:

enumerator CTL_GET_OPERATION_FLAG_CURRENT

Get the details set through last set call.

enumerator CTL_GET_OPERATION_FLAG_DEFAULT

Get the driver default values.

enumerator CTL_GET_OPERATION_FLAG_CAPABILITY

Get capability.

enumerator CTL_GET_OPERATION_FLAG_MAX

ctl_set_operation_t

enum ctl_set_operation_t

Set Operations used for additional settings.

Values:

enumerator CTL_SET_OPERATION_RESTORE_DEFAULT

Restore default values.

enumerator CTL_SET_OPERATION_CUSTOM

Set custom values.

enumerator CTL_SET_OPERATION_MAX

ctl_lace_trigger_flags_t

enum ctl_lace_trigger_flag_t

Values:

enumerator CTL_LACE_TRIGGER_FLAG_AMBIENT_LIGHT

LACE enhancement depends on Ambient light.

enumerator CTL_LACE_TRIGGER_FLAG_FIXED_AGGRESSIVENESS

LACE enhancement is as per given fixed aggressiveness level.

enumerator CTL_LACE_TRIGGER_FLAG_MAX

ctl_intel_arc_sync_profile_t

enum ctl_intel_arc_sync_profile_t

Intel Arc Sync profile.

Values:

enumerator CTL_INTEL_ARC_SYNC_PROFILE_INVALID

Invalid profile.

enumerator CTL_INTEL_ARC_SYNC_PROFILE_RECOMMENDED

Default. Selects appropriate profile based on the monitor. COMPATIBLE profile is applied if profile is not available for the monitor.

enumerator CTL_INTEL_ARC_SYNC_PROFILE_EXCELLENT

Unconstrained. Full VRR range of the monitor can be used.

enumerator CTL_INTEL_ARC_SYNC_PROFILE_GOOD

Some minor range constraints, unlikely to effect user experience but can reduce flicker on some monitors.

enumerator CTL_INTEL_ARC_SYNC_PROFILE_COMPATIBLE

Significant constraints that will reduce flicker considerably but are likely to cause some level of judder onscreen especially when refresh rates are changing rapidly.

enumerator CTL_INTEL_ARC_SYNC_PROFILE_OFF

Disable Intel Arc Sync on this monitor. This disables variable rate flips on this monitor. All sync flips will occur at the OS requested refresh rate.

enumerator CTL_INTEL_ARC_SYNC_PROFILE_VESA

Applies vesa specified constraints if the monitor has provided them, COMPATIBLE profile if not.

enumerator CTL_INTEL_ARC_SYNC_PROFILE_CUSTOM

Unlocks controls to set a custom Intel Arc Sync profile.

enumerator CTL_INTEL_ARC_SYNC_PROFILE_MAX

ctl_edid_management_optype_t

enum ctl_edid_management_optype_t

EDID Management operation type.

Values:

enumerator CTL_EDID_MANAGEMENT_OPTYPE_READ_EDID

This operation type is to read an output’s EDID. Set edid_type input arg to read MONITOR EDID or previously OVERRIDDEN EDID or CURRENT active EDID. Read EDID is a 2 pass call. First call with size = 0, pEdidBuf = nullptr to get the size, then call with allocated buffer to get the EDID data. READ operation is applicable for any normal, edid locked or edid overridden display output device.

enumerator CTL_EDID_MANAGEMENT_OPTYPE_LOCK_EDID

To make an output always connected with OVERRIDE or MONITOR EDID across reboots. When output isn’t connected call with OVERRIDE EDID; when connected, either set OVERRIDE and provide pEdidBuf or set MONITOR and driver will use monitor’s EDID. There is no change to EDID stored in Monitor. Cannot be called when override is active. Any OS EDID override will take precedence over IGCL override.

enumerator CTL_EDID_MANAGEMENT_OPTYPE_UNLOCK_EDID

To undo lock EDID operation, i.e. it makes output as detached in response to unplug. This operation removes past supplied EDID; output status is reported to OS as it is; output restores back to monitor’s EDID when it is connected.

enumerator CTL_EDID_MANAGEMENT_OPTYPE_OVERRIDE_EDID

To replace an output’s EDID with supplied one (pEdidBuf) only when physical display is connected. There is no change to EDID stored in Monitor. Cannot apply this operation on locked output. When no output device attached, the supplied EDID will be persisted in driver for future use. Any OS EDID override will take precedence over IGCL override.

enumerator CTL_EDID_MANAGEMENT_OPTYPE_UNDO_OVERRIDE_EDID

To undo override EDID operation, that is remove previously overridden EDID on an output. Output restores back to monitor’s EDID when it is connected.

enumerator CTL_EDID_MANAGEMENT_OPTYPE_MAX

ctl_edid_type_t

enum ctl_edid_type_t

EDID type. Used in LOCK_EDID and READ_EDID calls.

Values:

enumerator CTL_EDID_TYPE_CURRENT

[in] Used to return currently active EDID in READ_EDID call.

enumerator CTL_EDID_TYPE_OVERRIDE

[in] Is it user supplied EDID. Used in LOCK_EDID call with Supplied EDID or in READ_EDID to get Supplied EDID.

enumerator CTL_EDID_TYPE_MONITOR

[in] Is it Monitor’s EDID. Used in LOCK_EDID and READ_EDID calls.

enumerator CTL_EDID_TYPE_MAX

ctl_edid_management_out_flags_t

enum ctl_edid_management_out_flag_t

Values:

enumerator CTL_EDID_MANAGEMENT_OUT_FLAG_OS_CONN_NOTIFICATION

[out] If OS was notified about a connection change. App will need to wait for the OS action to complete.

enumerator CTL_EDID_MANAGEMENT_OUT_FLAG_SUPPLIED_EDID

[out] Is it previously supplied EDID, set for READ_EDID(CURRENT).

enumerator CTL_EDID_MANAGEMENT_OUT_FLAG_MONITOR_EDID

[out] Is it Monitor’s EDID, set for READ_EDID(CURRENT).

enumerator CTL_EDID_MANAGEMENT_OUT_FLAG_DISPLAY_CONNECTED

[out] Is Monitor physically connected

enumerator CTL_EDID_MANAGEMENT_OUT_FLAG_MAX

ctl_custom_mode_operation_types_t

enum ctl_custom_mode_operation_types_t

Custom mode operation types.

Values:

enumerator CTL_CUSTOM_MODE_OPERATION_TYPES_GET_CUSTOM_SOURCE_MODES

Get details of all previous applied custom modes if any.

enumerator CTL_CUSTOM_MODE_OPERATION_TYPES_ADD_CUSTOM_SOURCE_MODE

Add a new mode. Allows only single mode adition at a time.

enumerator CTL_CUSTOM_MODE_OPERATION_TYPES_REMOVE_CUSTOM_SOURCE_MODES

Remove previously added custom mode. Allows single or multiple mode removal at a time.

enumerator CTL_CUSTOM_MODE_OPERATION_TYPES_MAX

ctl_combined_display_optype_t

enum ctl_combined_display_optype_t

Combined Display operation type.

Values:

enumerator CTL_COMBINED_DISPLAY_OPTYPE_IS_SUPPORTED_CONFIG

To check whether given outputs can form a combined display, no changes are applied.

enumerator CTL_COMBINED_DISPLAY_OPTYPE_ENABLE

To setup and enable a combined display.

enumerator CTL_COMBINED_DISPLAY_OPTYPE_DISABLE

To disable combined display.

enumerator CTL_COMBINED_DISPLAY_OPTYPE_QUERY_CONFIG

To query combined display configuration.

enumerator CTL_COMBINED_DISPLAY_OPTYPE_MAX

ctl_genlock_operation_t

enum ctl_genlock_operation_t

Display Genlock Operations.

Values:

enumerator CTL_GENLOCK_OPERATION_GET_TIMING_DETAILS

Get details of GENLOCK support and timing information.

enumerator CTL_GENLOCK_OPERATION_VALIDATE

Driver to verify that the topology is Genlock capable.

enumerator CTL_GENLOCK_OPERATION_ENABLE

Enable GENLOCK.

enumerator CTL_GENLOCK_OPERATION_DISABLE

Disable GENLOCK.

enumerator CTL_GENLOCK_OPERATION_GET_TOPOLOGY

Get details of the current Genlock topology that is applied.

enumerator CTL_GENLOCK_OPERATION_MAX

ctl_wire_format_color_model_t

enum ctl_wire_format_color_model_t

Color model.

Values:

enumerator CTL_WIRE_FORMAT_COLOR_MODEL_RGB

Color model RGB.

enumerator CTL_WIRE_FORMAT_COLOR_MODEL_YCBCR_420

Color model YCBCR 420.

enumerator CTL_WIRE_FORMAT_COLOR_MODEL_YCBCR_422

Color model YCBCR 422.

enumerator CTL_WIRE_FORMAT_COLOR_MODEL_YCBCR_444

Color model YCBCR 444.

enumerator CTL_WIRE_FORMAT_COLOR_MODEL_MAX

ctl_wire_format_operation_type_t

enum ctl_wire_format_operation_type_t

Operation type.

Values:

enumerator CTL_WIRE_FORMAT_OPERATION_TYPE_GET

Get request.

enumerator CTL_WIRE_FORMAT_OPERATION_TYPE_SET

Set request.

enumerator CTL_WIRE_FORMAT_OPERATION_TYPE_RESTORE_DEFAULT

Restore to default values.

enumerator CTL_WIRE_FORMAT_OPERATION_TYPE_MAX

ctl_display_setting_flags_t

enum ctl_display_setting_flag_t

Values:

enumerator CTL_DISPLAY_SETTING_FLAG_LOW_LATENCY

Low latency.

enumerator CTL_DISPLAY_SETTING_FLAG_SOURCE_TM

Source tone mapping.

enumerator CTL_DISPLAY_SETTING_FLAG_CONTENT_TYPE

Content type.

enumerator CTL_DISPLAY_SETTING_FLAG_QUANTIZATION_RANGE

Quantization range, full range or limited range.

enumerator CTL_DISPLAY_SETTING_FLAG_PICTURE_AR

Picture aspect ratio.

enumerator CTL_DISPLAY_SETTING_FLAG_AUDIO

Audio settings.

enumerator CTL_DISPLAY_SETTING_FLAG_MAX

ctl_display_setting_low_latency_t

enum ctl_display_setting_low_latency_t

Low latency setting.

Values:

enumerator CTL_DISPLAY_SETTING_LOW_LATENCY_DEFAULT

Default.

enumerator CTL_DISPLAY_SETTING_LOW_LATENCY_DISABLED

Disabled.

enumerator CTL_DISPLAY_SETTING_LOW_LATENCY_ENABLED

Enabled.

enumerator CTL_DISPLAY_SETTING_LOW_LATENCY_MAX

ctl_display_setting_sourcetm_t

enum ctl_display_setting_sourcetm_t

Source tone mapping setting.

Values:

enumerator CTL_DISPLAY_SETTING_SOURCETM_DEFAULT

Default.

enumerator CTL_DISPLAY_SETTING_SOURCETM_DISABLED

Disabled.

enumerator CTL_DISPLAY_SETTING_SOURCETM_ENABLED

Enabled.

enumerator CTL_DISPLAY_SETTING_SOURCETM_MAX

ctl_display_setting_content_type_t

enum ctl_display_setting_content_type_t

Content type settings.

Values:

enumerator CTL_DISPLAY_SETTING_CONTENT_TYPE_DEFAULT

Default content type used by driver. Driver will use internal techniques to determine content type and indicate to panel.

enumerator CTL_DISPLAY_SETTING_CONTENT_TYPE_DISABLED

Content type indication is disabled.

enumerator CTL_DISPLAY_SETTING_CONTENT_TYPE_DESKTOP

Typical desktop with a mix of text and graphics.

enumerator CTL_DISPLAY_SETTING_CONTENT_TYPE_MEDIA

Video or media content.

enumerator CTL_DISPLAY_SETTING_CONTENT_TYPE_GAMING

Gaming content.

enumerator CTL_DISPLAY_SETTING_CONTENT_TYPE_MAX

ctl_display_setting_quantization_range_t

enum ctl_display_setting_quantization_range_t

Quantization range.

Values:

enumerator CTL_DISPLAY_SETTING_QUANTIZATION_RANGE_DEFAULT

Default based on video format.

enumerator CTL_DISPLAY_SETTING_QUANTIZATION_RANGE_LIMITED_RANGE

Limited range.

enumerator CTL_DISPLAY_SETTING_QUANTIZATION_RANGE_FULL_RANGE

Full range.

enumerator CTL_DISPLAY_SETTING_QUANTIZATION_RANGE_MAX

ctl_display_setting_picture_ar_flags_t

enum ctl_display_setting_picture_ar_flag_t

Values:

enumerator CTL_DISPLAY_SETTING_PICTURE_AR_FLAG_DEFAULT

Default picture aspect ratio.

enumerator CTL_DISPLAY_SETTING_PICTURE_AR_FLAG_DISABLED

Picture aspect ratio indication is explicitly disabled.

enumerator CTL_DISPLAY_SETTING_PICTURE_AR_FLAG_AR_4_3

Aspect ratio of 4:3.

enumerator CTL_DISPLAY_SETTING_PICTURE_AR_FLAG_AR_16_9

Aspect ratio of 16:9.

enumerator CTL_DISPLAY_SETTING_PICTURE_AR_FLAG_AR_64_27

Aspect ratio of 64:27 or 21:9 anamorphic.

enumerator CTL_DISPLAY_SETTING_PICTURE_AR_FLAG_AR_256_135

Aspect ratio of 256:135.

enumerator CTL_DISPLAY_SETTING_PICTURE_AR_FLAG_MAX

ctl_display_setting_audio_t

enum ctl_display_setting_audio_t

Audio settings.

Values:

enumerator CTL_DISPLAY_SETTING_AUDIO_DEFAULT

Default audio settings, always enumerated and enabled if display supports it.

enumerator CTL_DISPLAY_SETTING_AUDIO_DISABLED

Forcefully disable display audio end point enumeration to OS.

enumerator CTL_DISPLAY_SETTING_AUDIO_MAX

Display Structures

ctl_os_display_encoder_identifier_t

union ctl_os_display_encoder_identifier_t
#include <igcl_api.h>

OS specific Display identifiers.

Public Members

uint32_t WindowsDisplayEncoderID

[out] Windows OS Display encoder ID

ctl_generic_void_datatype_t DisplayEncoderID

[out] Display encoder ID for non-windows OS

ctl_display_timing_t

struct ctl_display_timing_t

Display Timing.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint64_t PixelClock

[out] Pixel Clock in Hz

uint32_t HActive

[out] Horizontal Active

uint32_t VActive

[out] Vertical Active

uint32_t HTotal

[out] Horizontal Total

uint32_t VTotal

[out] Vertical Total

uint32_t HBlank

[out] Horizontal Blank

uint32_t VBlank

[out] Vertical Blank

uint32_t HSync

[out] Horizontal Blank

uint32_t VSync

[out] Vertical Blank

float RefreshRate

[out] Refresh Rate

ctl_signal_standard_type_t SignalStandard

[out] Signal Standard

uint8_t VicId

[out] VIC ID for CTA timings

ctl_display_properties_t

struct ctl_display_properties_t

This structure will contain the properties of the display currently attached to the encoder.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_os_display_encoder_identifier_t Os_display_encoder_handle

[out] OS specific Display ID

ctl_display_output_types_t Type

[out] Device Type from display HW stand point. If a DisplayPort protocol converter is involved, this will indicate it’s DisplayPort. The protocol converter’s output will be available from ProtocolConverterOutput field

ctl_attached_display_mux_type_t AttachedDisplayMuxType

[out] Attached Display Mux Type

ctl_display_output_types_t ProtocolConverterOutput

[out] Protocol output type which can be used if config flags indicate it’s a protocol converter. If it’s not a protocol converter this will be set to CTL_DISPLAY_OUTPUT_TYPES_INVALID

ctl_revision_datatype_t SupportedSpec

[out] Supported industry spec version.

ctl_output_bpc_flags_t SupportedOutputBPCFlags

[out] Supported output bits per color. Refer ctl_output_bpc_flag_t. This is independent of RGB or YCbCr output.This is the max BPC supported.BPC will vary per mode based on restrictions like bandwidth and monitor support

ctl_protocol_converter_location_flags_t ProtocolConverterType

[out] Currently Active Protocol Converter. Refer ctl_protocol_converter_location_flag_t

ctl_display_config_flags_t DisplayConfigFlags

[out] Output configuration related flags which indicate how the output pixel stream drive the panel. Refer ctl_display_config_flag_t

ctl_std_display_feature_flags_t FeatureEnabledFlags

[out] Enabled Display features.Refer ctl_std_display_feature_flag_t.

ctl_std_display_feature_flags_t FeatureSupportedFlags

[out] Display Supported feature.Refer ctl_std_display_feature_flag_t

ctl_intel_display_feature_flags_t AdvancedFeatureEnabledFlags

[out] Enabled advanced feature.Refer ctl_intel_display_feature_flag_t.

ctl_intel_display_feature_flags_t AdvancedFeatureSupportedFlags

[out] Supported advanced feature.Refer ctl_intel_display_feature_flag_t.

ctl_display_timing_t Display_Timing_Info

[out] Applied Timing on the Display

uint32_t ReservedFields[16]

[out] Reserved field of 64 bytes

ctl_adapter_display_encoder_properties_t

struct ctl_adapter_display_encoder_properties_t

Adapter’s display encoder properties.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_os_display_encoder_identifier_t Os_display_encoder_handle

[out] OS specific Display ID

ctl_display_output_types_t Type

[out] Device Type from display HW stand point. If a DisplayPort protocol converter is involved, this will indicate it’s DisplayPort. The protocol converter’s output will be available from ProtocolConverterOutput field

bool IsOnBoardProtocolConverterOutputPresent

[out] Protocol output type which can be used if it’s a protocol converter. If it’s not a protocol converter this will be set to CTL_DISPLAY_OUTPUT_TYPES_INVALID

ctl_revision_datatype_t SupportedSpec

[out] Supported industry spec version

ctl_output_bpc_flags_t SupportedOutputBPCFlags

[out] Supported output bits per color. Refer ctl_output_bpc_flag_t. This is independent of RGB or YCbCr output.This is the max BPC supported.BPC will vary per mode based on restrictions like bandwidth and monitor support

ctl_encoder_config_flags_t EncoderConfigFlags

[out] Output configuration related flags which indicate how the output pixel stream drive the panel. Refer ctl_encoder_config_flag_t

Note:

Virtual = 1: This indicates that its a software display. Hardware based features will not be applicable to this display. Collage=1,Virtual=1: Indicates the fake display output created by driver which has the combined resolution of multiple physical displays involved in collage configuration

Collage=1,Virtual=0: Indicates the child physical displays involved in a collage configuration. These are real physical outputs

Split=1,Virtual=1 : Indicates the fake display output created by driver which occupies a portion of a real physical display

Split=1,Virtual=0 : Indicates the physical display which got split to form multiple split displays

Split=1,Collage=1 : Invalid combination

MgpuCollage=1,Collage=1,Virtual=1: Indicates the fake display output created by driver which has the combined resolution of multiple physical displays spread across multiple GPUs involved in Multi-GPU collage configuration MgpuCollage=1,Collage=1,Virtual=0: Indicates the child physical displays involved in a Multi-GPU collage configuration. These are real physical outputs

ctl_std_display_feature_flags_t FeatureSupportedFlags

[out] Adapter Supported feature flags. Refer ctl_std_display_feature_flag_t

ctl_intel_display_feature_flags_t AdvancedFeatureSupportedFlags

[out] Advanced Features Supported by the Adapter. Refer ctl_intel_display_feature_flag_t

uint32_t ReservedFields[16]

[out] Reserved field of 60 bytes

ctl_sharpness_filter_properties_t

struct ctl_sharpness_filter_properties_t

Sharpness filter properties.

Public Members

ctl_sharpness_filter_type_flags_t FilterType

[out] Filter type. Refer ctl_sharpness_filter_type_flag_t

ctl_property_range_info_t FilterDetails

[out] Min, max & step size information

ctl_sharpness_caps_t

struct ctl_sharpness_caps_t

Various sharpness filter types.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_sharpness_filter_type_flags_t SupportedFilterFlags

[out] Supported sharpness filters for a given display output. Refer ctl_sharpness_filter_type_flag_t

uint8_t NumFilterTypes

[out] Number of elements in filter properties array

ctl_sharpness_filter_properties_t *pFilterProperty

[in,out] Array of filter properties structure describing supported filter capabilities. Caller should provide a pre-allocated memory for this.

ctl_sharpness_settings_t

struct ctl_sharpness_settings_t

Current sharpness setting.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool Enable

[in,out] Current or new state of sharpness setting

ctl_sharpness_filter_type_flags_t FilterType

[in,out] Current or new filter to be set. Refer ctl_sharpness_filter_type_flag_t

float Intensity

[in,out] Setting intensity to be applied

ctl_i2c_access_args_t

struct ctl_i2c_access_args_t

I2C access arguments.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint32_t DataSize

[in,out] Valid data size

uint32_t Address

[in] Address to read or write

ctl_operation_type_t OpType

[in] Operation type, 1 for Read, 2 for Write, for Write operation, App needs to run with admin privileges

uint32_t Offset

[in] Offset

ctl_i2c_flags_t Flags

[in] I2C Flags. Refer ctl_i2c_flag_t

uint64_t RAD

[in] RAD, For Future use, to be used for branch devices, Interface will be provided to get RAD

uint8_t Data[CTL_I2C_MAX_DATA_SIZE]

[in,out] Data array

ctl_i2c_access_pinpair_args_t

struct ctl_i2c_access_pinpair_args_t

I2C access on Pin Pair arguments.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint32_t DataSize

[in,out] Valid data size

uint32_t Address

[in] Address to read or write

ctl_operation_type_t OpType

[in] Operation type, 1 for Read, 2 for Write, for Write operation, App needs to run with admin privileges

uint32_t Offset

[in] Offset

ctl_i2c_pinpair_flags_t Flags

[in] I2C Flags. Refer ctl_i2c_pinpair_flag_t

uint8_t Data[CTL_I2C_MAX_DATA_SIZE]

[in,out] Data array

uint32_t ReservedFields[4]

[in] Reserved for future use, must be set to Zero.

ctl_aux_access_args_t

struct ctl_aux_access_args_t

AUX access arguments.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_operation_type_t OpType

[in] Operation type, 1 for Read, 2 for Write, for Write operation, App needs to run with admin privileges

ctl_aux_flags_t Flags

[in] Aux Flags. Refer ctl_aux_flag_t

uint32_t Address

[in] Address to read or write

uint64_t RAD

[in] RAD, For Future use, to be used for branch devices, Interface will be provided to get RAD

uint32_t PortID

[in] Port ID, For Future use, to be used for SST tiled devices

uint32_t DataSize

[in,out] Valid data size

uint8_t Data[CTL_AUX_MAX_DATA_SIZE]

[in,out] Data array

ctl_power_optimization_caps_t

struct ctl_power_optimization_caps_t

Power optimization caps.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_power_optimization_flags_t SupportedFeatures

[out] Supported power optimization features. Refer ctl_power_optimization_flag_t

ctl_power_optimization_lrr_t

struct ctl_power_optimization_lrr_t

LRR detailed settings.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_power_optimization_lrr_flags_t SupportedLRRTypes

[out] LRR type(s). Refer ctl_power_optimization_lrr_flag_t

ctl_power_optimization_lrr_flags_t CurrentLRRTypes

[in,out] Current enabled LRR type(s) or the LRR type(s) to set to. Refer ctl_power_optimization_lrr_flag_t

bool bRequirePSRDisable

[out] Require PSR disable for any change in the selected LRR feature. Caller can re-enable PSR once the respective LRR feature is enable/disabled. E.g. for UBRR based on platform this flag may not be set in which case caller doesn’t need to do an explicit PSR disable

uint16_t LowRR

[out] Lowest RR used for LRR functionality if known to source

ctl_power_optimization_psr_t

struct ctl_power_optimization_psr_t

PSR detailed settings.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint8_t PSRVersion

[in,out] A value of 1 means PSR1, 2 means PSR2

bool FullFetchUpdate

[in,out] Full fetch and update

ctl_power_optimization_dpst_t

struct ctl_power_optimization_dpst_t

DPST detailed settings.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint8_t MinLevel

[out] Minimum supported aggressiveness level

uint8_t MaxLevel

[out] Maximum supported aggressiveness level

uint8_t Level

[in,out] Current aggressiveness level to be set

ctl_power_optimization_dpst_flags_t SupportedFeatures

[out] Supported features

ctl_power_optimization_dpst_flags_t EnabledFeatures

[in,out] Features enabled or to be enabled. Fill only one feature for SET call

ctl_power_optimization_feature_specific_info_t

union ctl_power_optimization_feature_specific_info_t
#include <igcl_api.h>

Feature specific power optimization data.

Public Members

ctl_power_optimization_lrr_t LRRInfo

[out] LRR info

ctl_power_optimization_psr_t PSRInfo

[in,out] PSR info

ctl_power_optimization_dpst_t DPSTInfo

[in,out] DPST info

ctl_power_optimization_settings_t

struct ctl_power_optimization_settings_t

Power optimization settings.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_power_optimization_plan_t PowerOptimizationPlan

[in] Power optimization power plan (max power/max perf/balanced)

ctl_power_optimization_flags_t PowerOptimizationFeature

[in] Power optimization feature interested in. Refer ctl_power_optimization_flag_t

bool Enable

[in,out] Enable state

ctl_power_optimization_feature_specific_info_t FeatureSpecificData

[in,out] Data specific to the feature caller is interested in

ctl_power_source_t PowerSource

[in] AC/DC

ctl_set_brightness_t

struct ctl_set_brightness_t

Brightness settings for SET call.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint32_t TargetBrightness

[in] The brightness level that the display need to transitioning to in milli-percentage. Range is 0-100000 (100%)

uint32_t SmoothTransitionTimeInMs

[in] Transition Time for brightness to take effect in milli-seconds. If its 0 then it will be an immediate change. Maximum possible value is 1000ms.

uint32_t ReservedFields[4]

[in] Reserved for future use

ctl_get_brightness_t

struct ctl_get_brightness_t

Brightness settings for GET call.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint32_t TargetBrightness

[out] The brightness level that the display is currently transitioning to in milli-percentage. If not in a transition, this should equal the current brightness. Range is 0-100000 (100%)

uint32_t CurrentBrightness

[out] The current brightness level of the display in milli-percentage

uint32_t ReservedFields[4]

[out] Reserved for future use

ctl_pixtx_color_primaries_t

struct ctl_pixtx_color_primaries_t

Pixel transformation color primaries.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

double xR

[out] CIE1931 x value with maximum red pixel value

double yR

[out] CIE1931 y value with maximum red pixel value

double xG

[out] CIE1931 x value with maximum green pixel value

double yG

[out] CIE1931 y value with maximum green pixel value

double xB

[out] CIE1931 x value with maximum blue pixel value

double yB

[out] CIE1931 y value with maximum blue pixel value

double xW

[out] CIE1931 x value with maximum white pixel value

double yW

[out] CIE1931 y value with maximum white pixel value

ctl_pixtx_pixel_format_t

struct ctl_pixtx_pixel_format_t

Pixel transformation pixel format.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint32_t BitsPerColor

[out] Bits per color, It Will be 16 for FP16 case

bool IsFloat

[out] Will be set for FP16 or other floating point encoding schemes

ctl_pixtx_gamma_encoding_type_t EncodingType

[out] Encoding type

ctl_pixtx_color_space_t ColorSpace

[out] Color space

ctl_pixtx_color_model_t ColorModel

[out] Color model

ctl_pixtx_color_primaries_t ColorPrimaries

[out] Color primaries, Used mainly for custom color space

double MaxBrightness

[out] Maximum brightness of pixel values. If no input is given, default will be set to sRGB during set call. If panel capability is not known get call will default to sRGB.

double MinBrightness

[out] Minimum brightness of pixel values

ctl_pixtx_1dlut_config_t

struct ctl_pixtx_1dlut_config_t

Pixel transformation 1D LUT configuration.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_pixtx_lut_sampling_type_t SamplingType

[in,out] Blocks with non-uniform sampling capability support unifrom sampling also but not vice versa.

uint32_t NumSamplesPerChannel

[in,out] Number of samples per channel. Resampled internally based on HW capability for uniformly sampled LUT.Maximum supported value is CTL_MAX_NUM_SAMPLES_PER_CHANNEL_1D_LUT Caller needs to use exact sampling position given in pSamplePositions for non-uniformly sampled LUTs.

uint32_t NumChannels

[in,out] Number of channels, 1 for Grey scale LUT, 3 for RGB LUT

double *pSampleValues

[in,out] Pointer to sample values, R array followed by G and B arrays in case of multi-channel LUT. Allocation size for pSampleValues should be NumSamplesPerChannel * NumChannels * sizeof(double)

double *pSamplePositions

[out] LUT (same for all channels) to represent sampling positions for non-uniformly sampled LUTs.Can be NULL in case uniformly sampled LUTs

ctl_pixtx_matrix_config_t

struct ctl_pixtx_matrix_config_t

Pixel transformation matrix configuration.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

double PreOffsets[3]

[in,out] Pre offsets

double PostOffsets[3]

[in,out] Post offsets

double Matrix[3][3]

[in,out] 3x3 Matrix

ctl_pixtx_3dlut_sample_t

struct ctl_pixtx_3dlut_sample_t

Pixel transformation 3D LUT sample. Samples are converted to integer based on underlying HW capabilities. Hence slight precision loss will be observed while getting sample values.

Public Members

double Red

[in,out] Red output value

double Green

[in,out] Green output value

double Blue

[in,out] Blue output value

ctl_pixtx_3dlut_config_t

struct ctl_pixtx_3dlut_config_t

Pixel transformation 3D LUT configuration.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint32_t NumSamplesPerChannel

[in,out] Number of samples per channel

ctl_pixtx_3dlut_sample_t *pSampleValues

[in,out] Pointer to sample values, R in outer most loop followed by G and B

ctl_pixtx_config_t

union ctl_pixtx_config_t
#include <igcl_api.h>

Pixel transformation configuration.

Public Members

ctl_pixtx_1dlut_config_t OneDLutConfig

[in,out] 1D LUT configuration

ctl_pixtx_3dlut_config_t ThreeDLutConfig

[in,out] 3D LUT configuration

ctl_pixtx_matrix_config_t MatrixConfig

[in,out] Matrix configuration

ctl_pixtx_block_config_t

struct ctl_pixtx_block_config_t

Pixel transformation block configuration.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint32_t BlockId

[in,out] Unique ID for each pixel processing block. Id for a block is fixed for a platform.

ctl_pixtx_block_type_t BlockType

[in,out] Block type

ctl_pixtx_config_t Config

[in,out] Configuration

ctl_pixtx_pipe_get_config_t

struct ctl_pixtx_pipe_get_config_t

Pixel transformation pipe get configuration.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_pixtx_config_query_type_t QueryType

[in] Query operation type

ctl_pixtx_pixel_format_t InputPixelFormat

[out] Input pixel format

ctl_pixtx_pixel_format_t OutputPixelFormat

[out] Output pixel format

uint32_t NumBlocks

[out] Number of blocks

ctl_pixtx_block_config_t *pBlockConfigs

[out] Pointer to specific configs

ctl_pixtx_pipe_set_config_t

struct ctl_pixtx_pipe_set_config_t

Pixel transformation pipe set configuration.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_pixtx_config_opertaion_type_t OpertaionType

[in] Set operation type

ctl_pixtx_pipe_set_config_flags_t Flags

[in] Config flags. Refer ctl_pixtx_pipe_set_config_flag_t

uint32_t NumBlocks

[in] Number of blocks

ctl_pixtx_block_config_t *pBlockConfigs

[in,out] Array of block specific configs

ctl_panel_descriptor_access_args_t

struct ctl_panel_descriptor_access_args_t

Panel descriptor access arguments.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_operation_type_t OpType

[in] Operation type, 1 for Read, 2 for Write. App needs to run with admin privileges for Write operation, Currently only Read operation is supported

uint32_t BlockNumber

[in] Block number, Need to provide only if acccessing EDID

uint32_t DescriptorDataSize

[in] Descriptor data size, Should be 0 for querying the size and should be DescriptorDataSize derived from query call otherwise

uint8_t *pDescriptorData

[in,out] Panel descriptor data

ctl_retro_scaling_settings_t

struct ctl_retro_scaling_settings_t

Set/Get Retro Scaling Type.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool Get

[in][release] Set to true to get current scaling . Set to False to Set the scaling

bool Enable

[in,out] State of the scaler

ctl_retro_scaling_type_flags_t RetroScalingType

[out] Requested retro scaling types. Refer ctl_retro_scaling_type_flag_t

ctl_retro_scaling_caps_t

struct ctl_retro_scaling_caps_t

Retro Scaling caps.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_retro_scaling_type_flags_t SupportedRetroScaling

[out] Supported retro scaling types

ctl_scaling_caps_t

struct ctl_scaling_caps_t

Scaling caps.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_scaling_type_flags_t SupportedScaling

[out] Supported scaling types. Refer ctl_scaling_type_flag_t

ctl_scaling_settings_t

struct ctl_scaling_settings_t

Set/Get Scaling type.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool Enable

[in,out] State of the scaler

ctl_scaling_type_flags_t ScalingType

[in,out] Requested scaling type. In Get call this field indicates ‘currunt’ scaling set. Refer ctl_scaling_type_flag_t

uint32_t CustomScalingX

[in,out] Custom Scaling X in percentage. This is percentage of current OS resolution. Valid values are 0 to 100. Up to 11% of native resolution can be downscaled

uint32_t CustomScalingY

[in,out] Custom Scaling Y in percentage. This is percentage of current OS resolution. Valid values are 0 to 100. Up to 11% of native resolution can be downscaled

bool HardwareModeSet

[in] Flag to indicate hardware modeset should be done to apply the scaling.Setting this to true would result in a flash on the screen. If this flag is set to false , API will request the OS to do a virtual modeset , but the OS can ignore this request and do a hardware modeset in some instances

ctl_scaling_type_flags_t PreferredScalingType

[out] Indicates OS persisted scaling type. This field is only valid when version > 0. Refer ctl_scaling_type_flag_t

ctl_lace_lux_aggr_map_entry_t

struct ctl_lace_lux_aggr_map_entry_t

Ambient light based enhancement table entry.

Public Members

uint32_t Lux

[in,out] Ambient lux

uint8_t AggressivenessPercent

[in,out] Pixel boost agressiveness

ctl_lace_lux_aggr_map_t

struct ctl_lace_lux_aggr_map_t

Ambient light based enhancement table.

Public Members

uint32_t MaxNumEntries

[out] Max Number of entries in mapping table supported

uint32_t NumEntries

[in,out] Number of entries in the given mapping table

ctl_lace_lux_aggr_map_entry_t *pLuxToAggrMappingTable

[in] Max number of Entries which can be passed in LuxToAggrMappingTable

ctl_lace_aggr_config_t

union ctl_lace_aggr_config_t
#include <igcl_api.h>

Data specific to the mode caller is interested in.

Public Members

uint8_t FixedAggressivenessLevelPercent

[in,out] Fixed aggressiveness level, applicable for CTL_LACE_MODE_FIXED_AGGR_LEVEL

ctl_lace_lux_aggr_map_t AggrLevelMap

[in,out] Lux to enhancement mapping table, applicable for CTL_LACE_MODE_AMBIENT_ADAPTIVE

ctl_lace_config_t

struct ctl_lace_config_t

Set/Get LACE Config.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool Enabled

[in,out] Enable or disable LACE feature

ctl_get_operation_flags_t OpTypeGet

[in] Get Operations used for additional settings

ctl_set_operation_t OpTypeSet

[in] Set Operations used for additional settings

ctl_lace_trigger_flags_t Trigger

[in,out] LACE operating mode to be Triggerd

ctl_lace_aggr_config_t LaceConfig

[in,out] Data specific to the mode, caller is interested in

ctl_sw_psr_settings_t

struct ctl_sw_psr_settings_t

Get Software PSR status/Set Software PSR settings.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool Set

[in][release] Set to False to Get Software PSR status. Set to True to Enable/Disable Software PSR

bool Supported

[out] When Get is True, returns if SW PSR is supported

bool Enable

[in,out] When Get is True, returns current state of Software PSR. When Get is False, Enables/Diasbles Software PSR

ctl_intel_arc_sync_monitor_params_t

struct ctl_intel_arc_sync_monitor_params_t

Intel Arc Sync Monitor Params.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool IsIntelArcSyncSupported

[out] Intel Arc Sync support for the monitor

float MinimumRefreshRateInHz

[out] Minimum Intel Arc Sync refresh rate supported by the monitor

float MaximumRefreshRateInHz

[out] Maximum Intel Arc Sync refresh rate supported by the monitor

uint32_t MaxFrameTimeIncreaseInUs

[out] Max frame time increase in micro seconds from DID2.1 Adaptive Sync block

uint32_t MaxFrameTimeDecreaseInUs

[out] Max frame time decrease in micro seconds from DID2.1 Adaptive Sync block

ctl_mux_properties_t

struct ctl_mux_properties_t

Display MUX device properties.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint8_t MuxId

[out] MUX ID of this MUX device enumerated

uint32_t Count

[in,out] Pointer to the number of display output instances this MUX object can drive. If count is zero, then the api will update the value with the total number of outputs available. If count is non-zero, then the api will only retrieve the number of outputs. If count is larger than the number of display outputs MUX can drive, then the api will update the value with the correct number of display outputs MUX can driver.

ctl_display_output_handle_t *phDisplayOutputs

[in,out][range(0, *pCount)] Array of display output instance handles this MUX device can drive

uint8_t IndexOfDisplayOutputOwningMux

[out] [range(0, (Count-1))] This is the index into the phDisplayOutputs list to the display output which currently owns the MUX output. This doesn’t mean display is active

ctl_intel_arc_sync_profile_params_t

struct ctl_intel_arc_sync_profile_params_t

Intel Arc Sync Profile Params.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_intel_arc_sync_profile_t IntelArcSyncProfile

[in,out] Intel Arc Sync profile used by driver. Refer ctl_intel_arc_sync_profile_t

float MaxRefreshRateInHz

[in,out] Maximum refresh rate utilized by the driver

float MinRefreshRateInHz

[in,out] Minimum refresh rate utilized by the driver

uint32_t MaxFrameTimeIncreaseInUs

[in,out] Maximum frame time increase (in micro seconds) imposed by the driver

uint32_t MaxFrameTimeDecreaseInUs

[in,out] Maximum frame time decrease (in micro seconds) imposed by the driver

ctl_edid_management_args_t

struct ctl_edid_management_args_t

EDID management.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_edid_management_optype_t OpType

[in] EDID managmeent operation type

ctl_edid_type_t EdidType

[in] EDID Type, Monitor or Supplied

uint32_t EdidSize

[in,out] EDID Size, should be 0 for querying the size of EDID, should be previously returned size to read EDID. if buffer isn’t big enough to fit EDID, returns size of EDID bytes.

uint8_t *pEdidBuf

[in,out] buffer holding EDID data

ctl_edid_management_out_flags_t OutFlags

[out] Output flags to inform about status of EDID management operations

ctl_get_set_custom_mode_args_t

struct ctl_get_set_custom_mode_args_t

Get/Set Custom Mode.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_custom_mode_operation_types_t CustomModeOpType

[in] Custom mode operation type

uint32_t NumOfModes

[in,out] Number of Custom Src Modes to be added/removed/Read.

ctl_custom_src_mode_t *pCustomSrcModeList

[in,out] Custom mode source list which holds source modes to be added/removed/Read.

ctl_custom_src_mode_t

struct ctl_custom_src_mode_t

Get/Set Custom Mode.

Public Members

uint32_t SourceX

[in,out] CustomMode Source X Size

uint32_t SourceY

[in,out] CustomMode Source Y Size

ctl_child_display_target_mode_t

struct ctl_child_display_target_mode_t

Combined Display’s child display target mode.

Public Members

uint32_t Width

[in,out] Width

uint32_t Height

[in,out] Height

float RefreshRate

[in,out] Refresh Rate

uint32_t ReservedFields[4]

[out] Reserved field of 16 bytes

ctl_combined_display_child_info_t

struct ctl_combined_display_child_info_t

Combined Display’s child display information.

Public Members

ctl_display_output_handle_t hDisplayOutput

[in,out] Display output handle under combined display configuration

ctl_rect_t FbSrc

[in,out] FrameBuffer source’s RECT within Combined Display respective

ctl_rect_t FbPos

[in,out] FrameBuffer target’s RECT within output size

ctl_display_orientation_t DisplayOrientation

[in,out] 0/180 Degree Display orientation (rotation)

ctl_child_display_target_mode_t TargetMode

[in,out] Desired target mode (width, height, refresh)

ctl_combined_display_args_t

struct ctl_combined_display_args_t

Combined Display arguments.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_combined_display_optype_t OpType

[in] Combined display operation type

bool IsSupported

[out] Returns yes/no in response to IS_SUPPORTED_CONFIG command

uint8_t NumOutputs

[in,out] Number of outputs part of desired combined display configuration

uint32_t CombinedDesktopWidth

[in,out] Width of desired combined display configuration

uint32_t CombinedDesktopHeight

[in,out] Height of desired combined display configuration

ctl_combined_display_child_info_t *pChildInfo

[in,out] List of child display information respective to each output. Up to 16 displays are supported with up to 4 displays per GPU.

ctl_display_output_handle_t hCombinedDisplayOutput

[in,out] Handle to combined display output

ctl_genlock_display_info_t

struct ctl_genlock_display_info_t

Display Genlock Info.

Public Members

ctl_display_output_handle_t hDisplayOutput

[in,out] Display output handle under Genlock topology

bool IsPrimary

[in,out] Genlock Primary

ctl_genlock_target_mode_list_t

struct ctl_genlock_target_mode_list_t

Genlock Target Mode List.

Public Members

ctl_display_output_handle_t hDisplayOutput

[in] Display output handle for whom target mode list is required

uint32_t NumModes

[in,out] Number of supported Modes that is returned from a driver

ctl_display_timing_t *pTargetModes

[out] Display Genlock operation and information

ctl_genlock_topology_t

struct ctl_genlock_topology_t

Genlock Topology.

Public Members

uint8_t NumGenlockDisplays

[in,out] Number of Genlock displays

bool IsPrimaryGenlockSystem

[in,out] Primary Genlock system

ctl_display_timing_t CommonTargetMode

[in] Common target mode

ctl_genlock_display_info_t *pGenlockDisplayInfo

[in,out] List of Genlock display info

ctl_genlock_target_mode_list_t *pGenlockModeList

[out] List of Genlock target modes

ctl_genlock_args_t

struct ctl_genlock_args_t

Display Genlock Arg type.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_genlock_operation_t Operation

[in] Display Genlock Operation

ctl_genlock_topology_t GenlockTopology

[in,out] Display Genlock array of topology structures

bool IsGenlockEnabled

[out] Whether the feature is currently enabled or not

bool IsGenlockPossible

[out] Indicates if Genlock can be enabled/disabled with the given topology

ctl_vblank_ts_args_t

struct ctl_vblank_ts_args_t

Vblank timestamp arguments.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint8_t NumOfTargets

[out] Number of child targets

uint64_t VblankTS[CTL_MAX_DISPLAYS_FOR_MGPU_COLLAGE]

[out] List of vblank timestamps in microseconds per child target

ctl_lda_args_t

struct ctl_lda_args_t

Link Display Adapters Arguments.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint8_t NumAdapters

[in,out] Numbers of adapters to be linked. Up to 4 adapters are supported

ctl_device_adapter_handle_t *hLinkedAdapters

[in,out][release] List of Control device adapter handles to be linked, first one being Primary Adapter

uint64_t Reserved[4]

[out] Reserved fields. Set to zero.

ctl_dce_args_t

struct ctl_dce_args_t

Get/Set Dynamic Contrast Enhancement arguments.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool Set

[in] Flag to indicate Set or Get operation

uint32_t TargetBrightnessPercent

[in] Target brightness percent

double PhaseinSpeedMultiplier

[in] Phase-in speed multiplier for brightness to take effect

uint32_t NumBins

[in,out] Number of histogram bins

bool Enable

[in,out] For get calls, this represents current state & for set this represents future state

bool IsSupported

[out] is DCE feature supported

uint32_t *pHistogram

[out] Bin wise histogram data of size NumBins * sizeof(uint32_t) for current frame

ctl_wire_format_t

struct ctl_wire_format_t

Wire Format.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_wire_format_color_model_t ColorModel

[in,out] Color model

ctl_output_bpc_flags_t ColorDepth

[in,out] Color Depth

ctl_get_set_wire_format_config_t

struct ctl_get_set_wire_format_config_t

Get Set Wire Format.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_wire_format_operation_type_t Operation

[in] Get/Set Operation

ctl_wire_format_t SupportedWireFormat[CTL_MAX_WIREFORMAT_COLOR_MODELS_SUPPORTED]

[out] Array of WireFormats supported

ctl_wire_format_t WireFormat

[in,out] Current/Requested WireFormat based on Operation. During SET Operation, if multiple bpc is set, the MIN bpc will be applied

ctl_display_settings_t

struct ctl_display_settings_t

Get/Set end display settings.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool Set

[in] Flag to indicate Set or Get operation. Default option for all features are reserved for Set=true calls, which will reset the setting to driver defaults.

ctl_display_setting_flags_t SupportedFlags

[out] Display setting flags supported by the display.

ctl_display_setting_flags_t ControllableFlags

[out] Display setting flags which can be controlled by the caller. Features which doesn’t have this flag set cannot be changed by caller.

ctl_display_setting_flags_t ValidFlags

[in,out] Display setting flags which caller can use to indicate the features it’s interested in. This cannot have a bit set which is not supported by SupportedFlags and ControllableFlags.

ctl_display_setting_low_latency_t LowLatency

[in,out] Low latency state of panel. For HDR10+ Gaming this need to be in ENABLED state.

ctl_display_setting_sourcetm_t SourceTM

[in,out] Source tone mapping state known to panel. For HDR10+ Gaming this need to be in ENABLED state.

ctl_display_setting_content_type_t ContentType

[in,out] Source content type known to panel.

ctl_display_setting_quantization_range_t QuantizationRange

[in,out] Quantization range

ctl_display_setting_picture_ar_flags_t SupportedPictureAR

[out] Supported Picture aspect ratios

ctl_display_setting_picture_ar_flag_t PictureAR

[in,out] Picture aspect ratio

ctl_display_setting_audio_t AudioSettings

[in,out] Audio settings

uint32_t Reserved[25]

[out] Reserved fields for future enumerations

Engine

Engine Functions

ctlEnumEngineGroups

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlEnumEngineGroups(ctl_device_adapter_handle_t hDAhandle, uint32_t *pCount, ctl_engine_handle_t *phEngine)

Get handle of engine groups.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hDAhandle – [in][release] Handle to adapter

  • pCount – [in,out] pointer to the number of components of this type. if count is zero, then the driver shall update the value with the total number of components of this type that are available. if count is greater than the number of components of this type that are available, then the driver shall update the value with the correct number of components.

  • phEngine – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pCount

ctlEngineGetProperties

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlEngineGetProperties(ctl_engine_handle_t hEngine, ctl_engine_properties_t *pProperties)

Get engine group properties.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hEngine – [in] Handle for the component.

  • pProperties – [in,out] The properties for the specified engine group.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hEngine

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pProperties

ctlEngineGetActivity

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlEngineGetActivity(ctl_engine_handle_t hEngine, ctl_engine_stats_t *pStats)

Get the activity stats for an engine group.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hEngine – [in] Handle for the component.

  • pStats – [in,out] Will contain a snapshot of the engine group activity counters.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hEngine

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pStats

Engine Enums

ctl_engine_group_t

enum ctl_engine_group_t

Accelerator engine groups.

Values:

enumerator CTL_ENGINE_GROUP_GT

Access information about all engines combined.

enumerator CTL_ENGINE_GROUP_RENDER

Access information about all render and compute engines combined.

enumerator CTL_ENGINE_GROUP_MEDIA

Access information about all media engines combined.

enumerator CTL_ENGINE_GROUP_MAX

Engine Structures

ctl_engine_properties_t

struct ctl_engine_properties_t

Engine group properties.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_engine_group_t type

[out] The engine group

ctl_engine_stats_t

struct ctl_engine_stats_t

Engine activity counters.

  • Percent utilization is calculated by taking two snapshots (s1, s2) and using the equation: util = (s2.activeTime - s1.activeTime) / (s2.timestamp - s1.timestamp)

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint64_t activeTime

[out] Monotonic counter for time in microseconds that this resource is actively running workloads.

uint64_t timestamp

[out] Monotonic timestamp counter in microseconds when activeTime counter was sampled. This timestamp should only be used to calculate delta time between snapshots of this structure. Never take the delta of this timestamp with the timestamp from a different structure since they are not guaranteed to have the same base. The absolute value of the timestamp is only valid during within the application and may be different on the next execution.

Fan

Fan Functions

ctlEnumFans

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlEnumFans(ctl_device_adapter_handle_t hDAhandle, uint32_t *pCount, ctl_fan_handle_t *phFan)

Get handle of fans.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hDAhandle – [in][release] Handle to the adapter

  • pCount – [in,out] pointer to the number of components of this type. if count is zero, then the driver shall update the value with the total number of components of this type that are available. if count is greater than the number of components of this type that are available, then the driver shall update the value with the correct number of components.

  • phFan – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pCount

ctlFanGetProperties

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlFanGetProperties(ctl_fan_handle_t hFan, ctl_fan_properties_t *pProperties)

Get fan properties.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hFan – [in] Handle for the component.

  • pProperties – [in,out] Will contain the properties of the fan.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hFan

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pProperties

ctlFanGetConfig

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlFanGetConfig(ctl_fan_handle_t hFan, ctl_fan_config_t *pConfig)

Get fan configurations and the current fan speed mode (default, fixed, temp-speed table)

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hFan – [in] Handle for the component.

  • pConfig – [in,out] Will contain the current configuration of the fan.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hFan

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pConfig

ctlFanSetDefaultMode

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlFanSetDefaultMode(ctl_fan_handle_t hFan)

Configure the fan to run with hardware factory settings (set mode to CTL_FAN_SPEED_MODE_DEFAULT)

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

hFan – [in] Handle for the component.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hFan

  • CTL_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

    • User does not have permissions to make these modifications.

ctlFanSetFixedSpeedMode

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlFanSetFixedSpeedMode(ctl_fan_handle_t hFan, const ctl_fan_speed_t *speed)

Configure the fan to rotate at a fixed speed (set mode to CTL_FAN_SPEED_MODE_FIXED)

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hFan – [in] Handle for the component.

  • speed – [in] The fixed fan speed setting

Returns:

ctlFanSetSpeedTableMode

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlFanSetSpeedTableMode(ctl_fan_handle_t hFan, const ctl_fan_speed_table_t *speedTable)

Configure the fan to adjust speed based on a temperature/speed table (set mode to CTL_FAN_SPEED_MODE_TABLE)

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hFan – [in] Handle for the component.

  • speedTable – [in] A table containing temperature/speed pairs.

Returns:

ctlFanGetState

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlFanGetState(ctl_fan_handle_t hFan, ctl_fan_speed_units_t units, int32_t *pSpeed)

Get current state of a fan - current mode and speed.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hFan – [in] Handle for the component.

  • units – [in] The units in which the fan speed should be returned.

  • pSpeed – [in,out] Will contain the current speed of the fan in the units requested. A value of -1 indicates that the fan speed cannot be measured.

Returns:

Fan Enums

ctl_fan_speed_mode_t

enum ctl_fan_speed_mode_t

Fan resource speed mode.

Values:

enumerator CTL_FAN_SPEED_MODE_DEFAULT

The fan speed is operating using the hardware default settings.

enumerator CTL_FAN_SPEED_MODE_FIXED

The fan speed is currently set to a fixed value.

enumerator CTL_FAN_SPEED_MODE_TABLE

The fan speed is currently controlled dynamically by hardware based on a temp/speed table.

enumerator CTL_FAN_SPEED_MODE_MAX

ctl_fan_speed_units_t

enum ctl_fan_speed_units_t

Fan speed units.

Values:

enumerator CTL_FAN_SPEED_UNITS_RPM

The fan speed is in units of revolutions per minute (rpm)

enumerator CTL_FAN_SPEED_UNITS_PERCENT

The fan speed is a percentage of the maximum speed of the fan.

enumerator CTL_FAN_SPEED_UNITS_MAX

Fan Structures

ctl_fan_speed_t

struct ctl_fan_speed_t

Fan speed.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

int32_t speed

[in,out] The speed of the fan. On output, a value of -1 indicates that there is no fixed fan speed setting.

ctl_fan_speed_units_t units

[in,out] The units that the fan speed is expressed in. On output, if fan speed is -1 then units should be ignored.

ctl_fan_temp_speed_t

struct ctl_fan_temp_speed_t

Fan temperature/speed pair.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint32_t temperature

[in,out] Temperature in degrees Celsius.

ctl_fan_speed_t speed

[in,out] The speed of the fan

ctl_fan_speed_table_t

struct ctl_fan_speed_table_t

Fan speed table.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

int32_t numPoints

[in,out] The number of valid points in the fan speed table. 0 means that there is no fan speed table configured. -1 means that a fan speed table is not supported by the hardware.

ctl_fan_temp_speed_t table[CTL_FAN_TEMP_SPEED_PAIR_COUNT]

[in,out] Array of temperature/fan speed pairs. The table is ordered based on temperature from lowest to highest.

ctl_fan_properties_t

struct ctl_fan_properties_t

Fan properties.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool canControl

[out] Indicates if software can control the fan speed assuming the user has permissions

uint32_t supportedModes

[out] Bitfield of supported fan configuration modes (1<<ctl_fan_speed_mode_t)

uint32_t supportedUnits

[out] Bitfield of supported fan speed units (1<<ctl_fan_speed_units_t)

int32_t maxRPM

[out] The maximum RPM of the fan. A value of -1 means that this property is unknown.

int32_t maxPoints

[out] The maximum number of points in the fan temp/speed table. A value of -1 means that this fan doesn’t support providing a temp/speed table.

ctl_fan_config_t

struct ctl_fan_config_t

Fan configuration.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_fan_speed_mode_t mode

[in,out] The fan speed mode (fixed, temp-speed table)

ctl_fan_speed_t speedFixed

[in,out] The current fixed fan speed setting

ctl_fan_speed_table_t speedTable

[out] A table containing temperature/speed pairs

Frequency

Frequency Functions

ctlEnumFrequencyDomains

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlEnumFrequencyDomains(ctl_device_adapter_handle_t hDAhandle, uint32_t *pCount, ctl_freq_handle_t *phFrequency)

Get handle of frequency domains.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hDAhandle – [in][release] Handle to display adapter

  • pCount – [in,out] pointer to the number of components of this type. if count is zero, then the driver shall update the value with the total number of components of this type that are available. if count is greater than the number of components of this type that are available, then the driver shall update the value with the correct number of components.

  • phFrequency – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pCount

ctlFrequencyGetProperties

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlFrequencyGetProperties(ctl_freq_handle_t hFrequency, ctl_freq_properties_t *pProperties)

Get frequency properties - available frequencies.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pProperties – [in,out] The frequency properties for the specified domain.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hFrequency

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pProperties

ctlFrequencyGetAvailableClocks

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlFrequencyGetAvailableClocks(ctl_freq_handle_t hFrequency, uint32_t *pCount, double *phFrequency)

Get available non-overclocked hardware clock frequencies for the frequency domain.

  • The list of available frequencies is returned in order of slowest to fastest.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hFrequency – [in] Device handle of the device.

  • pCount – [in,out] pointer to the number of frequencies. if count is zero, then the driver shall update the value with the total number of frequencies that are available. if count is greater than the number of frequencies that are available, then the driver shall update the value with the correct number of frequencies.

  • phFrequency – [in,out][optional][range(0, *pCount)] array of frequencies in units of MHz and sorted from slowest to fastest. if count is less than the number of frequencies that are available, then the driver shall only retrieve that number of frequencies.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hFrequency

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pCount

ctlFrequencyGetRange

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlFrequencyGetRange(ctl_freq_handle_t hFrequency, ctl_freq_range_t *pLimits)

Get current frequency limits.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pLimits – [in,out] The range between which the hardware can operate for the specified domain.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hFrequency

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pLimits

ctlFrequencySetRange

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlFrequencySetRange(ctl_freq_handle_t hFrequency, const ctl_freq_range_t *pLimits)

Set frequency range between which the hardware can operate.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pLimits – [in] The limits between which the hardware can operate for the specified domain.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hFrequency

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pLimits

  • CTL_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

    • User does not have permissions to make these modifications.

ctlFrequencyGetState

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlFrequencyGetState(ctl_freq_handle_t hFrequency, ctl_freq_state_t *pState)

Get current frequency state - frequency request, actual frequency, TDP limits.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pState – [in,out] Frequency state for the specified domain.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hFrequency

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pState

ctlFrequencyGetThrottleTime

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlFrequencyGetThrottleTime(ctl_freq_handle_t hFrequency, ctl_freq_throttle_time_t *pThrottleTime)

Get frequency throttle time.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hFrequency – [in] Handle for the component.

  • pThrottleTime – [in,out] Will contain a snapshot of the throttle time counters for the specified domain.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hFrequency

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pThrottleTime

Frequency Enums

ctl_freq_domain_t

enum ctl_freq_domain_t

Frequency domains.

Values:

enumerator CTL_FREQ_DOMAIN_GPU

GPU Core Domain.

enumerator CTL_FREQ_DOMAIN_MEMORY

Local Memory Domain.

enumerator CTL_FREQ_DOMAIN_MAX

ctl_freq_throttle_reason_flags_t

enum ctl_freq_throttle_reason_flag_t

Values:

enumerator CTL_FREQ_THROTTLE_REASON_FLAG_AVE_PWR_CAP

frequency throttled due to average power excursion (PL1)

enumerator CTL_FREQ_THROTTLE_REASON_FLAG_BURST_PWR_CAP

frequency throttled due to burst power excursion (PL2)

enumerator CTL_FREQ_THROTTLE_REASON_FLAG_CURRENT_LIMIT

frequency throttled due to current excursion (PL4)

enumerator CTL_FREQ_THROTTLE_REASON_FLAG_THERMAL_LIMIT

frequency throttled due to thermal excursion (T > TjMax)

enumerator CTL_FREQ_THROTTLE_REASON_FLAG_PSU_ALERT

frequency throttled due to power supply assertion

enumerator CTL_FREQ_THROTTLE_REASON_FLAG_SW_RANGE

frequency throttled due to software supplied frequency range

enumerator CTL_FREQ_THROTTLE_REASON_FLAG_HW_RANGE

frequency throttled due to a sub block that has a lower frequency range when it receives clocks

enumerator CTL_FREQ_THROTTLE_REASON_FLAG_MAX

Frequency Structures

ctl_freq_properties_t

struct ctl_freq_properties_t

Frequency properties.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_freq_domain_t type

[out] The hardware block that this frequency domain controls (GPU, memory, …)

bool canControl

[out] Indicates if software can control the frequency of this domain assuming the user has permissions

double min

[out] The minimum hardware clock frequency in units of MHz.

double max

[out] The maximum non-overclock hardware clock frequency in units of MHz.

ctl_freq_range_t

struct ctl_freq_range_t

Frequency range between which the hardware can operate. The limits can be above or below the hardware limits - the hardware will clamp appropriately.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

double min

[in,out] The min frequency in MHz below which hardware frequency management will not request frequencies. On input, setting to 0 will permit the frequency to go down to the hardware minimum. On output, a negative value indicates that no external minimum frequency limit is in effect.

double max

[in,out] The max frequency in MHz above which hardware frequency management will not request frequencies. On input, setting to 0 or a very big number will permit the frequency to go all the way up to the hardware maximum. On output, a negative number indicates that no external maximum frequency limit is in effect.

ctl_freq_state_t

struct ctl_freq_state_t

Frequency state.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

double currentVoltage

[out] Current voltage in Volts. A negative value indicates that this property is not known.

double request

[out] The current frequency request in MHz. A negative value indicates that this property is not known.

double tdp

[out] The maximum frequency in MHz supported under the current TDP conditions. This fluctuates dynamically based on the power and thermal limits of the part. A negative value indicates that this property is not known.

double efficient

[out] The efficient minimum frequency in MHz. A negative value indicates that this property is not known.

double actual

[out] The resolved frequency in MHz. A negative value indicates that this property is not known.

ctl_freq_throttle_reason_flags_t throttleReasons

[out] The reasons that the frequency is being limited by the hardware. Returns 0 (frequency not throttled) or a combination of ctl_freq_throttle_reason_flag_t.

ctl_freq_throttle_time_t

struct ctl_freq_throttle_time_t

Frequency throttle time snapshot.

  • Percent time throttled is calculated by taking two snapshots (s1, s2) and using the equation: throttled = (s2.throttleTime - s1.throttleTime) / (s2.timestamp - s1.timestamp)

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint64_t throttleTime

[out] The monotonic counter of time in microseconds that the frequency has been limited by the hardware.

uint64_t timestamp

[out] Microsecond timestamp when throttleTime was captured. This timestamp should only be used to calculate delta time between snapshots of this structure. Never take the delta of this timestamp with the timestamp from a different structure since they are not guaranteed to have the same base. The absolute value of the timestamp is only valid during within the application and may be different on the next execution.

Media

Media Functions

ctlGetSupportedVideoProcessingCapabilities

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetSupportedVideoProcessingCapabilities(ctl_device_adapter_handle_t hDAhandle, ctl_video_processing_feature_caps_t *pFeatureCaps)

Get Video Processing capabilities.

  • The application gets Video Processing properties

Parameters:

  • hDAhandle – [in][release] Handle to display adapter

  • pFeatureCaps – [in,out][release] Video Processing properties

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pFeatureCaps

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

ctlGetSetVideoProcessingFeature

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlGetSetVideoProcessingFeature(ctl_device_adapter_handle_t hDAhandle, ctl_video_processing_feature_getset_t *pFeature)

Get/Set Video Processing feature details.

  • Video Processing feature details

Parameters:

  • hDAhandle – [in][release] Handle to display adapter

  • pFeature – [in][release] Video Processing feature get/set parameter

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pFeature

  • CTL_RESULT_ERROR_UNSUPPORTED_VERSION - “Unsupported version”

Media Enums

ctl_video_processing_feature_t

enum ctl_video_processing_feature_t

Feature type.

Values:

enumerator CTL_VIDEO_PROCESSING_FEATURE_FILM_MODE_DETECTION

Film mode detection. Contains CTL_PROPERTY_VALUE_TYPE_BOOL ValueType.

enumerator CTL_VIDEO_PROCESSING_FEATURE_NOISE_REDUCTION

Noise reduction. Contains CTL_PROPERTY_VALUE_TYPE_CUSTOM type field using struct ctl_video_processing_noise_reduction_t.

enumerator CTL_VIDEO_PROCESSING_FEATURE_SHARPNESS

Sharpness. Contains CTL_PROPERTY_VALUE_TYPE_UINT32 ValueType.

enumerator CTL_VIDEO_PROCESSING_FEATURE_ADAPTIVE_CONTRAST_ENHANCEMENT

Adaptive contrast enhancement. Contains CTL_PROPERTY_VALUE_TYPE_CUSTOM type field using struct ctl_video_processing_adaptive_contrast_enhancement_t.

enumerator CTL_VIDEO_PROCESSING_FEATURE_SUPER_RESOLUTION

Super resolution. Contains CTL_PROPERTY_VALUE_TYPE_CUSTOM ValueType using ctl_video_processing_super_resolution_t. By defaut, Super resolution is not active, need application to activate it, please contact Intel for super resolution activation.

enumerator CTL_VIDEO_PROCESSING_FEATURE_STANDARD_COLOR_CORRECTION

Standard color correction. Controls Hue, Saturation, Contrast, Brightness. Contains CTL_PROPERTY_VALUE_TYPE_CUSTOM type field using struct ctl_video_processing_standard_color_correction_t.

enumerator CTL_VIDEO_PROCESSING_FEATURE_TOTAL_COLOR_CORRECTION

Total color correction. Controls Red, Green, Blue, Yellow, Cyan, Magenta. Contains CTL_PROPERTY_VALUE_TYPE_CUSTOM type field using struct ctl_video_processing_total_color_correction_t.

enumerator CTL_VIDEO_PROCESSING_FEATURE_SKIN_TONE_ENHANCEMENT

Skin tone enhancement. Contains CTL_PROPERTY_VALUE_TYPE_UINT32 ValueType.

enumerator CTL_VIDEO_PROCESSING_FEATURE_MAX

ctl_video_processing_super_resolution_flags_t

enum ctl_video_processing_super_resolution_flag_t

Values:

enumerator CTL_VIDEO_PROCESSING_SUPER_RESOLUTION_FLAG_DISABLE

Disable.

enumerator CTL_VIDEO_PROCESSING_SUPER_RESOLUTION_FLAG_ENABLE_DEFAULT_SCENARIO_MODE

Enable with default super resolution mode.

enumerator CTL_VIDEO_PROCESSING_SUPER_RESOLUTION_FLAG_ENABLE_CONFERENCE_SCENARIO_MODE

Super resolution mode targeted at video conference content.

enumerator CTL_VIDEO_PROCESSING_SUPER_RESOLUTION_FLAG_ENABLE_CAMERA_SCENARIO_MODE

Super resolution mode targeted at camera capture content (e.g. security camera)

enumerator CTL_VIDEO_PROCESSING_SUPER_RESOLUTION_FLAG_MAX

Media Structures

ctl_video_processing_super_resolution_info_t

struct ctl_video_processing_super_resolution_info_t

Super Resolution feature details structure to be used with SUPER_RESOLUTION.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_video_processing_super_resolution_flags_t super_resolution_flag

[in,out] SUPER_RESOLUTION flag

ctl_property_info_uint_t super_resolution_range_in_width

[in,out] The range of input width information(min, max, default and step size)which super resolution is capable of supporting.

ctl_property_info_uint_t super_resolution_range_in_height

[in,out] The range of input height information(min, max, default and step size)which super resolution is capable of supporting.

uint32_t ReservedFields[16]

[out] Reserved field of 64 bytes

ctl_video_processing_super_resolution_t

struct ctl_video_processing_super_resolution_t

Super Resolution Get/Set structure to be used with SUPER_RESOLUTION.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_video_processing_super_resolution_flags_t super_resolution_flag

[in,out] SUPER_RESOLUTION flag

bool super_resolution_max_in_enabled

[in,out] The enabling of maximum input width and height limition. If enabled, super resolution will always take effect if the input resolution is smaller than the below specified max resolution; otherwise, super_resolution_max_in_width and super_resolution_max_in_height will be ignored

uint32_t super_resolution_max_in_width

[in,out] The maximum input width limition value setting which super resolution will be allowed to enabled.

uint32_t super_resolution_max_in_height

[in,out] The maximum input height limiation value setting which super resolution will be allowed to enabled.

bool super_resolution_reboot_reset

[in,out] Resetting of super resolution after rebooting.

uint32_t ReservedFields[15]

[out] Reserved field of 60 bytes

char ReservedBytes[3]

[out] Reserved field of 3 bytes

ctl_video_processing_noise_reduction_info_t

struct ctl_video_processing_noise_reduction_info_t

Noise Reduction feature details structure to be used with NOISE_REDUCTION.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_property_info_uint_t noise_reduction

[in,out] Noise reduction min, max, default and step size information

bool noise_reduction_auto_detect_supported

[in,out] Noise reduction Auto Detect is supported; only valid if NOISE_REDUCTION is enabled. If enabled, noise reduction level is automatically determined and set value is not used.

ctl_property_info_boolean_t noise_reduction_auto_detect

[in,out] Noise reduction auto detect default information

uint32_t ReservedFields[16]

[out] Reserved field of 64 bytes

ctl_video_processing_noise_reduction_t

struct ctl_video_processing_noise_reduction_t

Noise Reduction Get/Set structure to be used with NOISE_REDUCTION.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_property_uint_t noise_reduction

[in,out] Noise reduction enable and value setting

ctl_property_boolean_t noise_reduction_auto_detect

[in,out] Noise reduction auto detect setting

uint32_t ReservedFields[16]

[out] Reserved field of 64 bytes

ctl_video_processing_adaptive_contrast_enhancement_info_t

struct ctl_video_processing_adaptive_contrast_enhancement_info_t

Adaptive Contrast Enhancement feature details structure to be used with ADAPTIVE_CONTRAST_ENHANCEMENT.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_property_info_uint_t adaptive_contrast_enhancement

[in,out] Adaptive Contrast Enhancement min, max, default and step size information

bool adaptive_contrast_enhancement_coexistence_supported

[in,out] Adaptive contrast enhancement coexistance is supported; only valid if ADAPTIVE_CONTRAST_ENHANCEMENT is enabled. If enabled, Video adaptive contrast ehancement will be allowed to be enabled and coexist with Display adaptive contrast ehancement feature.

ctl_property_info_boolean_t adaptive_contrast_enhancement_coexistence

[in,out] Adaptive contrast enhancement coexistence default information

uint32_t ReservedFields[16]

[out] Reserved field of 64 bytes

ctl_video_processing_adaptive_contrast_enhancement_t

struct ctl_video_processing_adaptive_contrast_enhancement_t

Adaptive Contrast Enhancement Get/Set structure to be used with ADAPTIVE_CONTRAST_ENHANCEMENT.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_property_uint_t adaptive_contrast_enhancement

[in,out] Adaptive Contrast Enhancement enable and value setting

ctl_property_boolean_t adaptive_contrast_enhancement_coexistence

[in,out] Adaptive contrast enhancement coexistance setting

uint32_t ReservedFields[16]

[out] Reserved field of 64 bytes

ctl_video_processing_standard_color_correction_info_t

struct ctl_video_processing_standard_color_correction_info_t

Standard Color Correction feature details structure to be used with STANDARD_COLOR_CORRECTION.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool standard_color_correction_default_enable

[in,out] STANDARD_COLOR_CORRECTION default enable setting. This global settings controls all of Hue, Saturation, Contrast, Brightness enabling. Individual Enable controls shall be ignored.

ctl_property_info_float_t brightness

[in,out] Brightness min, max, default and step size information

ctl_property_info_float_t contrast

[in,out] Contrast min, max, default and step size information

ctl_property_info_float_t hue

[in,out] Hue min, max, default and step size information

ctl_property_info_float_t saturation

[in,out] Saturation min, max, default and step size information

uint32_t ReservedFields[16]

[out] Reserved field of 64 bytes

ctl_video_processing_standard_color_correction_t

struct ctl_video_processing_standard_color_correction_t

Standard Color Correction Get/Set structure to be used with STANDARD_COLOR_CORRECTION.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool standard_color_correction_enable

[in,out] STANDARD_COLOR_CORRECTION enable setting. This global setting controls all of Hue, Saturation, Contrast, Brightness enabling.

float brightness

[in,out] Brightness value

float contrast

[in,out] Contrast value

float hue

[in,out] Hue value

float saturation

[in,out] Saturation value

uint32_t ReservedFields[16]

[out] Reserved field of 64 bytes

ctl_video_processing_total_color_correction_info_t

struct ctl_video_processing_total_color_correction_info_t

Total Color Correction Get/Set structure to be used with TOTAL_COLOR_CORRECTION.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool total_color_correction_default_enable

[in,out] TOTAL_COLOR_CORRECTION enable setting. This global setting controls all of Red, Green, Blue, Yellow, Cyan, Magenta enabling. Individual Enable controls shall be ignored.

ctl_property_info_uint_t red

[in,out] Red min, max, default and step size information

ctl_property_info_uint_t green

[in,out] Green min, max, default and step size information

ctl_property_info_uint_t blue

[in,out] Blue min, max, default and step size information

ctl_property_info_uint_t yellow

[in,out] Yellow min, max, default and step size information

ctl_property_info_uint_t cyan

[in,out] Cyan min, max, default and step size information

ctl_property_info_uint_t magenta

[in,out] Magenta min, max, default and step size information

uint32_t ReservedFields[16]

[out] Reserved field of 64 bytes

ctl_video_processing_total_color_correction_t

struct ctl_video_processing_total_color_correction_t

Total Color Correction Get/Set structure to be used with TOTAL_COLOR_CORRECTION.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool total_color_correction_enable

[in,out] TOTAL_COLOR_CORRECTION enable setting. This global setting controls all of Red, Green, Blue, Yellow, Cyan, Magenta enabling.

uint32_t red

[in,out] Red value

uint32_t green

[in,out] Green value

uint32_t blue

[in,out] Blue value

uint32_t yellow

[in,out] Yellow value

uint32_t cyan

[in,out] Cyan value

uint32_t magenta

[in,out] Magenta value

uint32_t ReservedFields[16]

[out] Reserved field of 64 bytes

ctl_video_processing_feature_details_t

struct ctl_video_processing_feature_details_t

Video Processing feature details which will have range supported and default values.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_video_processing_feature_t FeatureType

[out] Video processing feature type

ctl_property_value_type_t ValueType

[out] Type of value

ctl_property_info_t Value

[out] Union of various type of values for Video Processing features. For enum types this can be noise reduction, color control etc. This member is valid iff ValueType is not CTL_PROPERTY_VALUE_TYPE_CUSTOM

int32_t CustomValueSize

[in] CustomValue buffer size

void *pCustomValue

[in,out] Pointer to a custom structure. Features that use CustomType, after the first query for all of the supported features the user needs to allocate this buffer and then query again just this specific feature for the structure to be filled in. Caller should allocate this buffer with known custom feature structure size. This member is valid iff ValueType is CTL_PROPERTY_VALUE_TYPE_CUSTOM.

uint32_t ReservedFields[16]

[out] Reserved field of 64 bytes

ctl_video_processing_feature_caps_t

struct ctl_video_processing_feature_caps_t

Video Processing features which are controllable.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint32_t NumSupportedFeatures

[in,out] Number of elements in supported features array

ctl_video_processing_feature_details_t *pFeatureDetails

[in,out] Array of supported features and their details

uint32_t ReservedFields[16]

[out] Reserved field of 64 bytes

ctl_video_processing_feature_getset_t

struct ctl_video_processing_feature_getset_t

Video Processing feature for get/set.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_video_processing_feature_t FeatureType

[in] Features interested in

char *ApplicationName

[in] Application name for which the property type is applicable. If this is an empty string then this will get/set global settings for the given adapter. Note that this should contain only the name of the application and not the system specific path. [This is not currently supported and should be an empty string.]

int8_t ApplicationNameLength

[in] Length of ApplicationName string

bool bSet

[in] Set this if it’s a set call

ctl_property_value_type_t ValueType

[in] Type of value. Caller has to ensure it provides the right value type which decides how one read the union structure below

ctl_property_t Value

[in,out] Union of various type of values for Video Processing features. For enum types this can be noise reduction, color control etc. This member is valid iff ValueType is not CTL_PROPERTY_VALUE_TYPE_CUSTOM

int32_t CustomValueSize

[in] CustomValue buffer size. For a feature requiring custom struct, caller will know of it upfront the struct to use based on the feautre and can provide the right size info here

void *pCustomValue

[in,out] Pointer to a custom structure. Caller should allocate this buffer with known custom feature structure size. This member is valid iff ValueType is CTL_PROPERTY_VALUE_TYPE_CUSTOM

uint32_t ReservedFields[16]

[out] Reserved field of 64 bytes

Memory

Memory Functions

ctlEnumMemoryModules

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlEnumMemoryModules(ctl_device_adapter_handle_t hDAhandle, uint32_t *pCount, ctl_mem_handle_t *phMemory)

Get handle of memory modules.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hDAhandle – [in][release] Handle to display adapter

  • pCount – [in,out] pointer to the number of components of this type. if count is zero, then the driver shall update the value with the total number of components of this type that are available. if count is greater than the number of components of this type that are available, then the driver shall update the value with the correct number of components.

  • phMemory – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pCount

ctlMemoryGetProperties

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlMemoryGetProperties(ctl_mem_handle_t hMemory, ctl_mem_properties_t *pProperties)

Get memory properties.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hMemory – [in] Handle for the component.

  • pProperties – [in,out] Will contain memory properties.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hMemory

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pProperties

ctlMemoryGetState

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlMemoryGetState(ctl_mem_handle_t hMemory, ctl_mem_state_t *pState)

Get memory state - health, allocated.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hMemory – [in] Handle for the component.

  • pState – [in,out] Will contain the current health and allocated memory.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hMemory

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pState

ctlMemoryGetBandwidth

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlMemoryGetBandwidth(ctl_mem_handle_t hMemory, ctl_mem_bandwidth_t *pBandwidth)

Get memory bandwidth.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hMemory – [in] Handle for the component.

  • pBandwidth – [in,out] Will contain the current health, free memory, total memory size.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hMemory

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pBandwidth

  • CTL_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

    • User does not have permissions to query this telemetry.

Memory Enums

ctl_mem_type_t

enum ctl_mem_type_t

Memory module types.

Values:

enumerator CTL_MEM_TYPE_HBM

HBM memory.

enumerator CTL_MEM_TYPE_DDR

DDR memory.

enumerator CTL_MEM_TYPE_DDR3

DDR3 memory.

enumerator CTL_MEM_TYPE_DDR4

DDR4 memory.

enumerator CTL_MEM_TYPE_DDR5

DDR5 memory.

enumerator CTL_MEM_TYPE_LPDDR

LPDDR memory.

enumerator CTL_MEM_TYPE_LPDDR3

LPDDR3 memory.

enumerator CTL_MEM_TYPE_LPDDR4

LPDDR4 memory.

enumerator CTL_MEM_TYPE_LPDDR5

LPDDR5 memory.

enumerator CTL_MEM_TYPE_GDDR4

GDDR4 memory.

enumerator CTL_MEM_TYPE_GDDR5

GDDR5 memory.

enumerator CTL_MEM_TYPE_GDDR5X

GDDR5X memory.

enumerator CTL_MEM_TYPE_GDDR6

GDDR6 memory.

enumerator CTL_MEM_TYPE_GDDR6X

GDDR6X memory.

enumerator CTL_MEM_TYPE_GDDR7

GDDR7 memory.

enumerator CTL_MEM_TYPE_UNKNOWN

UNKNOWN memory.

enumerator CTL_MEM_TYPE_MAX

ctl_mem_loc_t

enum ctl_mem_loc_t

Memory module location.

Values:

enumerator CTL_MEM_LOC_SYSTEM

System memory.

enumerator CTL_MEM_LOC_DEVICE

On board local device memory.

enumerator CTL_MEM_LOC_MAX

Memory Structures

ctl_mem_properties_t

struct ctl_mem_properties_t

Memory properties.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_mem_type_t type

[out] The memory type

ctl_mem_loc_t location

[out] Location of this memory (system, device)

uint64_t physicalSize

[out] Physical memory size in bytes. A value of 0 indicates that this property is not known. However, a call to ctlMemoryGetState() will correctly return the total size of usable memory.

int32_t busWidth

[out] Width of the memory bus. A value of -1 means that this property is unknown.

int32_t numChannels

[out] The number of memory channels. A value of -1 means that this property is unknown.

ctl_mem_state_t

struct ctl_mem_state_t

Memory state - health, allocated.

  • Percent allocation is given by 100 * (size - free / size.

  • Percent free is given by 100 * free / size.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint64_t free

[out] The free memory in bytes

uint64_t size

[out] The total allocatable memory in bytes (can be less than ctl_mem_properties_t.physicalSize)

ctl_mem_bandwidth_t

struct ctl_mem_bandwidth_t

Memory bandwidth.

  • Percent bandwidth is calculated by taking two snapshots (s1, s2) and using the equation: bw = 10^6 * ((s2.readCounter - s1.readCounter) + (s2.writeCounter - s1.writeCounter)) / (s2.maxBandwidth * (s2.timestamp - s1.timestamp))

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint64_t maxBandwidth

[out] Current maximum bandwidth in units of bytes/sec

uint64_t timestamp

[out] The timestamp (in microseconds) when these measurements were sampled. This timestamp should only be used to calculate delta time between snapshots of this structure. Never take the delta of this timestamp with the timestamp from a different structure since they are not guaranteed to have the same base. The absolute value of the timestamp is only valid during within the application and may be different on the next execution.

uint64_t readCounter

[out] Total bytes read from memory. Supported only for Version > 0

uint64_t writeCounter

[out] Total bytes written to memory. Supported only for Version > 0

Overclock

Overclock Functions

ctlOverclockGetProperties

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockGetProperties(ctl_device_adapter_handle_t hDeviceHandle, ctl_oc_properties_t *pOcProperties)

Get overclock properties - available properties.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • pOcProperties – [in,out] The overclocking properties for the specified domain.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pOcProperties

ctlOverclockWaiverSet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockWaiverSet(ctl_device_adapter_handle_t hDeviceHandle)

Overclock Waiver - Warranty Waiver.

  • Most of the overclock functions will return an error if the waiver is not set. This is because most overclock settings will increase the electric/thermal stress on the part and thus reduce its lifetime.

  • By setting the waiver, the user is indicate that they are accepting a reduction in the lifetime of the part.

  • It is the responsibility of overclock applications to notify each user at least once with a popup of the dangers and requiring acceptance.

  • Only once the user has accepted should this function be called by the application.

  • It is acceptable for the application to cache the user choice and call this function on future executions without issuing the popup.

Parameters:

hDeviceHandle – [in][release] Handle to display adapter

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

ctlOverclockGpuFrequencyOffsetGet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockGpuFrequencyOffsetGet(ctl_device_adapter_handle_t hDeviceHandle, double *pOcFrequencyOffset)

Get the Overclock Frequency Offset for the GPU in MHz.

  • Determine the current frequency offset in effect (refer to ctlOverclockGpuFrequencyOffsetSet() for details).

  • The value returned may be different from the value that was previously set by the application depending on hardware limitations or if the function ctlOverclockGpuFrequencyOffsetSet() has been called or another application that has changed the value.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • pOcFrequencyOffset – [in,out] The Turbo Overclocking Frequency Desired in MHz.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pOcFrequencyOffset

ctlOverclockGpuFrequencyOffsetSet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockGpuFrequencyOffsetSet(ctl_device_adapter_handle_t hDeviceHandle, double ocFrequencyOffset)

Set the Overclock Frequency Offset for the GPU in MHZ.

  • The purpose of this function is to increase/decrease the frequency at which typical workloads will run within the same thermal budget.

  • The frequency offset is expressed in units of ±1MHz.

  • The actual operating frequency for each workload is not guaranteed to change exactly by the specified offset.

  • For positive frequency offsets, the factory maximum frequency may increase by up to the specified amount.

  • For negative frequency offsets, the overclock waiver must have been set since this can result in running the part at voltages beyond the part warrantee limits. An error is returned if the waiver has not been set.

  • Specifying large values for the frequency offset can lead to instability. It is recommended that changes are made in small increments and stability/performance measured running intense GPU workloads before increasing further.

  • This setting is not persistent through system reboots or driver resets/hangs. It is up to the overclock application to reapply the settings in those cases.

  • This setting can cause system/device instability. It is up to the overclock application to detect if the system has rebooted unexpectedly or the device was restarted. When this occurs, the application should not reapply the overclock settings automatically but instead return to previously known good settings or notify the user that the settings are not being applied.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • ocFrequencyOffset – [in] The Turbo Overclocking Frequency Desired in MHz.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

ctlOverclockGpuVoltageOffsetGet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockGpuVoltageOffsetGet(ctl_device_adapter_handle_t hDeviceHandle, double *pOcVoltageOffset)

Get the Overclock Gpu Voltage Offset in mV.

  • Determine the current voltage offset in effect on the hardware (refer to ctlOverclockGpuVoltageOffsetSet for details).

  • The value returned may be different from the value that was previously set by the application depending on hardware limitations or if the function ctlOverclockGpuVoltageOffsetSet has been called or another application that has changed the value.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • pOcVoltageOffset – [in,out] The Turbo Overclocking Frequency Desired in mV.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pOcVoltageOffset

ctlOverclockGpuVoltageOffsetSet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockGpuVoltageOffsetSet(ctl_device_adapter_handle_t hDeviceHandle, double ocVoltageOffset)

Set the Overclock Gpu Voltage Offset in mV.

  • The purpose of this function is to attempt to run the GPU up to higher voltages beyond the part warrantee limits. This can permit running at even higher frequencies than can be obtained using the frequency offset setting, but at the risk of reducing the lifetime of the part.

  • The voltage offset is expressed in units of ±millivolts with values permitted down to a resolution of 1 millivolt.

  • The overclock waiver must be set before calling this function otherwise and error will be returned.

  • There is no guarantee that a workload can operate at the higher frequencies permitted by this setting. Significantly more heat will be generated at these high frequencies/voltages which will necessitate a good cooling solution.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • ocVoltageOffset – [in] The Turbo Overclocking Frequency Desired in mV.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

ctlOverclockGpuLockGet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockGpuLockGet(ctl_device_adapter_handle_t hDeviceHandle, ctl_oc_vf_pair_t *pVfPair)

Gets the Locked GPU Voltage for Overclocking in mV.

  • The purpose of this function is to determine if the current values of the frequency/voltage lock.

  • If the lock is not currently active, will return 0 for frequency and voltage.

  • Note that the operating frequency/voltage may be lower than these settings if power/thermal limits are exceeded.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • pVfPair – [out] The current locked voltage and frequency.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pVfPair

ctlOverclockGpuLockSet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockGpuLockSet(ctl_device_adapter_handle_t hDeviceHandle, ctl_oc_vf_pair_t vFPair)

Locks the GPU voltage for Overclocking in mV.

  • The purpose of this function is to provide an interface for scanners to lock the frequency and voltage to fixed values.

  • The frequency is expressed in units of MHz with a resolution of 1MHz.

  • The voltage is expressed in units of ±millivolts with values permitted down to a resolution of 1 millivolt.

  • The overclock waiver must be set since fixing the voltage at a high value puts unnecessary stress on the part.

  • The actual frequency may reduce depending on power/thermal limitations.

  • Requesting a frequency and/or voltage of 0 will return the hardware to dynamic frequency/voltage management with any previous frequency offset or voltage offset settings reapplied.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • vFPair – [in] The current locked voltage and frequency.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

ctlOverclockVramFrequencyOffsetGet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockVramFrequencyOffsetGet(ctl_device_adapter_handle_t hDeviceHandle, double *pOcFrequencyOffset)

Get the current Vram Frequency Offset in GT/s.

  • The purpose of this function is to return the current VRAM frequency offset in units of GT/s.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • pOcFrequencyOffset – [in,out] The current Memory Frequency in GT/s.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pOcFrequencyOffset

ctlOverclockVramFrequencyOffsetSet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockVramFrequencyOffsetSet(ctl_device_adapter_handle_t hDeviceHandle, double ocFrequencyOffset)

Set the desired Vram frquency Offset in GT/s.

  • The purpose of this function is to increase/decrease the frequency of VRAM.

  • The frequency offset is expressed in units of GT/s with a minimum step size given by ctlOverclockGetProperties.

  • The actual operating frequency for each workload is not guaranteed to change exactly by the specified offset.

  • The waiver must be set using clibOverclockWaiverSet() before this function can be called.

  • This setting is not persistent through system reboots or driver resets/hangs. It is up to the overclock application to reapply the settings in those cases.

  • This setting can cause system/device instability. It is up to the overclock application to detect if the system has rebooted unexpectedly or the device was restarted. When this occurs, the application should not reapply the overclock settings automatically but instead return to previously known good settings or notify the user that the settings are not being applied.

  • If the memory controller doesn’t support changes to frequency on the fly, one of the following return codes will be given:

  • CTL_RESULT_ERROR_RESET_DEVICE_REQUIRED: The requested memory overclock will be applied when the device is reset or the system is rebooted. In this case, the overclock software should check if the overclock request was applied after the reset/reboot. If it was and when the overclock application shuts down gracefully and if the overclock application wants the setting to be persistent, the application should request the same overclock settings again so that they will be applied on the next reset/reboot. If this is not done, then every time the device is reset and overclock is requested, the device needs to be reset a second time.

  • CTL_RESULT_ERROR_FULL_REBOOT_REQUIRED: The requested memory overclock will be applied when the system is rebooted. In this case, the overclock software should check if the overclock request was applied after the reboot. If it was and when the overclock application shuts down gracefully and if the overclock application wants the setting to be persistent, the application should request the same overclock settings again so that they will be applied on the next reset/reboot. If this is not done and the overclock setting is requested after the reboot has occurred, a second reboot will be required.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • ocFrequencyOffset – [in] The desired Memory Frequency in GT/s.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

ctlOverclockVramVoltageOffsetGet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockVramVoltageOffsetGet(ctl_device_adapter_handle_t hDeviceHandle, double *pVoltage)

Get the Overclock Vram Voltage Offset in mV.

  • The purpose of this function is to increase/decrease the voltage of VRAM.

  • The voltage offset is expressed in units of millivolts with a minimum step size given by ctlOverclockGetProperties.

  • The waiver must be set using ctlOverclockWaiverSet before this function can be called.

  • This setting is not persistent through system reboots or driver resets/hangs. It is up to the overclock application to reapply the settings in those cases.

  • This setting can cause system/device instability. It is up to the overclock application to detect if the system has rebooted unexpectedly or the device was restarted. When this occurs, the application should not reapply the overclock settings automatically but instead return to previously known good settings or notify the user that the settings are not being applied.

  • If the memory controller doesn’t support changes to voltage on the fly, one of the following return codes will be given:

  • CTL_RESULT_ERROR_RESET_DEVICE_REQUIRED: The requested memory overclock will be applied when the device is reset or the system is rebooted. In this case, the overclock software should check if the overclock request was applied after the reset/reboot. If it was and when the overclock application shuts down gracefully and if the overclock application wants the setting to be persistent, the application should request the same overclock settings again so that they will be applied on the next reset/reboot. If this is not done, then every time the device is reset and overclock is requested, the device needs to be reset a second time.

  • CTL_RESULT_ERROR_FULL_REBOOT_REQUIRED: The requested memory overclock will be applied when the system is rebooted. In this case, the overclock software should check if the overclock request was applied after the reboot. If it was and when the overclock application shuts down gracefully and if the overclock application wants the setting to be persistent, the application should request the same overclock settings again so that they will be applied on the next reset/reboot. If this is not done and the overclock setting is requested after the reboot has occurred, a second reboot will be required.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • pVoltage – [out] The current locked voltage in mV.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pVoltage

ctlOverclockVramVoltageOffsetSet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockVramVoltageOffsetSet(ctl_device_adapter_handle_t hDeviceHandle, double voltage)

Set the Overclock Vram Voltage Offset in mV.

  • The purpose of this function is to set the maximum sustained power limit. If the average GPU power averaged over a few seconds exceeds this value, the frequency of the GPU will be throttled.

  • Set a value of 0 to disable this power limit. In this case, the GPU frequency will not throttle due to average power but may hit other limits.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • voltage – [in] The voltage to be locked in mV.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

ctlOverclockPowerLimitGet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockPowerLimitGet(ctl_device_adapter_handle_t hDeviceHandle, double *pSustainedPowerLimit)

Get the sustained power limit in mW.

  • The purpose of this function is to read the current sustained power limit.

  • A value of 0 means that the limit is disabled - the GPU frequency can run as high as possible until other limits are hit.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • pSustainedPowerLimit – [in,out] The current sustained power limit in mW.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pSustainedPowerLimit

ctlOverclockPowerLimitSet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockPowerLimitSet(ctl_device_adapter_handle_t hDeviceHandle, double sustainedPowerLimit)

Set the sustained power limit in mW.

  • The purpose of this function is to set the maximum sustained power limit. If the average GPU power averaged over a few seconds exceeds this value, the frequency of the GPU will be throttled.

  • Set a value of 0 to disable this power limit. In this case, the GPU frequency will not throttle due to average power but may hit other limits.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • sustainedPowerLimit – [in] The desired sustained power limit in mW.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

ctlOverclockTemperatureLimitGet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockTemperatureLimitGet(ctl_device_adapter_handle_t hDeviceHandle, double *pTemperatureLimit)

Get the current temperature limit in Celsius.

  • The purpose of this function is to read the current thermal limit.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • pTemperatureLimit – [in,out] The current temperature limit in Celsius.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pTemperatureLimit

ctlOverclockTemperatureLimitSet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockTemperatureLimitSet(ctl_device_adapter_handle_t hDeviceHandle, double temperatureLimit)

Set the temperature limit in Celsius.

  • The purpose of this function is to change the maximum thermal limit. When the GPU temperature exceeds this value, the GPU frequency will be throttled.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • temperatureLimit – [in] The desired temperature limit in Celsius.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

ctlPowerTelemetryGet

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlPowerTelemetryGet(ctl_device_adapter_handle_t hDeviceHandle, ctl_power_telemetry_t *pTelemetryInfo)

Get Power Telemetry.

  • Limited rate of 50 ms, any call under 50 ms will return the same information.

Parameters:

  • hDeviceHandle – [in][release] Handle to display adapter

  • pTelemetryInfo – [out] The overclocking properties for the specified domain.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pTelemetryInfo

ctlOverclockResetToDefault

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlOverclockResetToDefault(ctl_device_adapter_handle_t hDeviceHandle)

Reset all Overclock Settings to stock.

  • Reset all Overclock setting to default using single API call

  • This request resets any changes made to GpuFrequencyOffset, GpuVoltageOffset, PowerLimit, TemperatureLimit, GpuLock

  • This Doesn’t reset any Fan Curve Changes. It can be reset using ctlFanSetDefaultMode

Parameters:

hDeviceHandle – [in][release] Handle to display adapter

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDeviceHandle

Overclock Enums

ctl_psu_type_t

enum ctl_psu_type_t

PSU Type.

Values:

enumerator CTL_PSU_TYPE_PSU_NONE

Type of the PSU is unknown.

enumerator CTL_PSU_TYPE_PSU_PCIE

Type of the PSU is PCIe.

enumerator CTL_PSU_TYPE_PSU_6PIN

Type of the PSU is 6 PIN.

enumerator CTL_PSU_TYPE_PSU_8PIN

Type of the PSU is 8 PIN.

enumerator CTL_PSU_TYPE_MAX

Overclock Structures

ctl_oc_telemetry_item_t

struct ctl_oc_telemetry_item_t

Telemetry Item for each telemetry property.

Public Members

bool bSupported

[out] Indicates if the value is supported.

ctl_units_t units

[out] Indicates the units of the value.

ctl_data_type_t type

[out] Indicates the data type.

ctl_data_value_t value

[out] The value of type ctl_data_type_t and units ctl_units_t.

ctl_oc_control_info_t

struct ctl_oc_control_info_t

Overclocking Control Information.

  • Whether the device supports overclocking.

  • The bSupported/bRelative/bReference/units/min/max/step/default/reference values for the available overclock controls

  • The idea is to facilitate the way the applications present overclock settings to the user. If bSupported is false, the corresponding overclock control is not supported

  • The setting units will be an enum that enables the application to know the units for the control setting e.g. MHz. The min and max settings give the limits for the control.

  • The step setting gives the minimum change in the control value (plus or minus) - if a control is not changed by at least this amount, the hardware may round up or down.

  • The default values gives the manufacturing setting for the control. Some controls such as frequency offset and voltage offset are relative; in this case, bRelative will be true, otherwise the control settings are absolute values.

  • For relative controls and if bReference is true, the reference value gives the absolute value at the default setting.

  • If bReference is false, the absolute value of the default setting is no not known and it is probably better to display the setting to users as percentage offsets.

Public Members

bool bSupported

[out] Indicates if the values are known.

bool bRelative

[out] Indicates if the values are meant to be taken as relative values instead of absolut values.

bool bReference

[out] For relative values, this indicates if a reference is available.

ctl_units_t units

[out] Units for the values.

double min

[out] Minimum Value.

double max

[out] Maximum Value.

double step

[out] Step Value.

double Default

[out] Default Value.

double reference

[out] Reference Value if the bReference is true.

ctl_oc_properties_t

struct ctl_oc_properties_t

Overclock properties.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool bSupported

[out] Indicates if the adapter supports overclocking.

ctl_oc_control_info_t gpuFrequencyOffset

[out] related to function ctlOverclockGpuFrequencyOffsetSet

ctl_oc_control_info_t gpuVoltageOffset

[out] related to function ctlOverclockGpuVoltageOffsetSet

ctl_oc_control_info_t vramFrequencyOffset

[out] Property Field Deprecated / No Longer Supported

ctl_oc_control_info_t vramVoltageOffset

[out] Property Field Deprecated / No Longer Supported

ctl_oc_control_info_t powerLimit

[out] related to function ctlOverclockPowerLimitSet

ctl_oc_control_info_t temperatureLimit

[out] related to function ctlOverclockTemperatureLimitSet

ctl_oc_vf_pair_t

struct ctl_oc_vf_pair_t

Overclock Voltage Frequency Pair.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

double Voltage

[in,out] Voltage component of the pair in mV.

double Frequency

[in,out] Frequency component of the pair in MHz.

ctl_psu_info_t

struct ctl_psu_info_t

PSU Info.

Public Members

bool bSupported

[out] Indicates if this PSU entry is supported.

ctl_psu_type_t psuType

[out] Type of the PSU.

ctl_oc_telemetry_item_t energyCounter

[out] Snapshot of the monotonic energy counter maintained by hardware. It measures the total energy consumed this power source. By taking the delta between two snapshots and dividing by the delta time in seconds, an application can compute the average power.

ctl_oc_telemetry_item_t voltage

[out] Instantaneous snapshot of the voltage of this power source.

ctl_power_telemetry_t

struct ctl_power_telemetry_t

Power Telemetry.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_oc_telemetry_item_t timeStamp

[out] Snapshot of the timestamp counter that measures the total time since Jan 1, 1970 UTC. It is a decimal value in seconds with a minimum accuracy of 1 millisecond.

ctl_oc_telemetry_item_t gpuEnergyCounter

[out] Snapshot of the monotonic energy counter maintained by hardware. It measures the total energy consumed by the GPU chip. By taking the delta between two snapshots and dividing by the delta time in seconds, an application can compute the average power.

ctl_oc_telemetry_item_t gpuVoltage

[out] Instantaneous snapshot of the voltage feeding the GPU chip. It is measured at the power supply output - chip input will be lower.

ctl_oc_telemetry_item_t gpuCurrentClockFrequency

[out] Instantaneous snapshot of the GPU chip frequency.

ctl_oc_telemetry_item_t gpuCurrentTemperature

[out] Instantaneous snapshot of the GPU chip temperature, read from the sensor reporting the highest value.

ctl_oc_telemetry_item_t globalActivityCounter

[out] Snapshot of the monotonic global activity counter. It measures the time in seconds (accurate down to 1 millisecond) that any GPU engine is busy. By taking the delta between two snapshots and dividing by the delta time in seconds, an application can compute the average percentage utilization of the GPU..

ctl_oc_telemetry_item_t renderComputeActivityCounter

[out] Snapshot of the monotonic 3D/compute activity counter. It measures the time in seconds (accurate down to 1 millisecond) that any 3D render/compute engine is busy. By taking the delta between two snapshots and dividing by the delta time in seconds, an application can compute the average percentage utilization of all 3D render/compute blocks in the GPU.

ctl_oc_telemetry_item_t mediaActivityCounter

[out] Snapshot of the monotonic media activity counter. It measures the time in seconds (accurate down to 1 millisecond) that any media engine is busy. By taking the delta between two snapshots and dividing by the delta time in seconds, an application can compute the average percentage utilization of all media blocks in the GPU.

bool gpuPowerLimited

[out] Instantaneous indication that the desired GPU frequency is being throttled because the GPU chip is exceeding the maximum power limits. Increasing the power limits using ctlOverclockPowerLimitSet() is one way to remove this limitation.

bool gpuTemperatureLimited

[out] Instantaneous indication that the desired GPU frequency is being throttled because the GPU chip is exceeding the temperature limits. Increasing the temperature limits using ctlOverclockTemperatureLimitSet() is one way to reduce this limitation. Improving the cooling solution is another way.

bool gpuCurrentLimited

[out] Instantaneous indication that the desired GPU frequency is being throttled because the GPU chip has exceeded the power supply current limits. A better power supply is required to reduce this limitation.

bool gpuVoltageLimited

[out] Instantaneous indication that the GPU frequency cannot be increased because the voltage limits have been reached. Increase the voltage offset using ctlOverclockGpuVoltageOffsetSet() is one way to reduce this limitation.

bool gpuUtilizationLimited

[out] Instantaneous indication that due to lower GPU utilization, the hardware has lowered the GPU frequency.

ctl_oc_telemetry_item_t vramEnergyCounter

[out] Snapshot of the monotonic energy counter maintained by hardware. It measures the total energy consumed by the local memory modules. By taking the delta between two snapshots and dividing by the delta time in seconds, an application can compute the average power.

ctl_oc_telemetry_item_t vramVoltage

[out] Instantaneous snapshot of the voltage feeding the memory modules.

ctl_oc_telemetry_item_t vramCurrentClockFrequency

[out] Instantaneous snapshot of the raw clock frequency driving the memory modules.

ctl_oc_telemetry_item_t vramCurrentEffectiveFrequency

[out] Instantaneous snapshot of the effective data transfer rate that the memory modules can sustain based on the current clock frequency..

ctl_oc_telemetry_item_t vramReadBandwidthCounter

[out] Instantaneous snapshot of the monotonic counter that measures the read traffic from the memory modules. By taking the delta between two snapshots and dividing by the delta time in seconds, an application can compute the average read bandwidth.

ctl_oc_telemetry_item_t vramWriteBandwidthCounter

[out] Instantaneous snapshot of the monotonic counter that measures the write traffic to the memory modules. By taking the delta between two snapshots and dividing by the delta time in seconds, an application can compute the average write bandwidth.

ctl_oc_telemetry_item_t vramCurrentTemperature

[out] Instantaneous snapshot of the GPU chip temperature, read from the sensor reporting the highest value.

bool vramPowerLimited

[out] Instantaneous indication that the memory frequency is being throttled because the memory modules are exceeding the maximum power limits.

bool vramTemperatureLimited

[out] Instantaneous indication that the memory frequency is being throttled because the memory modules are exceeding the temperature limits.

bool vramCurrentLimited

[out] Instantaneous indication that the memory frequency is being throttled because the memory modules have exceeded the power supply current limits.

bool vramVoltageLimited

[out] Instantaneous indication that the memory frequency cannot be increased because the voltage limits have been reached.

bool vramUtilizationLimited

[out] Instantaneous indication that due to lower memory traffic, the hardware has lowered the memory frequency.

ctl_oc_telemetry_item_t totalCardEnergyCounter

[out] Total Card Energy Counter.

ctl_psu_info_t psu[CTL_PSU_COUNT]

[out] PSU voltage and power.

ctl_oc_telemetry_item_t fanSpeed[CTL_FAN_COUNT]

[out] Fan speed.

Pci

Pci Functions

ctlPciGetProperties

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlPciGetProperties(ctl_device_adapter_handle_t hDAhandle, ctl_pci_properties_t *pProperties)

Get PCI properties - address, max speed.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hDAhandle – [in][release] Handle to display adapter

  • pProperties – [in,out] Will contain the PCI properties.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pProperties

ctlPciGetState

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlPciGetState(ctl_device_adapter_handle_t hDAhandle, ctl_pci_state_t *pState)

Get current PCI state - current speed.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hDAhandle – [in][release] Handle to display adapter

  • pState – [in,out] Will contain the PCI properties.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pState

Pci Structures

ctl_pci_address_t

struct ctl_pci_address_t

PCI address.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint32_t domain

[out] BDF domain

uint32_t bus

[out] BDF bus

uint32_t device

[out] BDF device

uint32_t function

[out] BDF function

ctl_pci_speed_t

struct ctl_pci_speed_t

PCI speed.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

int32_t gen

[out] The link generation. A value of -1 means that this property is unknown.

int32_t width

[out] The number of lanes. A value of -1 means that this property is unknown.

int64_t maxBandwidth

[out] The maximum bandwidth in bytes/sec (sum of all lanes). A value of -1 means that this property is unknown.

ctl_pci_properties_t

struct ctl_pci_properties_t

Static PCI properties.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_pci_address_t address

[out] The BDF address

ctl_pci_speed_t maxSpeed

[out] Fastest port configuration supported by the device (sum of all lanes)

bool resizable_bar_supported

[out] Support for Resizable Bar on this device.

bool resizable_bar_enabled

[out] Resizable Bar enabled on this device

ctl_pci_state_t

struct ctl_pci_state_t

Dynamic PCI state.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_pci_speed_t speed

[out] The current port configure speed

Power

Power Functions

ctlEnumPowerDomains

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlEnumPowerDomains(ctl_device_adapter_handle_t hDAhandle, uint32_t *pCount, ctl_pwr_handle_t *phPower)

Get handle of power domains.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hDAhandle – [in][release] Handle to display adapter

  • pCount – [in,out] pointer to the number of components of this type. if count is zero, then the driver shall update the value with the total number of components of this type that are available. if count is greater than the number of components of this type that are available, then the driver shall update the value with the correct number of components.

  • phPower – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pCount

ctlPowerGetProperties

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlPowerGetProperties(ctl_pwr_handle_t hPower, ctl_power_properties_t *pProperties)

Get properties related to a power domain.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hPower – [in] Handle for the component.

  • pProperties – [in,out] Structure that will contain property data.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hPower

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pProperties

ctlPowerGetEnergyCounter

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlPowerGetEnergyCounter(ctl_pwr_handle_t hPower, ctl_power_energy_counter_t *pEnergy)

Get energy counter.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hPower – [in] Handle for the component.

  • pEnergy – [in,out] Will contain the latest snapshot of the energy counter and timestamp when the last counter value was measured.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hPower

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pEnergy

ctlPowerGetLimits

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlPowerGetLimits(ctl_pwr_handle_t hPower, ctl_power_limits_t *pPowerLimits)

Get power limits.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hPower – [in] Handle for the component.

  • pPowerLimits – [in,out][optional] Structure that will contain the power limits.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hPower

ctlPowerSetLimits

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlPowerSetLimits(ctl_pwr_handle_t hPower, const ctl_power_limits_t *pPowerLimits)

Set power limits.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hPower – [in] Handle for the component.

  • pPowerLimits – [in][optional] Structure that will contain the power limits.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hPower

  • CTL_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

    • User does not have permissions to make these modifications.

  • CTL_RESULT_ERROR_NOT_AVAILABLE

    • The device is in use, meaning that the GPU is under Over clocking, applying power limits under overclocking is not supported.

Power Structures

ctl_power_properties_t

struct ctl_power_properties_t

Properties related to device power settings.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool canControl

[out] Software can change the power limits of this domain assuming the user has permissions.

int32_t defaultLimit

[out] The factory default TDP power limit of the part in milliwatts. A value of -1 means that this is not known.

int32_t minLimit

[out] The minimum power limit in milliwatts that can be requested.

int32_t maxLimit

[out] The maximum power limit in milliwatts that can be requested.

ctl_power_energy_counter_t

struct ctl_power_energy_counter_t

Energy counter snapshot.

  • Average power is calculated by taking two snapshots (s1, s2) and using the equation: PowerWatts = (s2.energy - s1.energy) / (s2.timestamp - s1.timestamp)

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

uint64_t energy

[out] The monotonic energy counter in microjoules.

uint64_t timestamp

[out] Microsecond timestamp when energy was captured. This timestamp should only be used to calculate delta time between snapshots of this structure. Never take the delta of this timestamp with the timestamp from a different structure since they are not guaranteed to have the same base. The absolute value of the timestamp is only valid during within the application and may be different on the next execution.

ctl_power_sustained_limit_t

struct ctl_power_sustained_limit_t

Sustained power limits.

  • The power controller (Punit) will throttle the operating frequency if the power averaged over a window (typically seconds) exceeds this limit.

Public Members

bool enabled

[in,out] indicates if the limit is enabled (true) or ignored (false)

int32_t power

[in,out] power limit in milliwatts

int32_t interval

[in,out] power averaging window (Tau) in milliseconds

ctl_power_burst_limit_t

struct ctl_power_burst_limit_t

Burst power limit.

  • The power controller (Punit) will throttle the operating frequency of the device if the power averaged over a few milliseconds exceeds a limit known as PL2. Typically PL2 > PL1 so that it permits the frequency to burst higher for short periods than would be otherwise permitted by PL1.

Public Members

bool enabled

[in,out] indicates if the limit is enabled (true) or ignored (false)

int32_t power

[in,out] power limit in milliwatts

ctl_power_peak_limit_t

struct ctl_power_peak_limit_t

Peak power limit.

  • The power controller (Punit) will preemptively throttle the operating frequency of the device when the instantaneous power exceeds this limit. The limit is known as PL4. It expresses the maximum power that can be drawn from the power supply.

  • If this power limit is removed or set too high, the power supply will generate an interrupt when it detects an overcurrent condition and the power controller will throttle the device frequencies down to min. It is thus better to tune the PL4 value in order to avoid such excursions.

Public Members

int32_t powerAC

[in,out] power limit in milliwatts for the AC power source.

int32_t powerDC

[in,out] power limit in milliwatts for the DC power source. On input, this is ignored if the product does not have a battery. On output, this will be -1 if the product does not have a battery.

ctl_power_limits_t

struct ctl_power_limits_t

Power limits.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_power_sustained_limit_t sustainedPowerLimit

[in,out] sustained power limit.

ctl_power_burst_limit_t burstPowerLimit

[in,out] burst power limit.

ctl_power_peak_limit_t peakPowerLimits

[in,out] peak power limit.

ctl_energy_threshold_t

struct ctl_energy_threshold_t

Energy threshold.

  • .

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

bool enable

[in,out] Indicates if the energy threshold is enabled.

double threshold

[in,out] The energy threshold in Joules. Will be 0.0 if no threshold has been set.

uint32_t processId

[in,out] The host process ID that set the energy threshold. Will be 0xFFFFFFFF if no threshold has been set.

Temperature

Temperature Functions

ctlEnumTemperatureSensors

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlEnumTemperatureSensors(ctl_device_adapter_handle_t hDAhandle, uint32_t *pCount, ctl_temp_handle_t *phTemperature)

Get handle of temperature sensors.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hDAhandle – [in][release] Handle to display adapter

  • pCount – [in,out] pointer to the number of components of this type. if count is zero, then the driver shall update the value with the total number of components of this type that are available. if count is greater than the number of components of this type that are available, then the driver shall update the value with the correct number of components.

  • phTemperature – [in,out][optional][range(0, *pCount)] array of handle of components of this type. if count is less than the number of components of this type that are available, then the driver shall only retrieve that number of component handles.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hDAhandle

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pCount

ctlTemperatureGetProperties

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlTemperatureGetProperties(ctl_temp_handle_t hTemperature, ctl_temp_properties_t *pProperties)

Get temperature sensor properties.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hTemperature – [in] Handle for the component.

  • pProperties – [in,out] Will contain the temperature sensor properties.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hTemperature

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pProperties

ctlTemperatureGetState

CTL_APIEXPORT ctl_result_t CTL_APICALL ctlTemperatureGetState(ctl_temp_handle_t hTemperature, double *pTemperature)

Get the temperature from a specified sensor.

  • The application may call this function from simultaneous threads.

  • The implementation of this function should be lock-free.

Parameters:

  • hTemperature – [in] Handle for the component.

  • pTemperature – [in,out] Will contain the temperature read from the specified sensor in degrees Celsius.

Returns:

  • CTL_RESULT_SUCCESS

  • CTL_RESULT_ERROR_UNINITIALIZED

  • CTL_RESULT_ERROR_DEVICE_LOST

  • CTL_RESULT_ERROR_INVALID_NULL_HANDLE

    • nullptr == hTemperature

  • CTL_RESULT_ERROR_INVALID_NULL_POINTER

    • nullptr == pTemperature

Temperature Enums

ctl_temp_sensors_t

enum ctl_temp_sensors_t

Temperature sensors.

Values:

enumerator CTL_TEMP_SENSORS_GLOBAL

The maximum temperature across all device sensors.

enumerator CTL_TEMP_SENSORS_GPU

The maximum temperature across all sensors in the GPU.

enumerator CTL_TEMP_SENSORS_MEMORY

The maximum temperature across all sensors in the local memory.

enumerator CTL_TEMP_SENSORS_GLOBAL_MIN

The minimum temperature across all device sensors.

enumerator CTL_TEMP_SENSORS_GPU_MIN

The minimum temperature across all sensors in the GPU.

enumerator CTL_TEMP_SENSORS_MEMORY_MIN

The minimum temperature across all sensors in the local device memory.

enumerator CTL_TEMP_SENSORS_MAX

Temperature Structures

ctl_temp_properties_t

struct ctl_temp_properties_t

Temperature sensor properties.

Public Members

uint32_t Size

[in] size of this structure

uint8_t Version

[in] version of this structure

ctl_temp_sensors_t type

[out] Which part of the device the temperature sensor measures

double maxTemperature

[out] Will contain the maximum temperature for the specific device in degrees Celsius.