---

DGDecodeNV 2053

---

What is DGDecodeNV?
Filter Syntax
   DGSource()
   DGDenoise()
   DGSharpen()
   DGTelecide()
   DGDecimate()
   DGBob()
   PVBob()
Usage Examples
   LoadPlugin() Example
   DGSource() Examples

What is DGDecodeNV?

Table of Contents

DGDecodeNV is an Avisynth source filter (AviSynth v2.6 or higher) that decodes and frame-serves AVC (H.264), HEVC (H.265), VC1, and MPEG2 video. It works in conjunction with the indexing tool DGIndexNV.

The "NV" in the name "DGDecodeNV" indicates that this version of the program is designed for use with the GPU decoder on some Nvidia video cards. See here to check whether your video card has a VP2 or greater engine:

Table of Nvidia Graphics Cards Specifications

You can get the latest binaries of DGDecodeNV at http://rationalqm.us/dgdecnv/dgdecnv.html.

Filter Syntax

Table of Contents

DGSource()

Table of Contents

DGSource(str "dgi", bool i420, int deinterlace, bool use_top_field, bool use_pf, int ct, int cb, int cl, int cr, int rw, int rh, int fieldop, bool show, bool fulldepth)

DGSource() is a source filter that delivers decoded video in YV12/i420/YUV420P16 format. DGSource() exports the Avisynth environment variable FFPICT_TYPE to denote the frame coding type: 'I', 'P', or 'B'. 'U' is used when the type is unknown or cannot be unambiguously labeled. If a field is pulled down by soft pulldown, the frame type of the coded frame corresponding to the non-pulled-down field is given.

dgi: "[PATH\]project.dgi"

DGIndexNV Project File.
Required parameter!
Note 1: PATH\ can be omitted if "project.dgi" is in the same directory as your AviSynth (*.avs) script.


i420: true/false (default: false)

Deliver i420 instead of YV12.

deinterlace: 0/1/2 (default: 0)

Nvidia PureVideo Deinterlacer
0: no deinterlacing
1: single rate deinterlacing
2: double rate deinterlacing (bobbing)

Note that double rate deinterlacing requires Windows XP SP3!

Also note that setting deinterlace to 1 or 2 forces the field operation to be "Ignore Pulldown", regardless of the project setting.

use_top_field: true/false (default: true)

Use the top field for single rate deinterlacing.
When this parameter is true, the top field is used for single rate deinterlacing; when false the bottom field is used. When deinterlace=0 or deinterlace=2, this parameter is ignored.

use_pf: true/false (default: false)

Use the progressive_frame indication from NVCUVID. If deinterlace=1 or deinterlace=2, and use_pf=true, then only frames marked as interlaced by NVCUVID will be deinterlaced. If deinterlace=1 or deinterlace=2, and use_pf=false, then all frames will be deinterlaced.

ct, cb, cl, cr: integer (default: 0)

Use the GPU to crop the video. The letter c in the parameter stands for "crop" and the letters t/b/l/r stand for top/bottom/left/right, so "cb" specifies the amount to crop off the bottom of the frame. You can use the cropping tool in DGIndexNV to help in determining good values for these parameters and for optionally exporting them to the Avisynth script via the template __crop__ macro (refer to the DGIndexNV user manual for details).

Important note 1: The cropping values are relative to the original coded size and not relative to the coded display area. For example, if your stream has a coded height of 1088 but a display height of 1080, then if you want to crop off 8 pixels from the 1080 to make 1072, then your crop value will be 16, i.e., 8 to get from 1088 to 1080, and then 8 more to get your desired crop. This is different from what is done by some other applications that do not expose the coded size to the user. If you use the DGIndexNV cropping tool this will be handled for you automatically.

Important note 2: The nVidia driver is currently broken such that mod-2 cropping of the top and left sides is broken, and so the values of ct and cl must be mod-4. Right and bottom cropping may be mod-2. DGDecNV allows you to specify mod-2 values for top and left, however, looking forward to a fix from nVidia.


rw, rh: integer (default: 0)

Use the GPU to resize the video. The resizing is applied after deinterlacing. If either rw or rh is 0, no resizing is performed. If you need to crop before resizing, use the ct/cb/cl/cr parameters described above.

fieldop: 0/1/2 (default: 0)

0: Honor Pulldown Flags
1: Force Film
2: Ignore Pulldown Flags

AVC, MPG, and VC1 video each provide syntax elements that enable a single field of any frame to be repeated automatically during display ("pulled down"). The extra fields do not occupy space in the video stream but are simply created by copying when the stream is decoded and displayed. This facility is most often used to display film rate clips (23.976 fps) at the NTSC rate (29.97 fps), a process called 3:2 pulldown. In practice, however, pulldown in various different patterns is commonly encountered. It can be used, for example, to display 25 fps PAL at the NTSC rate. One way to learn about "telecining" and "3:2 pulldown" is to perform a search for those terms using our friend Google.

