video-v1/vav2/docs/completed/hardware-acceleration/AMD_AMF_AV1_Decoder_Design.md

AMD AMF AV1 Decoder Design Document

Overview

This document describes the design and implementation of the AMD AMF (Advanced Media Framework) AV1 decoder integration within the VavCore library. The AMF decoder provides hardware-accelerated AV1 decoding on AMD GPUs.

Architecture

Class Hierarchy

IVideoDecoder (interface)
└── AMFAV1Decoder (implementation)

Key Components

• AMFAV1Decoder: Main decoder class implementing IVideoDecoder interface
• VideoDecoderFactory: Factory class extended to support AMF decoder creation
• AMF SDK Integration: Direct integration with AMD AMF SDK headers and libraries

Implementation Details

File Structure

VavCore/src/Decoder/
├── AMFAV1Decoder.h          # AMF decoder header
├── AMFAV1Decoder.cpp        # AMF decoder implementation
├── VideoDecoderFactory.h    # Updated factory header
└── VideoDecoderFactory.cpp  # Updated factory implementation

Dependencies

• Headers: D:\Project\video-av1\include\amf\
  • amf/core/Factory.h
  • amf/core/Context.h
  • amf/components/VideoDecoderUVD.h
  • amf/core/Surface.h
• Libraries: D:\Project\video-av1\lib\amf\
  • amf.lib (Release)
  • amf-debug.lib (Debug)
  • amf.dll / amf-debug.dll (Runtime)

Core Functionality

Initialization Process

1. AMF Library Loading: Load external AMF component via g_AMFFactory.LoadExternalComponent()
2. Context Creation: Create AMF context using CreateContext()
3. Graphics API Initialization: Initialize DirectX 11 (fallback to DirectX 9)
4. Decoder Component Creation: Create AV1 decoder using AMFVideoDecoderHW_AV1
5. Property Configuration: Set decoder properties (surface copy, reorder mode)

Decoding Pipeline

AV1 Packet → AMFBuffer → AMF Decoder → AMFSurface → VideoFrame

1. Input Processing: Create AMFBuffer and copy packet data
2. Submission: Submit input buffer to decoder via SubmitInput()
3. Output Query: Poll for decoded frames using QueryOutput()
4. Surface Conversion: Convert AMFSurface to VideoFrame with proper format handling

Surface Format Support

• NV12: Primary format with interleaved UV plane conversion
• YUV420P: Planar YUV 4:2:0 format
• YUV422P: Planar YUV 4:2:2 format (if supported)
• YUV444P: Planar YUV 4:4:4 format (if supported)

Error Handling

AMF Error Codes

Comprehensive mapping of AMF result codes to human-readable messages:

• AMF_OK: Success
• AMF_FAIL: General failure
• AMF_NOT_SUPPORTED: Feature not supported
• AMF_NO_DEVICE: No compatible AMD device
• AMF_INPUT_FULL: Input queue full (retry required)
• AMF_REPEAT: Output not ready (normal for some frames)

Error Recovery

• Initialization Failure: Graceful fallback to other decoders
• Runtime Errors: Frame-level error handling with statistics tracking
• GPU Context Loss: Automatic cleanup and re-initialization capability

Integration with VideoDecoderFactory

Decoder Priority Order (AUTO mode)

1. ADAPTIVE_NVDEC: NVIDIA adaptive decoder (highest priority)
2. AMF: AMD AMF decoder (new addition)
3. ADAPTIVE_DAV1D: dav1d adaptive decoder
4. NVDEC: NVIDIA hardware decoder
5. DAV1D: dav1d software decoder
6. MEDIA_FOUNDATION: Windows Media Foundation (fallback)

Factory Enhancements

• Added DecoderType::AMF enumeration
• Implemented CheckAMFAvailability() method
• Updated decoder creation logic with AMF support
• Added AMF decoder to supported decoders list

Performance Characteristics

Expected Benefits

• Hardware Acceleration: GPU-based decoding for reduced CPU usage
• Low Latency: Optimized for real-time playback scenarios
• Memory Efficiency: Direct GPU memory handling
• Power Efficiency: Lower power consumption compared to software decoding

Potential Limitations

• AMD GPU Requirement: Only works on systems with AMD GPUs
• Driver Dependency: Requires recent AMD graphics drivers with AMF support
• Format Restrictions: Limited to AMF-supported pixel formats

Configuration Options

Decoder Properties

• Surface Copy Mode: Enables CPU access to decoded surfaces
• Reorder Mode: Set to low latency for real-time applications
• Memory Type: Host memory for easier CPU access

Customizable Parameters

• Maximum Resolution: Default 4096x4096, can be adjusted
• Output Format: Configurable surface format preference

Testing and Validation

Availability Testing

bool IsAMFAvailable() const {
    amf::AMFFactoryPtr temp_factory;
    AMF_RESULT result = amf::g_AMFFactory.LoadExternalComponent(temp_factory, L"AMFFactory");
    return (result == AMF_OK && temp_factory);
}

Performance Metrics

• Decode Time Tracking: Per-frame decode time measurement
• Error Rate Monitoring: Failed decode attempts tracking
• Throughput Analysis: Frames per second performance

Future Enhancements

Potential Improvements

1. Adaptive Quality Control: Dynamic resolution scaling based on performance
2. Multi-GPU Support: Load balancing across multiple AMD GPUs
3. Advanced Memory Management: Zero-copy optimization with GPU memory
4. HDR Support: High Dynamic Range content decoding
5. Hardware-specific Optimizations: RDNA/RDNA2 specific enhancements

Integration Possibilities

• Vulkan Context: Alternative to DirectX for cross-platform support
• OpenCL Integration: Compute shader-based post-processing
• Multi-threaded Decoding: Parallel decode streams

Dependencies and Build Configuration

Required Libraries

# AMF libraries (to be added to VavCore.vcxproj)
target_include_directories(VavCore PRIVATE
    "D:/Project/video-av1/include/amf"
)

target_link_libraries(VavCore PRIVATE
    debug "D:/Project/video-av1/lib/amf/amf-debug.lib"
    optimized "D:/Project/video-av1/lib/amf/amf.lib"
)

Runtime Requirements

• AMD GPU with AMF support (Radeon HD 7000 series or newer)
• AMD graphics driver with AMF runtime (Adrenalin 19.7.1 or newer)
• DirectX 11 runtime (fallback to DirectX 9)

Troubleshooting Guide

Common Issues

1. AMF Library Not Found: Check AMD driver installation
2. Context Creation Failed: Verify DirectX runtime availability
3. Decoder Creation Failed: Confirm AV1 hardware support
4. Surface Conversion Errors: Check pixel format compatibility

Debug Output

Comprehensive logging system with categorized messages:

• [AMFAV1Decoder] prefix for all decoder messages
• AMF error code translation with operation context
• Performance statistics in debug builds

---

Document Version: 1.0 Last Updated: 2025-09-26 Author: Claude Code Assistant