ILMH264Decoder Interface

The ILMH264Decoder Interface is the interface for the LEAD H264 Decoder

Data Types:

eH264DecodingFlag

These are the possible values for H264 decoding flags. These flags can be set in the SymbolMode property.

typedef enum 
{ 
   H264DecodingFlag_DecodeCorruptedStream = 0x00000001, 
   H264DecodingFlag_FillFrameGaps = 0x00000002, 
   H264DecodingFlag_DisplayGrayOnError = 0x00000004, 
   H264DecodingFlag_UseOneThread = 0x00000008, 
   H264DecodingFlag_WaitForI_FrameToPlay = 0x00000010, 
   H264DecodingFlag_DiscardCorruptedFrames = 0x00000020, 
   H264DecodingFlag_LowMemorySituation = 0x00000040, 
} eH264DecodingFlag; 

ltmmMediaEventCode

typedef enum 
{ 
   ltmmEC_Sample_Delivered = 0xA000, /* Event sent on a regular base when samples are decoded. The frequency is indicated by the DeliveredFrameNotificationInterval property. lParam1 is set to the frame index. */ 
   ltmmEC_No_Samples_Delivered = 0xA001, /* Streaming stopped and no samples were delivered by the hardware acceleration decoding engine. lParam1 will be set to one of the eH264DecodingEngine enumeration types */ 
} ltmmMediaEventCode; 

eH264DecoderApiLevel

typedef enum 
{ 
   H264DecoderApiLevel_1 = 0 
} eH264DecoderApiLevel; 

eH264DecodingCapability

typedef enum 
{ 
   H264DecodingCapability_Software = 0, /* Original software only, no hardware acceleration is available */ 
   H264DecodingCapability_QuickSync = 2, /* QuickSync Video hardware acceleration is available */ 
   H264DecodingCapability_CUDA = 4, /* CUDA hardware acceleration is available */ 
   H264DecodingCapability_CUDA_QuickSync = 6, /* Both CUDA and QuickSync Video hardware acceleration are available */ 
} eH264DecodingCapability; 

eH264DecodingEngine

typedef enum 
{ 
   H264DecodingEngine_QuickSync_Hardware = 1, 
   H264DecodingEngine_CUDA_Hardware = 2, 
} eH264DecodingEngine; 

Interface Properties:

Type

Name

Description

eH264DecodingCapability Capability

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

  • H264DecodingCapability_Software[0] - indicates only software decompression is available.

  • H264DecodingCapability_QuickSync [2] - indicates Intel Quick Sync Video hardware acceleration is available.

  • H264DecodingCapability_CUDA [4]- indicates NVIDIA CUDA hardware acceleration is available.

  • H264DecodingCapability_CUDA_QuickSync [6] - indicates both 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, Quick Sync hardware decoding will not 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.

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

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

The H264DecodingCapability_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 & H264DecodingCapability_QuickSync) 
{ 
   /* computer has Quick Sync hardware capabilities */ 
} 

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

if ((int)Capability & H264DecodingCapability_CUDA) 
{ 
   /* computer has CUDA hardware capabilities */ 
} 

The hardware acceleration is disabled by default because some video streams will not play properly with hardware acceleration. For example, video streams containing only P frames can be decoded when you use the software decompression but not when you use hardware acceleration (Quick Sync Video or CUDA).

If you try to play/convert a stream using hardware acceleration and the decoder does not output a single frame, the decoder will send the ltmmEC_No_Samples_Delivered (0xA001) event with the lParam1 value set to the active decoding engine (H264DecodingEngine_CUDA_Hardware or H264DecodingEngine_QuickSync_Hardware). If you detect this event, it is recommended that you disable the hardware decoding engine and try playing/converting the stream again.

long

DecodingOptions   

  Accepts one or all values from eH264DecodingFlag.

  H264DecodingFlag_DecodeCorruptedStream:

  • Enables the decoder to play corrupted streams. The decoder will run slower in this mode.

H264DecodingFlag_DiscardCorruptedFrames:

  • When this option is enabled, the decoder will not deliver frames downstream frames it believes are corrupted. This results in cleaner looking video at a slightly lower frame rate in corrupted videos. This option is off by default.