Understanding the theory and practice required to properly set this option for a given application is nontrivial. Here we can only define the operations and give some general guidance. There is ample additional material available in existing guides.

The fieldop setting allows the user to specify how the pulldown flags are to be handled.

• Honor Pulldown Flags (fieldop=0) - The pulldown flags (if any) are obeyed and the fields are repeated. This means that the frame-served video will appear exactly as it is intended to appear on the final display device. Therefore, if you have a 3:2 pulled-down clip, you'll get the standard repeating pattern of 3 progressive frames followed by 2 interlaced frames. If you have PAL, you'll just get the encoded pictures with no repeated fields (because PAL has no pulldown flags to honor). The frame rate will always be the same as the display frame rate of the source.
• Ignore Pulldown Flags (fieldop=2) - The pulldown flags are ignored. This allows one to obtain the raw encoded pictures, with no repeated fields. However, because repeated fields intended for display are ignored and not displayed, the resulting frame rate may differ from the source frame rate. It may even vary throughout the clip, due to irregular patterns of pulldown flags. If the pulldown is irregular, use of this option will cause the audio-video sync to change at different parts of the clip, and most likely sync will not be acceptable. This option is mostly intended for power users, who would use it as a diagnostic aid for inspecting the encoded pictures. Although this option ignores the flags, they are still stored in the DGI file although DGDecodeNV will ignore them.
• Force Film (fieldop=1) - This option is intended for the special case of film content encoded at 23.976 fps but pulled down for display at 29.97 fps, i.e., 3:2 pulldown. This option will restore the 23.976 fps film rate while keeping audio and video in sync throughout the clip. This option works by ignoring pulldown flags and adjusting the frame rate back to the film rate. Do not use this option on non-3:2 pulled-down material, and, therefore, never use it on PAL.

The fieldop is perhaps the most important option to understand when using DGDecNV. Most users should first preview the project and inspect the DGIndexNV Information Panel. If the clip is 29.976fps, and the Field Repeats box in the Information Panel indicates field repeats consistent with 3:2 pulldown, then it is likely that the clip can be treated as 3:2 pulldown material, and so Force Film (fieldop=1) should be selected. Force Film can also be used on hybrid material and will decimate frames as required in video sections to maintain the film rate.

Otherwise, then you should leave fieldop=0 (Honor Pulldown Flags) for generation of the DGI file. If the result is combed (because the source is interlaced, hybrid interlaced/3:2, field blended, etc.), you may want to apply a deinterlacer or inverse telecine (IVTC) filter in your Avisynth script.

Almost invariably, if you know the source is not all 3:2 pulled-down NTSC, you will want to select Honor Pulldown Flags and then post-process as required. Keep in mind that if there are no pulldown flags, there is nothing to honor, so this option just delivers the encoded frames.

fieldop=2 (Ignore Pulldown Flags) should be necessary only for advanced users who want to see just the exact coded pictures in the video stream.


show: true/false (default: false)

Enable textual information overlay on the output video frames. Currently the information displayed is the DGDecodeNV version number, the GOP number, the display and coded frame numbers, and the frame coding type. Note that if leading orphaned B frames exist at the beginning of the stream, they are replaced with copies of the first I frame, and so the overlay will show data for the first I frame for each of the leading orphaned B frames. Also note that the frame numbers appropriately reflect the setting of the fieldop option.


show2: string (default: "")

Modifies the display of the show parameter (show must be set to true for this to have any effect). The control string has this format: "x,y,custom", where x and y give the offset in the frame for display of the show information, and custom is a string that will be displayed as the last line of the displayed information. If no custom string is needed, leave that field blank. It is the users responsibility to ensure that the displayed information is not pushed off the frame as that will cause a crash (error checking for this will be added in a future version).


fulldepth: true/false (default: false)

When fulldepth=true and the encoded video is HEVC 10-bit or 12-bit, then DGSource() delivers 16-bit data to Avisynth with the unused lower bits zeroed. The reported pixel format is CS_YUV420P16. If either of the two conditions are not met, then DGSource() delivers 8-bit YV12 or I420 data, as determined by the i420 parameter. When fulldepth=false and the video is HEVC 10-bit or 12-bit, then the video is dithered down to 8-bit for delivery. If you need a reduced color space (less than 16 bits) for your high-bit-depth processing, you can use ConvertBits() as needed after your DGSource() call.

