VRAM capture properties

A pin-centric AVStream minidriver must support several properties in order for it to capture to VRAM. This section describes the sequence of requests that the minidriver receives before and during VRAM processing.

Before capture is initiated, the KS proxy sends a KSPROPERTY_PREFERRED_CAPTURE_SURFACE get-property request. The minidriver should return different values depending on whether the driver is capturing to system memory or VRAM.

Capturing to system memory

To capture to system memory, return KS_CAPTURE_ALLOC_SYSTEM_AGP.

The capture driver then receives a KSPROPERTY_CURRENT_CAPTURE_SURFACE set-property request with a system memory value type. The capture driver now acts as bus-master DMA device and places the data directly into system memory.

In this mode, the capture driver receives system memory buffers in the AVStrMiniPinProcess callback function of the output pin.

For information about how to implement DMA in your pin process callback, see Packet-based DMA in AVStream.

To capture with multiple output pins (for instance, separate video, audio, and VBI pins), each pin should support the VRAM properties and processing as described earlier. The proxy generates a separate thread for each pin.

Capturing to VRAM

If your driver supports VRAM capture, return KS_CAPTURE_ALLOC_VRAM in response to KSPROPERTY_PREFERRED_CAPTURE_SURFACE.

The minidriver next receives a KSPROPERTY_DISPLAY_ADAPTER_GUID get-property request, querying for the display adapter's GUID.

Obtain the adapter GUID from the vendor-supplied graphics miniport driver. The DXGK_INTERFACESPECIFICDATA structure contains the adapter GUID to return in the property request. This structure is generated by the DirectX graphics kernel (DXGK) subsystem and is passed to the miniport driver when the adapter is initialized.

If the pin supports VRAM transport and the GUIDs of the display adapter and downstream filter match, the KS proxy module is selected as the allocator. The proxy notifies the capture pin about selection of VRAM surface transport between the pins by setting the KSPROPERTY_CURRENT_CAPTURE_SURFACE property with the selected surface type for the capture.

If the pin receives KS_CAPTURE_ALLOC_VRAM, it will then receive VRAM processing requests.

VRAM processing requests consist of two parts. First, the capture driver receives a get-request of KSPROPERTY_MAP_CAPTURE_HANDLE_TO_VRAM_ADDRESS. The get handler receives an IRP that contains the kernel-mode VRAM surface handle.

The capture driver or the display miniport driver should map the VRAM surface handle to an actual VRAM physical address. The VRAM surface handle does not remain valid; do not cache it for later use.

Return the mapped address in the VRAM_SURFACE_INFO_PROPERTY_S that was provided in the property request. The capture driver can issue an IOCTL to request the mapping from the display miniport driver.

Second, the capture filter's AVStrMiniPinProcess is called when a pin has data to process.

The minidriver should now call KsPinGetLeadingEdgeStreamPointer to acquire and lock the leading edge stream pointer for this pin. This function returns a pointer to a KSSTREAM_POINTER structure.

This stream pointer structure contains a pointer to a KSSTREAM_HEADER.

In the Data member of the stream header, find a pointer to a VRAM_SURFACE_INFO structure.

This structure contains the physical address returned in response to KSPROPERTY_MAP_CAPTURE_HANDLE_TO_VRAM_ADDRESS. The hSurface member that represents the handle is NULL.

The capture driver should:

• Program the capture hardware with the VRAM physical address.

• Handle the video frame completion.

• Fill in the cbCaptured member of VRAM_SURFACE_INFO with the number of bytes copied into the VRAM surface. Do not set the DataUsed member of KSSTREAM_HEADER with the number of bytes captured. Instead, set DataUsed to sizeof(VRAM_SURFACE_INFO).

• If your capture driver performs timestamping, set PresentationTime, Duration, and, if relevant, OptionsFlags in KSSTREAM_HEADER.

• Call KsStreamPointerAdvanceOffsets to continue processing or delete all clones and complete the request by calling KsStreamPointerDelete.

The CCapturePin::ProcessD3DSurface method in the Capture.cpp file in the AVStream Simulated Hardware Sample Driver (AVSHwS) in the Windows Driver Kit (WDK) samples shows one way to implement this callback for VRAM support.