ILMH265Encoder Interface

This is the interface for the LEAD H265 Encoder.

Interface Properties:

Type

Name

Description

eH265CAPABILITY

Capability

(Read-only) Indicates whether hardware compression and High profiles are available. The Capability property returns a bitwise OR'd combination of the following flags. If no bit is set,  only software compression is supported. The following values are possible:

  • H265CAPABILITY_SOFTWARE[0], then only software compression is available

  • H265CAPABILITY_QUICKSYNC [1], then Intel Quick Sync Video hardware compression is available      

  • H265CAPABILITY_CUDA [2], then CUDA compression is supported on the current machine    

VARIANT_BOOL

EnableRateControl

Indicates whether the H265 encoderuses Rate-Driven compression or Quality-Driven compression. If this property is TRUE, Rate-Driven compression is used and the rate is set in the BitRate property. If this is FALSE, Quality-Driven compression is used and the quality factor is set in the QualityFactor property.

long

BitRate

The bitrate, in bits per second, when the EnableRateControl value is TRUE. Note that this is not in the same units as in the property page. The property page shows the bitrate in Kbits/second, while the BitRate property uses bits/second. For example, 1000 Kbps is achieved by setting this value to 1,000,000 (one million).

long

QualityFactor

Contains the video quality factor. A quality factor of 1 gives the highest quality and the largest video file size. A quality factor of 50 gives the lowest quality and smallest file size. This property is valid only if the EnableRateControl property is FALSE.

eH265FRAMEINTERVALUNIT

IFrameIntervalUnit

Represents the unit for the IFrameInterval property or how the IFrameInterval property is interpreted by the encoder. If IFrameIntervalUnit = H265INTERVALUNIT_PFRAME, then the IFrameInterval represents the I-frame interval in term of P frames. If IFrameIntervalUnit != H265INTERVALUNIT_FRAME, then I-frame Interval is in terms of P and B frames.

long

IFrameInterval

If IFrameIntervalUnit = H265INTERVALUNIT_PFRAME then this property specifies the number of P frames between two successive I frames plus one. A value of zero means there is only one I in the whole video and all the other frames are either P or B . If this value is one there will be NO P frame between any two I frames. If the value is 2 there will be ONE P frame between any two I frames and so on.

If IFrameIntervalUnit = H265INTERVALUNIT_FRAME then this property specifies the number of frames between two successive I-frames. In other words it specifies the "Group of Pictures (GOP)" length. A value of zero means there is only one I-frame in the whole video and all the other frames are either P or B. If this value is one there will no P or B frames between any I frames.

long

PFrameInterval

Specifies the number of B frames between two successive P frames.  Note that all the frames between successive P frames are B frames.

VARIANT_BOOL EnableCompressionEngine (eH265COMPRESSIONENGINE compressionEngine, VARIANT_BOOL *pEnabled)

Flag that indicates whether a certain compression engine should be used.

The compressionEngine parameter indicates which compression engine to enable or disable.

The pEnabled parameter indicates whether the compression engine should be enabled.

Currently the following values can be passed for compressionEngine:

H265COMPRESSIONENGINE_QUICKSYNC_HARDWARE [1]: Intel Quick Sync Video hardware acceleration. If you disable this compression engine, the encoder 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 H264CAPABILITY_QUICKSYNC).

H265COMPRESSIONENGINE_CUDA_HARDWARE [2]: NVIDIA CUDA hardware acceleration. If you disable this compression engine, the encoder 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 does not contain H264CAPABILITY_CUDA).

The H265COMPRESSIONENGINE_INTELQUICKSYNC value is equivalent to the H265COMPRESSIONENGINE_QUICKSYNC_HARDWARE value.

float

 

FrameRate

Sets the playback frame rate, in frames per second, of the compressed video, regardless of the rate of the input stream frames. The LEAD H265 Encoder automatically adjusts the input video to match the desired frame rate. The rate is adjusted by dropping or duplicating input frames. If the selected frame rate is lower than the original framerate, the compression will be higher.

Use the value -1 if the output frame rate needs to be the same as the input frame rate.

eH265OUTPUTFORMAT

OutputFormat

Value that specifies the output format. For a list of possible values, refer to eH265OUTPUTFORMAT.

long PreferredCUDADevice

A read-write property indicating which CUDA device to use (0-based). This property is useful only when the encoder is using the NVIDIA encoder and when the system has more than one NVIDIA graphics card with CUDA capabilities. The property can be set to the following values:

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

In general, it is better for the compressions to be balanced among the existing CUDA devices. Conversions will be faster and you will also avoid burnout situations, (in which the card can be destroyed by over-use if the fan does not cool the card properly). GPUCount indicates the number of CUDA-capable devices and can be obtained with the GetCUDAInfo method.

