ILMH265Decoder Interface

The ILMH265Decoder Interface is the interface for the LEAD H265 Decoder

Data Types:

eH265DecoderApiLevel

typedef enum 
{ 
   H265DecoderApiLevel_1 = 0 
} eH265DecoderApiLevel; 

eH265DecodingCapability

typedef enum 
{ 
   H265DecodingCapability_None = 0, /* There is no decoding engine available */ 
   H265DecodingCapability_Software = 1, /* Software decoding only */ 
   H265DecodingCapability_QuickSync = 2, /* QuickSync Video hardware acceleration is available */ 
   H265DecodingCapability_Software_QuickSync = 3, /* Software and QuickSync Video Hardware decoding is available */ 
   H265DecodingCapability_CUDA = 4, /* CUDA hardware acceleration is available */ 
   H265DecodingCapability_Software_CUDA = 5, /* Software, QuickSync video and CUDA Hardware decoding is available */ 
   H265DecodingCapability_CUDA_QuickSync = 6, /* Both CUDA and QuickSync Video hardware acceleration are available */ 
   H265DecodingCapability_Software_CUDA_QuickSync = 7, /* Software, QuickSync Video and CUDA are available */ 
} eH265DecodingCapability; 

eH265DecodingEngine

typedef enum 
{ 
   H265DecodingEngine_None = 0, 
   H265DecodingEngine_Software = 1, 
   H265DecodingEngine_QuickSync_Hardware = 2, 
   H265DecodingEngine_CUDA_Hardware = 4, 
} eH265DecodingEngine; 

Interface Properties:

Type

Name

 Description

eH265DecodingCapability Capability

(Read-only) Indicates whether hardware acceleration is available. Can be one of the following values:

  • H265DecodingCapability_None [0] - There is no decoding engine available.

  • H265DecodingCapability_Software [1] - Indicates only software decompression is available.

  • H265DecodingCapability_QuickSync [2] - Indicates Intel Quick Sync Video hardware acceleration is available.

  • H265DecodingCapability_Software_QuickSync [3] - Indicates Software and Intel Quick Sync Video hardware acceleration is available.

  • H265DecodingCapability_CUDA [4]- Indicates NVIDIA CUDA hardware acceleration is available.

  • H265DecodingCapability_Software_CUDA [5]- Indicates Software and NVIDIA CUDA hardware acceleration is available.

  • H265DecodingCapability_CUDA_QuickSync [6] - Indicates both Quick Sync and CUDA hardware accelerations are available.

  • H265DecodingCapability_Software_CUDA_QuickSync [7] - Indicates Software, Quick Sync and CUDA hardware accelerations are available.

See the How to Enable High Profiles and Hardware Compression in the LEAD H.264 Encoder topic for more information on installing libmfxsw32/64.dll. If you do not install libmfxsw32/64.dll, neither software nor Quick Sync hardware decoding will be available.

Unlike the Quick Sync video case, you do not need to install anything special to get access to CUDA hardware acceleration. Everything is installed by the NVIDIA display driver. You might need to install a newer version of the display driver if the display driver does not have support for the CUDA 5.5 engine. See the GetCUDAInfo method below for more information.

Note that some CUDA GPUs are capable of hardware acceleration for decoding in general, but not necessarily of H265/HEVC decoding. This page contains a list of CUDA GPUs capable of decoding H265 video. Note that the list is not always logical, since some high end Tesla cards (like Tesla M6) are not capable of H265 decoding, while some lower cards (like GeForce GTX 960) can. The list is not complete, since it does not list all the GTX 9xx or 10xx cards that can decode H265 video.

If the Quick Sync Video hardware acceleration is available, you can enable it by setting the EnableDecodingEngine property for H265DecodingEngine_QuickSync_Hardware to VARIANT_TRUE.

You can enable the CUDA hardware acceleration by setting the EnableDecodingEngine property for H265DecodingEngine_CUDA_Hardware to VARIANT_TRUE.

The H265DecodingCapability_XXX values let you easily determine whether Quick Sync hardware acceleration is available by performing a bitwise 'and' operation.

Use the following 'if' statement in C/C++ to determine whether the computer has Quick Sync hardware acceleration capabilities:

if((int)Capability & H265DecodingCapability_QuickSync) 
{ 
   /* computer has Quick Sync hardware capabilities */ 
} 

You can determine CUDA hardware acceleration capability by using the following code:

if ((int)Capability & H265DecodingCapability_CUDA) 
{ 
   /* computer has CUDA hardware capabilities */ 
} 
VARIANT_BOOL EnableDecodingEngine(eH265DecodingEngine decodingEngine) Flag that indicates whether a certain decompression engine should be used.