H264DecodingFlag_DisplayGrayOnError: 

  • Enables the decoder to display the corrupted data as a gray region. Otherwise a random area from previous frames could be displayed. 

H264DecodingFlag_FillFrameGaps:

  • Enables the decoder to replace a missing frame from a previous frame in the stream.  This option may provide jerky playback, and is not recommended

H264DecodingFlag_UseOneThread:

  • By default the number of threads the decoder uses equal to the number of CPU/cores. So for a quad core machine the decoder will use four threads to decode the h.264 stream. if this flag set, then the decoder will use one thread only no matter how many CPUs or cores the machine has.

H264DecodingFlag_WaitForI_FrameToPlay:

  • If set, the decoder will discard all the frames received before the first I frame. This will eliminate corrupted frames seen sometimes at the start of some streams. If not set, the decoder will display frames as soon as it receives them. This option is off by default.

264DecodingFlag_LowMemorySituation:

  • If set, the decoder uses less memory. The decoder uses this flag internally when it detects the video is large and that there is an encoder in the graph that requires a lot of memory. You can also set this flag if you run into Out Of Memory situations when you try to convert some files.

double

 

 DeliveredFrameNotificationInterval

 

The interval of Delivered Frame Notification in seconds. A value of Zero will disable notification sending. Values smaller than the  time per frame (= 1.0 / frame rate) will cause the decoder to send a notification for each frame. The Notification ID is ltmmEC_Sample_Delivered (0xA000). Values less than zero will not be accepted. This parameter can be changed while the decoder is running.

VARIANT_BOOL EnableDecodingEngine(eH264DecodingEngine 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:

H264DecodingEngine_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 H264DecodingCapability_QuickSync).

H264DecodingEngine_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 H264DecodingCapability_CUDA flag set).

Hardware acceleration is disabled by default because some streams are not supported by the hardware acceleration decoders. In other words, if you do not call this property and enable acceleration, the acceleration will not be used. The property page calls this property when you enable/disable the hardware acceleration check boxes.
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.

You can 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 the 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 the 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 andGPU_Count- 1). GPUCount indicates the number of CUDA-capable devices and can be obtained calling the GetCUDAInfo method.

Interface Methods:

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 on the Apply or OK button.

Returns

S_OK if successful, S_FALSE otherwise. 

HRESULT ResetToDefaults (eH264DecoderApiLevel ApiLevel)

Parameters

eH264DecoderApiLevel ApiLevel

Description

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

The H264 decoder might change in the future and have different properties or default behaviour. Calling this method ensure the filter will have the same default values as they were at the time you developed your application.

It is recommended you call ResetToDefaultsEx(H264DecoderApiLevel_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 *puRequiredDriverVersion)

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 on 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.

puRequiredDriverVersion

Optional pointer to a variable that will be updated with 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 on the computer's CUDA capabilities. 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.

You can pass NULL for any parameters you don't need.

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 H264 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 recommended 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 on 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 CUDA device name. 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 on the specified CUDA device. Can be NULL if this information is not needed.
pUsagePercentage Optional pointer to a variable that will be updated 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 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 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 maximum temperature in degrees Celsius. Can be NULL if this information is not needed.

Description

Use this method to get more information on a CUDA device's current settings. Use this method to monitor the usage and temperature for a particular GPU device. For example, you might use this to make sure the temperature does not get too hot, (since some graphics card 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; otherwise, a return code indicating the reason for failure:

LTMM_E_CUDA_DEVICE_NOT_AVAILABLE [0x80050020] if 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

HRESULT ResetToDefaultsEx(eH264DecoderApiLevel ApiLevel);

Parameters

ApiLevel Specifies which defaults should be used by the filter.

Description

Resets the filter to default values. The ApiLevel parameter determines which default values to use. Current applications should set ApiLevel to H264DecoderApiLevel_1 = 0. The filter might change in the future and have different properties or default behaviour. Calling this method ensures future versions of the filter will behave the same way as when the application was developed. It is best to call ResetToDefaultsEx(H264DecoderApiLevel_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.

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