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
```cpp
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
```cmake
# 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*