The decodingEngine parameter indicates which engine to enable or disable.

Currently the following values can be passed for decodingEngine:

H265DecodingEngine_QuickSync [2]: Intel Quick Sync Video hardware acceleration. If this decoding engine is not enabled, the decoder will not use Quick Sync Video hardware acceleration even if the computer is capable of Quick Sync hardware acceleration. This property is ignored if the computer is not capable of Quick Sync hardware acceleration (i.e., if the Capability property does not contain H265DecodingCapability_QuickSync).

H265DecodingEngine_CUDA [4]: NVIDIA CUDA hardware acceleration. If this decoding engine is not enabled, the decoder will not use CUDA hardware acceleration even if the computer is capable of CUDA hardware acceleration. This property is ignored if the computer is not capable of CUDA hardware acceleration (i.e., if the Capability property does not return a value that has the H265DecodingCapability_CUDA flag set).

The hardware acceleration options are enabled by default.

The hardware acceleration options can only be changed if the filter is in the stopped state. If you change the settings while the decoder is running, the updates will take effect when the graph stops. Pausing the stream is not enough - you have to stop the playback or the conversion completely.

If both decoding engines are enabled, the H265 decoder will pick one. The preferred decoding engine can change in the future, so if you wish to guarantee the use of a particular engine you should disable the other one.

eH265DecodingEngine CurrentDecodingEngine (Read-only) Indicates which engine is currently being used.

The decodingEngine parameter indicates which engine to enable or disable.

Currently this property can return one of the following values:

H265DecodingEngine_None [0]: There is no decoding engine available. The software decoding engine was not installed properly and no hardware acceleration is enabled or available. The decode will fail to decode any video in this case.

H265DecodingEngine_Software [1]: Only software decoding is available. Hardware acceleration is either not available or not enabled.

H265DecodingEngine_QuickSync [2]: Intel Quick Sync Video hardware acceleration.

H265DecodingEngine_CUDA [4]: NVIDIA CUDA hardware acceleration.

long PreferredCUDADevice

A read-write property indicating which CUDA device to use (0-based). This property is useful only when the decoder is using the NVIDIA CUDA hardware acceleration and the system has more than one NVIDIA graphics card with CUDA capabilities.

Set this property to indicate which device to use. The property can be set to the following values:

  • -1 (default), which indicates the decoder will automatically select which CUDA device to use (AutoSelect mode).
  • N (between 0 and GPUCount - 1), indicating the decoder will use device N regardless of whether it is in use or not.

In general, it is better for operations to be balanced among the existing CUDA devices. Decodings will be faster and you will also avoid burnout situations. A burnout situation can occur if the fan does not cool the card properly; in this situation, the card can be permanently destroyed by over-use.

GPUCount indicates the number of CUDA-capable devices and can be obtained calling the GetCUDAInfo method.

You can also get it to find out which device will be used. If AutoSelect mode is used (if this property is -1), then you can find out which device will actually be used by getting the SelectedCUDADevice property.

If you change the preferred CUDA device while the graph is running, the change will take effect when the graph is restarted. In this case, the return code from the call to change the property will be LTMM_S_WRONG_STATE (0x00050055).

long SelectedCUDADevice A 0-based read-only property that can be used to find out which CUDA device will be used for conversion. If you wish to change the selection, set the PreferredCUDADevice property to the device you wish to use (value between 0 and GPU_Count- 1). GPUCount indicates the number of CUDA-capable devices and can be obtained calling the GetCUDAInfo method.

Interface Methods:

HRESULT ResetToDefaultsEx(eH265DecoderApiLevel ApiLevel);

Parameters

ApiLevel Specifies which defaults should be used by the filter.

Description

Resets the decoder to its default values. The ApiLevel parameter determines which default values to use. Current applications should set ApiLevel to H265DecoderApiLevel_1 = 0.

The H265 decoder may change in the future and have different properties or default behaviour. Calling this method ensures the filter will have the same default values they had at the time you developed your application.

It is best to call ResetToDefaultsEx(H265DecoderApiLevel_1) before you start setting properties and start calling other methods for this interface.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

E_INVALIDARG

The ApiLevel parameter is invalid.

HRESULT WriteToRegistry ()

Description

Writes the values of all of the properties listed above to the system registry, so that the decoder will remember these settings the next time it is used. This method is automatically called by the property page when you apply modified settings by clicking the Apply or OK button.

Returns

S_OK if successful, S_FALSE otherwise. 

HRESULT ResetToDefaults (eH265DecoderApiLevel ApiLevel)

Parameters

eH265DecoderApiLevel ApiLevel

Description

Resets the decoder to its default values. The ApiLevel parameter determines which default values to use. Current applications should set ApiLevel to H265DecoderApiLevel_1 = 0.