You can set this property to indicate which device to use. 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.

This property is useful only if you have more than one CUDA device on your computer.

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).
VARIANT_BOOL EnableDriftCorrector Property indicating whether the encoder should automatically correct timestamp drifting. If VARIANT_FALSE, timestamps are not corrected. If VARIANT_TRUE, the encoder will automatically correct timestamps that drift over time.
If this property is enabled (set to VARIANT_TRUE), the encoder will work together with any other encoders in the current graph to correct drifts and synchronize audio and video. Currently, only the LEAD H264, H265 and AAC Encoders support this feature.
The default value for this property is VARIANT_FALSE (timestamp drifting is not corrected).
This is an advanced low-level setting that should be set to a VARIANT_TRUE value only if:
  1. you are in a capture situations (it will NOT work properly in file conversion situations)
  2. you are discovering that audio and video streams lose synchronization after running for a while (typically a few hours).

If you are unsure whether to use it or not, leave this property set to VARIANT_FALSE, because setting it incorrectly can cause big problems. See the Timestamp drifting in live capture situations topic for more details.
This property was added mainly to solve problems with some Decklink video capture cards. The problems were as follows:

  1. at the beginning of the capture, there was a slight drift (around 60-90ms) between the audio and video streams.
  2. the drift was increasing after a few hours.
Setting this property to VARIANT_TRUE (or True in some languages) solves these problems.

Interface Methods:

HRESULT WriteToRegistry ()

Description

Writes the values of all of the properties listed above to the system registry, so that the encoder will remember these settings the next time it is used.

The property page calls this method when you click the Apply or OK buttons after changing some values in the property page.

Returns

S_OK if successful; otherwise,  S_FALSE. 

HRESULT  ResetToDefaults (eH265APILEVEL ApiLevel)

Parameters

eH265APILEVEL ApiLevel

Description

Resets resizing to default values. The ApiLevel determines which default values to use. Current applications should set ApiLevel to H265_APILEVEL_1 = 0.

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

It is best to call ResetToDefaults(H265_APILEVEL_1) before you start setting properties and start calling other methods for this interface if you modify all of the encoder settings.

Returns

S_OK

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 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 the 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 the 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 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 LEAD H265 Encoder User Interface.

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 encoder might be able to use CUDA hardware encoding even if the installed version is less than the recommended version. But some features might not be available or the encoding 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 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 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 entire time) and 100 (the device was in use the entire 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. The problem will NOT go away by restarting the computer or by turning the computer off so the card cools down. The card is damaged for good and has to be replaced.

Returns

S_OK if successful

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.

Data Types:

1. eH265OUTPUTFORMAT:

typedef enum 
{ 
   H265FORMAT_AUTO = 0, 
   H265FORMAT_MAIN= 1, /* Main profile output using byte stream format (compatible with MPEG file format, uses 00 00 01 start codes) */ 
   H265FORMAT_MAIN_HVC1 = 2,   /* Main Profile output using NAL unit stream format (compatible with ISO/MP4 file format) */ 
} eH265OUTPUTFORMAT; 

 Lists the possible values for the output mode, set in the OutputFormat property.

2. eH265APILEVEL

typedef enum 
{ 
   H265_APILEVEL_1 = 0, 
} eH265APILEVEL; 

3. eH265FRAMEINTERVALUNIT

typedef enum 
{ 
   H265INTERVALUNIT_PFRAME = 0, 
   H265INTERVALUNIT_FRAME = 1, 
} eH265FRAMEINTERVALUNIT; 

Lists the possible frame interval units to be interpreted by the encoder, set in the IFrameIntervalUnit property.

4. eH265CAPABILITY

typedef enum 
{ 
   H265CAPABILITY_SOFTWARE = 0, 
   H265CAPABILITY_QUICKSYNC = 1, 
   H265CAPABILITY_CUDA = 2, 
} eH265CAPABILITY; 

Lists the possible capabilities that can be reported by the Capability property. The Capability property will return a bitwise or combination of the above flags. If no bit is set, only software compression is supported. 

5. eH265COMPRESSIONENGINE

typedef enum 
{ 
   H265COMPRESSIONENGINE_QUICKSYNC_HARDWARE = 1, 
   H265COMPRESSIONENGINE_INTELQUICKSYNC = H265COMPRESSIONENGINE_QUICKSYNC_HARDWARE, 
   H265COMPRESSIONENGINE_CUDA_HARDWARE = 2, 
} eH265COMPRESSIONENGINE; 

Lists the possible types of compression engines that can be used with the EnableCompressionEngine property. The H265COMPRESSIONENGINE_CUDA_HARDWARE value has been added to enable or disable CUDA hardware compression using the EnableCompressionEngine property.

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