vdxa_drawingaquad - shekh/VirtualDub2 GitHub Wiki

VirtualDub Plugin SDK 1.2

Drawing a quad

The basic unit of rendering in the VDXA API is a quadrilateral, or quad. This is a polygon with four points. Actually, it's even more restrictive since it's a 2D axis-aligned rectangle, but it's still a quad. Because all rendering occurs via quads, a decent amount of setup is involved.

Requirements

The following must be set up prior to rendering a quad:

Texture samplers
Texture matrices
Program constants

These are considered persistent state, so if multiple quads share common parameters you can set them up only once. State is reset upon entry to the filter, however, so full setup is required for each frame processed.

Texture samplers

To assign a texture to a texture sampler, use the IVDXAContext::SetSampler function. This binds the texture for use by the fragment program. You must also supply a filtering mode, which determines how the texture is upsampled when texels are fetched.

Ordinarily you do not need to bind a texture to a sampler more than once, as you can read from a sampler multiple times with different coordinates. Note that one traditional reason for doing so is not permitted: you may not bind the same texture to multiple samplers in order to read the same texture with differing filter modes. This is not permitted, as it is impossible to support in OpenGL. Unused samplers do not count against this restriction, however.

Texture matrices and texture coordinate interpolators

As said before, VDXA does not allow access to the vertex program (vertex shader). It does supply a pass-through vertex program, however, that allows access to all eight texture coordinate interpolators. These are set up in the VDXA API through texture matrices, which are used to initialize the interpolators.

There are two ways to set up an interpolator:

Texture handle and offset
If you supply a texture handle, VDXA automatically sets up the interpolator to iterate over the entire source image, translated by a supplied (x, y) offset. This is the easiest way to set up an interpolator since any difference in size between the image and the containing surface or texture is accounted for. Most convolution algorithms can be set up using this method.

Direct 4x3 matrix
In cases where the default mapping is not sufficient, the interpolator may be set up directly with a 4x3 matrix. An arbitrary linear mapping for all four components may be set up this way. This is useful when using the interpolators to supply information not related to texture coordinates, such as a vertical phase or x/y coordinate.

Unless you want every pixel to be exactly the same color in the output, at least one interpolator needs to be set up, because otherwise there is no source of varying input to the fragment program.

Program constants

32 4-vector program constants can be passed to the fragment program. These are set up by calling IVDXAContext::SetFragmentProgramConstF() with the range and constant data. Constants may be changed for each drawing operation, but always have the same value for every iteration of the fragment program within an operation.

Because VDXA does not support named constant binding, fragment programs must hardcode the constant register used for each constant. In HLSL, this is done using a register semantic:

extern float4 myconst : register(c4);

Program constants are best used for either configuration parameters or precomputing constant expressions to save program cycles. They should not be used for values that are truly constant; those should be declared as constants in the fragment program itself to give the compiler a chance to optimize based on their value. In cases where the constant is dependent upon a configuration parameter and the compiler could do significant optimization based on certain values, it may be worth creating multiple fragment programs.

Drawing the quad

Once setup is complete, call IVDXAContext::DrawQuad() to draw the quad, specifying the fragment program to use and the render target to draw into. The entire image space, including any borders, are rendered.