DGDenoise()

Table of Contents

DGDenoise(clip c, float strength, float blend, bool chroma, int searchw, int device)

DGDenoise() is a fast stand-alone CUDA filter that implements NLM denoising. The input clip must be in the YV12 or YUV420P16 format. DGSource() delivers YUV420P16 when the source stream has a 10/12/16-bit depth and the fulldepth option is set to true.

c: Avisynth clip (default: last)

strength: float value (default: 0.15)

Strength of the Non-Local Means (NLM) denoising. Typical values for strength are in the range 0.1-1.0. Note that if you have interlaced source you should deinterlace with deinterlace=1 or deinterlace=2. If you have hard pulldown, or you have soft pulldown that is being honored, then invoke it through DGDenoise() after performing external IVTC. The essential point to remember is that denoising should be applied to progressive frames. If you must retain interlacing, then separate the fields, apply DGDenoise(), and then re-weave the fields.


blend: float value (default: 0.1)

Blending coefficient for the NLM denoising with range 0.0 to 1.0. Use lower values to blend in less of the original pixel.


chroma: true/false (default: false)

When set to true NLM denoising is applied to the chroma as well as the luma.


searchw: 5/7/9 (default: 5)

Width of the search window for the NLM denoising. Wider windows may improve quality at the expense of speed.


device: int (default: 255)

When set to 255, the first GPU found is used. When set to any other value the GPU with that ordinal value is used.

DGSharpen()

Table of Contents

DGSharpen(clip c, float strength, int device)

DGSharpen() is a fast stand-alone CUDA filter that implements limited sharpening like the well-known filter LimitedSharpenFaster(). The input clip must be in the YV12 or YUV420P16 format. DGSource() delivers YUV420P16 when the source stream has a 10/12/16-bit depth and the fulldepth option is set to true.

c: Avisynth clip (default: last)

strength: float value (default: 1.0)

Strength of the sharpening. Typical values for strength are in the range 0.1-1.0. Note that if you have interlaced source you should deinterlace with deinterlace=1 or deinterlace=2. If you have hard pulldown, or you have soft pulldown that is being honored, then invoke it through DGSharpen() after performing external IVTC. The essential point to remember is that sharpening should be applied to progressive frames. If you must retain interlacing, then separate the fields, apply DGSharpen(), and then re-weave the fields.


device: int (default: 255)

When set to 255, the first GPU found is used. When set to any other value the GPU with that ordinal value is used.

DGTelecide()

Table of Contents

DGTelecide(clip c, int mode, float pthresh, float dthresh, bool blend, bool map, bool show, int device)

DGTelecide() is a fast stand-alone CUDA filter that implements field matching and adaptive deinterlacing. The input clip must be in the YV12 format. Note that DGTelecide() requires the field order to be properly specified. The safest policy is to always set the correct order using AssumeTFF()/AssumeBFF(). AVISource() is dangerous without doing so because it always sets BFF. Note that DGSource() sets the correct field order, so when it is used as the source filter it is not necessary to manually set the field order.

DGTelecide() reconstructs the original progressive frames by properly matching fields. Sometimes, due for example to bad edits, a good match cannot be found and a progressive frame cannot be reconstructed. In that case, if postprocessing is enabled (mode = 1), the frame will be deinterlaced so that a bad frame is not delivered. DGTelecide() also provides modes for pure adaptive deinterlacing without field matching. Refer to the description for the mode parameter for details.

c: Avisynth clip (default: last)

mode: int value (default: 0)

Mode of operation:

Mode 0: Field matching without adaptive deinterlacing of frames with a bad match (no postprocessing).
Mode 1: Field matching with adaptive deinterlacing of frames with a bad match (postprocessing).
Mode 2: Adaptive deinterlacing of all frames (unconditional deinterlacing).
Mode 3: Adaptive deinterlacing of frames determined to be combed (conditional deinterlacing).


pthresh: float value (default: 0.0)

Threshold for postprocessing. If the metric for a matched frame exceeds pthresh, the frame will be deinterlaced. Use the show option to see the metrics and thereby set an appropriate pthresh value. Postprocessing applies only to frames with no good match and it allows DGTelecide() to deliver reasonable looking frames in such instances.


dthresh: float value (default: 10.0)

Threshold for adaptive deinterlacing. This threshold is used to detect interlaced lines. Lower values deinterlace more of the frame, while higher values deinterlace less. Use the map option to visualize the lines detected as interlaced and thereby set an appropriate dthresh value.


blend: bool (default: false)

When blend=true deinterlaced frames are deinterlaced using field blending. When blend=false deinterlaced frames are deinterlaced using field interpolation.


map: bool (default: false)