The H265 decoder may change in the future and have different properties or default behaviour. Calling this method ensures the filter will have the same default values they had at the time you developed your application.

It is best to call ResetToDefaultsEx(H265DecoderApiLevel_1) before you start setting properties and start calling other methods for this interface.

Returns

S_OK if connected, S_FALSE otherwise.

HRESULT GetCUDAInfo(long *pGPUCount, BSTR *pszFriendlySystemDescription, long *puInstalledDriverVersion, long *puInstalledDriverVersion)

Parameters

pGPUCount

Optional pointer to a variable that will be updated with the number of available CUDA GPU units. Can be NULL if this information is not needed.

pszFriendlySystemDescription

Optional pointer to a variable that will be updated with a user-friendly string containing information about the system. Can be NULL if this information is not needed.

puInstalledDriverVersion

Optional pointer to a variable that will be updated with the version of CUDA engine installed on this system. Can be NULL if this information is not needed.

puInstalledDriverVersion

Optional pointer to a variable that will be updated with the recommended version of CUDA engine that should be installed for optimal performance. Can be NULL if this information is not needed.

Description

Use this method to get more information about the computer's CUDA capabilities. For instance, you can find out whether there are any GPUs, a user friendly string you can display to the user, and the recommended and installed versions of the CUDA engine present.

Pass NULL for any parameters that are not needed.

If pszFriendlySystemDescription is not NULL, the string returned is a wide char string allocated with the SysAllocString Windows API function. You are responsible for freeing it using the Windows API function SysFreeString. This string is the string displayed by the "CUDA Info" button in the H265 Decoder Property page.

The driver version is an integer having the following format: <h>0<m>0, where <h> is the major version (1..9) and <m> is the minor version (1..9). For example, version 5.5 is reported as the decimal number 5050.

The decoder might be able to use CUDA hardware decoding even if the installed version is less than the recommended version. But some features might not be available or the decoding might fail, so it is best that the display driver installed contains a CUDA engine with a version at least as high as the recommended version. If the installed version is less than the recommended version, you are encouraged to display a message asking the user to install the latest display driver for the graphics card from the NVIDIA web site (https://www.nvidia.com/content/global/global.php). Note that the display driver version does not necessarily correspond to the CUDA version.

If CUDA is not available, *pGPUCount will be set to 0 and the puInstalledDriverVersion will be set to 0. Most systems will have 0 or 1 GPU units. In rare situations (systems with multiple graphics cards), *pGPUCount will be set to 2 or more.

You can get more information about each GPU device by calling the GetCUDADeviceSettings method.

Returns

S_OK if connected

E_OUTOFMEMORY if there is not enough memory to allocate the resulting string.

HRESULT GetCUDADeviceSettings (long device, BSTR *pszDeviceName, BSTR *pszFriendlyDeviceDescription, long *pUsagePercentage, long *pCurTemp, long *pMinTemp, long *pMaxTemp)

Parameters

device 0-based index of the CUDA device (between 0 and GPUCount - 1).
pszDeviceName Optional pointer to a variable that will be updated with the name of the CUDA device. Can be NULL if this information is not needed.
pszFriendlyDeviceDescription Optional pointer to a variable that will be updated with a user-friendly string containing information about the specified CUDA device. Can be NULL if this information is not needed.
pUsagePercentage Optional pointer to a variable that will be updated with the percentage of time the device was in use in the last second. Value will be between 0 (device was idle the whole time) and 100 (the device was in use the whole time). Can be NULL if this information is not needed.
pCurTemp Optional pointer to a variable that will be updated with the current temperature in degrees Celsius. Can be NULL if this information is not needed.
pMinTemp Optional pointer to a variable that will be updated with the minimum temperature in degrees Celsius. Can be NULL if this information is not needed.
pMaxTemp Optional pointer to a variable that will be updated with the maximum temperature in degrees Celsius. Can be NULL if this information is not needed.

Description

Use this method to get more information about a CUDA device's current settings. Use this method to monitor the usage and temperature of a particular GPU device. For example, you might use this to make sure the temperature does not get too hot, (since some graphics cards can be destroyed if they are used too much for long periods of time). If you burn out the card, it is destroyed permanently. If you burn out the card, it will not be enough to restart or turn the computer off so the card cools down. The card will be damaged for good and will need to be replaced.

Returns

S_OK if successful

LTMM_E_CUDA_DEVICE_NOT_AVAILABLE [0x80050020] if the device is not between 0 and GPUCount - 1

E_OUTOFMEMORY if there is not enough memory to allocate the resulting string

E_FAIL if an unexpected error occurred getting the device's settings

Help Version 20.0.2020.3.31
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2020 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Filters C API Help