ILMMPEG2Decoder Interface

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

Data Types

ltmmMediaEventCode_

Summary

Defines values used for media event reporting.

Syntax

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

Summary

Lists the valid values for the ApiLevel parameter that can be passed to the ResetToDefaults method.

Syntax

typedef enum 
{ 
   MPEG2DecoderApiLevel_1 = 0 
} eMPEG2DecoderApiLevel; 

eMPEG2DecodingCapability

Summary

Determines the hardware acceleration availably.

Syntax

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; 

Members

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.

eMPEG2DecodingEngine

Summary

Specifies a certain decompression engine to be used.

Syntax

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

Members

MPEG2DecodingEngine_QuickSync_Hardware

[1] 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_Hardware

[2] 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.|

Properties

Type Name Description
eMPEG2DecodingCapability Capability (Read-only) Indicates whether hardware acceleration is available.
See the LEAD H264 Encoder 4.0 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.
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.

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.

Comments

This method is automatically called by the property page when you apply modified settings by clicking the Apply or OK button.

Returns

Return Description
S_OK Successful.
S_FALSE Otherwise.

HRESULT ResetToDefaults (eMPEG2DecoderApiLevel ApiLevel)

Description

Resets the decoder to its default values.

Parameters

ApiLevel

Determines which default values to use. Current applications should set the ApiLevel to MPEG2DecoderApiLevel_1 = 0.

Comments

The MPEG2 decoder may change in the future and have different properties or default behavior. 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

Return Description
S_OK Connected.
S_FALSE Otherwise.

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

Description

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

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.

puRequiredDriverVersion

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.

Comments

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 (https://www.nvidia.com/en-us/). 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

Return Description
S_OK Connected.
E_OUTOFMEMORY 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)

Description

Gets more information about a CUDA device's current settings.

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.

Comments

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

Return Description
S_OK 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.
Help Version 22.0.2023.2.15
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Filters C API Help

Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.