When set to true, then for deinterlced frames, lines detected as interlaced are shown in white. Use this option to appropriately set your deinterlacing threshold dthresh.


show: bool (default: false)

When set to true, metrics information is overlaid onto the frame.


device: int (default: 255)

When set to 255, the first GPU found is used. When set to any other value the GPU with that ordinal value is used.

DGDecimate()

Table of Contents

DGDecimate(clip c, int cycle, int keep, int device, bool show)

DGDecimate() is a fast stand-alone CUDA filter that implements N-in-M frame decimation. The input clip must be in the YV12 format.

c: Avisynth clip (default: last)

cycle: int value (default: 5, max 40)

Decimation cycle size M. For every cycle of M frames, N frames will be retained, where N is given by the keep parameter. The M - N frames that differ least from their predecessors are discarded.


keep: int value (default: 4)

Decimation keep number N. For every cycle of M frames, N frames will be retained, where N is given by the keep parameter. The M - N frames that differ least from their predecessors are discarded.


device: int (default: 255)

When set to 255, the first GPU found is used. When set to any other value the GPU with that ordinal value is used.


show: bool (default: false)

When set to true, metrics information is overlaid onto the frame. Note that if the cycle size is greater than 10, only the first 10 frame metrics are shown.

DGBob()

Table of Contents

DGBob(clip c, int order, int mode, int device)

DGBob() is a fast stand-alone CUDA filter that implements the YADIF deinterlacing algorithm (original concept by Michael Niedermayer). The input clip must be in the YV12 format. Note that DGBob() requires the field order to be properly specified. DGBob can take the order from Avisynth but the safest policy is to set the correct order using the 'order' parameter. For example, AVISource() is dangerous without doing so because it always sets BFF. Note that DGSource() sets the correct field order, so when it is used as the source filter it is safe to omit the 'order' parameter or set it to -1.

c: Avisynth clip (default: last)

order: int value (default: -1)

Field order: -1: take order from Avisynth, 0: BFF, 1: TFF.


mode: int value (default: 1)

Rendering mode: 0: single-rate deinterlacing, 1: double-rate deinterlacing, 2: double-rate deinterlacing but retain the original frame rate (for slow motion).


device: int (default: 255)

When set to 255, the first GPU found is used. When set to any other value the GPU with that ordinal value is used.

PVBob()

Table of Contents

PVBob(clip c, int order, int mode, int device)

PVBob() is a stand-alone version of the PureVideo deinterlacer. This is the same functionality that you get using the deinterlace parameter of DGSource(). If you are sourcing your video using DGSource(), it is always preferable to invoke the deinterlacer using DGSource() rather than PVBob(). PVBob() is intended for use when a different source filter is used. The input clip must be in the YV12 format. Note that PVBob() requires the field order to be properly specified. PVBob can take the order from Avisynth but the safest policy is to set the correct order using the 'order' parameter. For example, AVISource() is dangerous without doing so because it always sets BFF.

c: Avisynth clip (default: last)

order: int value (default: -1)

Field order: -1: take order from Avisynth, 0: BFF, 1: TFF.


mode: int value (default: 1)

Rendering mode: 0: single-rate deinterlacing, 1: double-rate deinterlacing.


device: int (default: 255)

When set to 255, the first GPU found is used. When set to any other value the GPU with that ordinal value is used.

Usage Examples

Table of Contents

AviSynth LoadPlugin() Example

Table of Contents

AviSynth's LoadPlugin() must be called before any DGDecodeNV functions can be used.
To accomplish this, add a line like the following one to the beginning of your AviSynth (*.avs) script:


LoadPlugin("C:\My Files\DGDecodeNV.dll")

Note: This load plugin line can be omitted if DGDecodeNV.dll is in the default AviSynth plug-ins directory, because Avisynth will load it automatically.

DGSource() Examples

Table of Contents

To decode:


DGSource("C:\My Files\project.dgi")

Note: The path can be omitted if "project.dgi" is in the same directory as your AviSynth (*.avs) script.

nVidia PureVideo deinterlacing:


DGSource("project.dgi", deinterlace=1)


Resizing:


DGSource("project.dgi", rw=1280, rh=720)


Denoising:


DGSource("project.dgi")
DGDenoise(strength=0.15)


Sharpening:


DGSource("project.dgi")
DGSharpen(strength=0.75)


Inverse telecine (IVTC) (for hard 3:2 pulldown):


DGSource("project.dgi")
DGTelecide(mode=1, pthresh=3.5)
DGDecimate()


Deinterlacing (without using nVidia PureVideo):


DGSource("project.dgi")
DGTelecide(mode=2, dthresh=7.5)