ILMMPEG2Decoder Interface

This is the interface for the LEAD MPEG-2 Decoder (2.0).

Properties:

Type

Name

 Description

eMPEG2DecodingCapability Capability

(Read-only) Indicates whether hardware acceleration is available. The following values are possible:

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

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

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

  • MPEG2DecodingCapability_CUDA_QuickSync [6] - indicates that 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 may 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 MPEG2DecodingEngine_QuickSync_Hardware to VARIANT_TRUE.

Enable CUDA hardware acceleration by setting the EnableDecodingEngine property for MPEG2DecodingEngine_CUDA_Hardware to VARIANT_TRUE.

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

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

if((int)Capability & MPEG2DecodingCapability_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 (MPEG2DecodingEngine_CUDA_Hardware or MPEG2DecodingEngine_QuickSync_Hardware). If you detect this event, it is recommended that you disable the hardware decoding engine and try playing/converting the stream again.

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

MPEG2DecodingEngine_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 MPEG2DecodingCapability_QuickSync). MPEG2DecodingEngine_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 MPEG2DecodingCapability_CUDA flag set). Hardware acceleration is disabled by default because some streams are not supported by 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 CUDA device (AutoSelect mode).
  • N (between 0 and GPUCount - 1), indicates the decoder will use device N regardless of whether it is already 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.

The GPUCount indicates the number of CUDA-capable devices and can be obtained calling the GetCUDAInfo method. You can also call it to find out which device will be used. If the 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 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.

Return

S_OK if successful; otherwise, S_FALSE. 

HRESULT  ResetToDefaults (eMPEG2DecoderApiLevel ApiLevel)

Parameters

eMPEG2DecoderApiLevel ApiLevel

Description

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

The MPEG2 decoder may change in the future and have different properties or default behaviour. Calling this method ensures the filter will use the same default values that were used at the time you developed your application.

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

Returns

S_OK if connected; otherwise, S_FALSE.

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 version of the CUDA engine that is recommended to 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. 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 do not 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 MPEG2 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 may be able to use CUDA hardware decoding even if the installed version is less than the recommended version. But some features may 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 (http://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, the *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 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 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 about a CUDA device's current settings. Use this method to monitor the usage and temperature for a particular GPU device. For example, you can use this to ensure that the temperature does not get too hot. This is important because some graphics card can get burned out if they are used too much for long periods of time. If the card gets burned out, it is destroyed permanently: it will not start working again if you turn the computer off and let the card cool 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] - the device is not between 0 and GPUCount - 1.

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

E_FAIL - an unexpected error occurred getting the device's settings.

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 eMPEG2DecodingEngine enumeration types */ 
} ltmmMediaEventCode_; 

eMPEG2DecoderApiLevel

typedef enum 
{ 
   MPEG2DecoderApiLevel_1 = 0 
} eMPEG2DecoderApiLevel; 

eMPEG2DecodingCapability

typedef enum 
{ 
   MPEG2DecodingCapability_Software = 0, /* Original software only, no hardware acceleration is available */ 
   MPEG2DecodingCapability_QuickSync = 2, /* QuickSync Video hardware acceleration is available */ 
   MPEG2DecodingCapability_CUDA = 4, /* CUDA hardware acceleration is available */ 
   MPEG2DecodingCapability_CUDA_QuickSync = 6, /* Both CUDA and QuickSync Video hardware acceleration are available */ 
} eMPEG2DecodingCapability; 

eMPEG2DecodingEngine

typedef enum 
{ 
   MPEG2DecodingEngine_QuickSync_Hardware = 1, 
   MPEG2DecodingEngine_CUDA_Hardware = 2, 
} eMPEG2DecodingEngine; 

Help Version 19.0.2017.10.27
Products | Support | Contact Us | Copyright Notices
© 1991-2017 LEAD Technologies, Inc. All Rights Reserved.
LEADTOOLS Filters C API Help