video-v1/vav2/docs/working/NVDEC_RingBuffer_Decode_Design.md

NVDEC RingBuffer-based Asynchronous Decoding Design

Date: 2025-10-05 (Updated - CurrPicIdx Simplification) Status: ✅ Design Finalized - Ready for Implementation (Improved Architecture) Target: NVDECAV1Decoder DecodeToSurface() optimization using NVDEC's native CurrPicIdx

---

📋 Table of Contents

1. Background & Problem Statement
2. Design Goals
3. NVDEC CurrPicIdx Design Philosophy ⭐ NEW
4. Architecture Overview
5. Detailed Design
6. Implementation Plan
7. Performance Analysis
8. Risk Assessment
9. References

---

🎯 Background & Problem Statement

Current Implementation Issues

Issue 1: Sequential Decoding Bottleneck

Current Code (NVDECAV1Decoder::DecodeToSurface):

bool DecodeToSurface(packet_data, target_surface, output_frame) {
    cuvidParseVideoData(packet);           // Submit packet
    wait_for_frame();                      // Block until decode complete
    cuvidMapVideoFrame();                  // Map decoded frame
    CopyNV12Frame(srcPtr, target_surface); // Copy to surface
    cuvidUnmapVideoFrame();                // Unmap frame
    return true;
}

Timeline:

Call 1: [Submit][Wait____][Map][Copy][Unmap]
Call 2:                                      [Submit][Wait____][Map][Copy][Unmap]
Call 3:                                                                          [Submit][Wait____][Map][Copy][Unmap]

Total: ~45ms (15ms * 3)

Problem: GPU sits idle during packet submission and surface copying.

---

Issue 2: Packet-Surface Mapping Mismatch

Scenario: Multi-threaded DecodeToSurface calls

// Thread A
DecodeToSurface(packet1, surface1, frame1);  // I-frame, 15ms

// Thread B (simultaneous)
DecodeToSurface(packet2, surface2, frame2);  // P-frame, 3ms

// GPU completes out-of-order
packet2 completes @ t=3ms  → picture_index=5
packet1 completes @ t=15ms → picture_index=4

// Current queue-based retrieval
Thread A: pop() → picture_index=5 ❌ (gets packet2 result!)
Thread B: pop() → picture_index=4 ❌ (gets packet1 result!)

// Result: surface1 contains packet2, surface2 contains packet1

Root Cause:

• FIFO queue doesn't track which packet belongs to which surface
• Decoding completion order ≠ submission order

---

Issue 3: Multi-Frame Packet Handling ⚠️ Critical Discovery

Scenario: Single WebM packet contains multiple AV1 frames

// DecodeToSurface called ONCE
DecodeToSurface(packet_175bytes, surface1, frame1);

// NVDEC parser extracts MULTIPLE frames from single packet:
→ HandlePictureDecode(CurrPicIdx=0, IntraPicFlag=1)  // I-frame
→ HandlePictureDecode(CurrPicIdx=1, IntraPicFlag=0)  // P-frame
→ HandlePictureDecode(CurrPicIdx=2, IntraPicFlag=0)  // P-frame
→ ... (up to 8 frames in one packet)

// Problem: Which picture_index should be returned?
// Current design assumes: 1 packet = 1 frame ❌

Impact:

• Slot allocation assumes 1 packet → 1 slot → 1 picture_index
• Reality: 1 packet → 1 slot → N picture_indices
• Must track multiple picture_indices per slot
• Must decide which frame to return (first? last? all?)

---

Issue 3: ulNumOutputSurfaces Underutilization

NVDEC Configuration:

m_createInfo.ulNumOutputSurfaces = 8;  // 8 output buffers allocated

Purpose of 8 Surfaces:

1. Reference frame storage (AV1 needs up to 8 reference frames)
2. Display reordering buffer (B-frames, decode order ≠ display order)
3. Pipeline parallelism (overlap decode/map/copy operations)

Current Usage: Only 1-2 surfaces actually utilized → Wasted GPU memory (~24MB for 1920x1080)

---

🎯 Design Goals

Primary Goals

1. ✅ Correct Packet-Surface Mapping

   • Guarantee: DecodeToSurface(packetN, surfaceN) → surfaceN contains packetN result
   • No out-of-order completion issues

2. ✅ Sequential Return Order

   • Even if packet2 completes before packet1, return surface1 first
   • Maintain FIFO semantics for API users

3. ⚡ Parallel Decoding Throughput

   • Allow 2-3 packets to decode simultaneously on GPU
   • Reduce total decode latency by ~30-40%

4. 🛡️ Simplicity & Maintainability

   • Avoid complex ID mapping systems
   • Use fixed-size RingBuffer (matches NVDEC hardware design)
   • Single polling thread (not per-decode thread)

Non-Goals

• ❌ Full 8-frame parallel decoding (limited by reference frame dependencies)
• ❌ Out-of-order surface return (would break video playback semantics)
• ❌ Dynamic buffer sizing (fixed 8 slots matches NVDEC hardware)

---

🎯 NVDEC CurrPicIdx Design Philosophy

Discovery: Why ParseContext Cannot Work

During implementation, we attempted to pass per-picture user data through NVDEC callbacks using a ParseContext approach:

// ❌ Failed Approach: Trying to pass per-picture context
struct ParseContext {
    NVDECAV1Decoder* decoder;
    uint64_t slot_id;
};

// In DecodeToSurface():
ParseContext context(this, my_id);
m_parserParams.pUserData = &context;  // Try to change user_data
cuvidParseVideoData(m_parser, &packet);

Why It Failed:

1. cuvidCreateVideoParser() makes an internal copy of CUVIDPARSERPARAMS at parser creation time
2. Changing m_parserParams.pUserData after parser creation does not affect NVDEC's internal copy
3. NVDEC API provides parser-level user_data only, not picture-level user_data
4. The pUserData field is set once at parser creation and used for all callbacks

Evidence from Testing:

[DecodeToSurface] ParseContext created: magic=0xDEADBEEFCAFEBABE, decoder=000002E42CD9E4A0, slot_id=0
[HandlePictureDecode] ParseContext: magic=0x00007FFF71168468, decoder=0000000000000000, slot_id=0
[HandlePictureDecode] ERROR: Invalid ParseContext magic!

NVDEC's Native Ring Buffer Design

NVDEC is designed around a fixed 8-slot ring buffer architecture:

m_createInfo.ulNumOutputSurfaces = 8;  // NVDEC allocates 8 internal surfaces

NVDEC's Philosophy:

• Applications should use CurrPicIdx (0-7) as the direct ring buffer index
• NVDEC manages surface allocation and provides the index via pic_params->CurrPicIdx
• No custom slot_id allocation is needed - NVDEC already provides the slot index
• Applications maintain metadata arrays indexed by CurrPicIdx

Data Flow:

cuvidParseVideoData(packet)
    ↓
HandlePictureDecode(pic_params)
    ↓
CurrPicIdx = pic_params->CurrPicIdx  // 0-7 (NVDEC's ring buffer index)
    ↓
Use CurrPicIdx directly:
    m_ringBuffer[CurrPicIdx].target_surface = ...
    m_ringBuffer[CurrPicIdx].metadata = ...

Eliminated Complexity

Previous Approach (Unnecessary):

// ❌ Custom slot_id allocation
std::atomic<uint64_t> m_slotIdCounter{0};
uint64_t my_id = m_slotIdCounter.fetch_add(1);
size_t slot_idx = my_id % 8;

// ❌ Mapping CurrPicIdx → slot_id
std::unordered_map<int, uint64_t> m_pictureIndexToSlotId;
m_pictureIndexToSlotId[CurrPicIdx] = my_id;

New Approach (Direct CurrPicIdx):

// ✅ Use NVDEC's CurrPicIdx directly
int nvdec_slot = pic_params->CurrPicIdx;  // 0-7
m_ringBuffer[nvdec_slot].target_surface = ...;
m_ringBuffer[nvdec_slot].is_ready = true;

Key Insight

NVDEC provides CurrPicIdx for a reason:

• It's the canonical ring buffer index that NVDEC uses internally
• Applications are expected to maintain side-channel metadata indexed by CurrPicIdx
• No need for custom ID allocation or mapping tables
• Simpler, more efficient, and aligned with NVDEC's design

What We Need Instead:

• Store submission context (target_surface, surface_type) in a temporary variable
• Pass context to HandlePictureDecode via stack/member variable (not user_data)
• Use CurrPicIdx directly as ring buffer index in callback

---

🏗️ Architecture Overview

High-Level Design

┌─────────────────────────────────────────────────────────────────┐
│                    DecodeToSurface() Call                        │
│  (Thread 1, 2, 3, ... can call concurrently)                    │
└────────────┬────────────────────────────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────────────────────────────┐
│                        RingBuffer (8 slots)                      │
│  ┌─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐            │
│  │ [0] │ [1] │ [2] │ [3] │ [4] │ [5] │ [6] │ [7] │            │
│  └─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘            │
│     ▲                                             ▲              │
│     │                                             │              │
│  m_returnIndex                              m_submitIndex        │
│  (consumer)                                 (producer)           │
└────────────┬────────────────────────────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Polling Thread                              │
│  while (polling_running) {                                       │
│    slot = ringBuffer[m_returnIndex]                             │
│    if (cuvidGetDecodeStatus(slot.picture_index) == Success) {   │
│      slot.is_ready = true                                       │
│      slot.frame_ready.notify_one()                              │
│    }                                                             │
│    sleep(100us)                                                 │
│  }                                                               │
└─────────────────────────────────────────────────────────────────┘

Data Structures

DecodeSlot Structure (Simplified)

struct DecodeSlot {
    // Slot state
    std::atomic<bool> in_use{false};      // Is this NVDEC slot currently decoding?

    // Submitted information (set by DecodeToSurface)
    void* target_surface;                 // Destination D3D12 resource
    VavCoreSurfaceType surface_type;      // Surface type
    uint64_t submission_id;               // For FIFO ordering (monotonic counter)

    // NVDEC information (set by HandlePictureDecode callback)
    int picture_index;                    // CurrPicIdx from NVDEC (same as slot index)

    // Synchronization primitives
    std::condition_variable frame_ready;  // Signaled when decode complete
    std::mutex slot_mutex;                // Protects this slot's state
    std::atomic<bool> is_ready{false};    // Decode completed flag
};

Key Simplifications:

• ✅ No std::vector<int> picture_indices - single picture per slot
• ✅ picture_index == slot_index (CurrPicIdx is the slot index)
• ✅ No mapping tables needed

RingBuffer Members (Simplified)

class NVDECAV1Decoder {
private:
    static constexpr size_t RING_BUFFER_SIZE = 8;  // Match ulNumOutputSurfaces

    DecodeSlot m_ringBuffer[RING_BUFFER_SIZE];

    // 🎯 Simplified: Only submission ID for FIFO ordering
    std::atomic<uint64_t> m_submissionCounter{0};   // Monotonic submission ID
    std::atomic<uint64_t> m_returnCounter{0};       // Return order enforcement (FIFO)

    // ⚠️ CRITICAL FIX: Ring buffer for pending submissions (multi-thread safe)
    struct PendingSubmission {
        void* target_surface;
        VavCoreSurfaceType surface_type;
        uint64_t submission_id;
        std::atomic<bool> in_use{false};
    };
    PendingSubmission m_pendingSubmissions[RING_BUFFER_SIZE];  // Ring buffer for contexts
    std::mutex m_submissionMutex;  // Protects pending submission allocation

    // Polling thread
    std::thread m_pollingThread;
    std::atomic<bool> m_pollingRunning{false};
};

Key Fix:

• ✅ m_pendingSubmissions[8] ring buffer (not single struct!)
• ✅ Each slot has its own pending context
• ✅ submission_id % 8 determines which pending slot to use
• ✅ Thread-safe: Different threads use different pending slots

Eliminated Variables:

• ❌ m_slotIdCounter (replaced with m_submissionCounter)
• ❌ m_pictureIndexToSlotId mapping (not needed!)
• ❌ m_currentSubmittingSlotId atomic (use pending submission ring buffer)

---

🔧 Detailed Design

Component 1: Submission Preparation (Producer)

Purpose: Prepare submission context before calling cuvidParseVideoData

// In DecodeToSurface()

// 1. Allocate submission ID for FIFO ordering
uint64_t my_submission_id = m_submissionCounter.fetch_add(1);
size_t pending_idx = my_submission_id % RING_BUFFER_SIZE;

// 2. Wait if pending slot is still in use (overflow protection)
while (m_pendingSubmissions[pending_idx].in_use.load()) {
    std::this_thread::sleep_for(std::chrono::milliseconds(1));
}

// 3. Store submission context in ring buffer slot
{
    std::lock_guard<std::mutex> lock(m_submissionMutex);
    auto& pending = m_pendingSubmissions[pending_idx];

    pending.target_surface = target_surface;
    pending.surface_type = target_type;
    pending.submission_id = my_submission_id;
    pending.in_use.store(true);
}

LOGF_DEBUG("[DecodeToSurface] Prepared submission_id=%llu, pending_idx=%zu",
           my_submission_id, pending_idx);

Key Design Points:

• ✅ Ring buffer for pending contexts - Multi-thread safe, no overwrite
• ✅ pending_idx = submission_id % 8 - Deterministic slot allocation
• ✅ Overflow protection - Wait if pending slot still in use
• ✅ No slot allocation yet - NVDEC will provide CurrPicIdx in callback
• ✅ Thread-safe - Each thread uses different pending slot

---

Component 2: Packet Submission

Purpose: Submit packet to NVDEC parser (cuvidParseVideoData is synchronous)

// 3. Submit packet to NVDEC parser
CUVIDSOURCEDATAPACKET packet = {};
packet.payload = packet_data;
packet.payload_size = packet_size;
packet.flags = CUVID_PKT_ENDOFPICTURE;
packet.timestamp = 0;  // Not used - we use m_pendingSubmission instead

CUresult result = cuvidParseVideoData(m_parser, &packet);
// cuvidParseVideoData is SYNCHRONOUS - HandlePictureDecode called before return

if (result != CUDA_SUCCESS) {
    LOGF_ERROR("[DecodeToSurface] cuvidParseVideoData failed");
    return false;
}

LOGF_DEBUG("[DecodeToSurface] Packet submitted, callback completed");

Simplified Flow:

cuvidParseVideoData(packet)
    ↓ (synchronous callback)
HandlePictureDecode(pic_params)
    ↓
CurrPicIdx = pic_params->CurrPicIdx  // NVDEC provides slot index (0-7)
    ↓
pending_idx = submission_id % 8
    ↓
Copy m_pendingSubmissions[pending_idx] → m_ringBuffer[CurrPicIdx]
    ↓
Release m_pendingSubmissions[pending_idx].in_use = false
    ↓
Return from HandlePictureDecode
    ↓
Return from cuvidParseVideoData

Key Points:

• ✅ cuvidParseVideoData is synchronous - callbacks complete before return
• ✅ CurrPicIdx is the slot index - no calculation needed
• ✅ pending_idx = submission_id % 8 - find correct pending context
• ✅ Ring buffer prevents overwrites - multi-thread safe
• ✅ Release pending slot after copy - allow reuse for next submission

---

Component 3: Polling Thread (Background Status Checker)

Purpose: Continuously poll pending slots for decode completion

void NVDECAV1Decoder::PollingThreadFunc() {
    while (m_pollingRunning) {
        // 1. Check all slots for pending decodes
        for (int slot_idx = 0; slot_idx < RING_BUFFER_SIZE; ++slot_idx) {
            DecodeSlot& slot = m_ringBuffer[slot_idx];

            // 2. Skip slots not in use or already ready
            if (!slot.in_use.load() || slot.is_ready.load()) {
                continue;
            }

            // 3. Query NVDEC decode status for this slot's picture
            CUVIDGETDECODESTATUS decodeStatus = {};
            CUresult result = cuvidGetDecodeStatus(m_decoder, slot.picture_index, &decodeStatus);

            // 4. If decode complete, mark slot ready
            if (result == CUDA_SUCCESS &&
                decodeStatus.decodeStatus == cuvidDecodeStatus_Success) {

                {
                    std::lock_guard<std::mutex> lock(slot.slot_mutex);
                    slot.is_ready.store(true);
                }
                slot.frame_ready.notify_one();

                LOGF_DEBUG("[PollingThread] Slot %d ready (submission_id=%llu)",
                           slot_idx, slot.submission_id);
            }
        }

        // 5. Sleep to avoid busy-wait
        std::this_thread::sleep_for(std::chrono::microseconds(100));
    }
}

Key Points:

• ✅ Simple slot iteration - check all 8 slots (minimal overhead)
• ✅ Single picture per slot - no vector iteration needed
• ✅ CurrPicIdx == slot_idx - direct correspondence
• ✅ Uses cuvidGetDecodeStatus() non-blocking query
• ✅ 100us sleep → ~10,000 checks/second (low CPU usage)

---

Component 4: Wait for Decode and Retrieve Slot

Purpose: Wait for NVDEC to complete decoding and find which slot was used

// In DecodeToSurface() - After cuvidParseVideoData returns

// 4. Find which slot NVDEC used (check all slots for our submission_id)
int my_slot_idx = -1;
for (int i = 0; i < RING_BUFFER_SIZE; ++i) {
    if (m_ringBuffer[i].submission_id == my_submission_id) {
        my_slot_idx = i;
        break;
    }
}

if (my_slot_idx == -1) {
    LOGF_ERROR("[DecodeToSurface] Failed to find slot for submission_id=%llu", my_submission_id);
    return false;
}

DecodeSlot& my_slot = m_ringBuffer[my_slot_idx];
LOGF_DEBUG("[DecodeToSurface] Found slot_idx=%d for submission_id=%llu", my_slot_idx, my_submission_id);

// 5. Wait for my turn in FIFO order
while (m_returnCounter.load() != my_submission_id) {
    std::this_thread::sleep_for(std::chrono::milliseconds(1));
}

LOGF_DEBUG("[DecodeToSurface] My turn! submission_id=%llu", my_submission_id);

// 6. Wait for decode to complete
{
    std::unique_lock<std::mutex> lock(my_slot.slot_mutex);

    if (!my_slot.frame_ready.wait_for(lock, std::chrono::milliseconds(500),
        [&my_slot]() { return my_slot.is_ready.load(); })) {
        // Timeout - decode took too long
        LOGF_ERROR("[DecodeToSurface] Decode timeout for slot %d", my_slot_idx);
        my_slot.in_use.store(false);
        m_returnCounter.fetch_add(1);  // Skip to avoid deadlock
        return false;
    }
}

LOGF_DEBUG("[DecodeToSurface] Decode complete for slot %d", my_slot_idx);

Simplified Timeline Example:

Thread 1 (submission_id=0, CurrPicIdx=3): Wait for returnCounter==0 ✅
                                          Wait for slot[3].is_ready...

Thread 2 (submission_id=1, CurrPicIdx=5): Wait for returnCounter==1 ⏸️ (blocked)

GPU: slot[5] completes first @ t=3ms
     → slot[5].is_ready = true
     → Thread 2 still blocked (returnCounter=0)

GPU: slot[3] completes @ t=15ms
     → slot[3].is_ready = true
     → Thread 1 wakes up ✅
     → Thread 1 processes → returnCounter = 1
     → Thread 2 now unblocked ✅

Key Points:

• ✅ Find slot by submission_id - simple linear search
• ✅ FIFO using submission_id - not slot index
• ✅ CurrPicIdx can be any value - NVDEC chooses which slot to use

---

Component 5: Frame Retrieval & Cleanup

Purpose: Map decoded frame, copy to surface, release slot

// In DecodeToSurface() - After decode complete

// 7. Map decoded frame from NVDEC using the slot's picture_index
CUVIDPROCPARAMS procParams = {};
procParams.progressive_frame = 1;

CUdeviceptr srcDevicePtr = 0;
unsigned int srcPitch = 0;

int pic_idx = my_slot.picture_index;  // CurrPicIdx from NVDEC
CUresult result = cuvidMapVideoFrame(m_decoder, pic_idx, &srcDevicePtr, &srcPitch, &procParams);
if (result != CUDA_SUCCESS) {
    LOGF_ERROR("[DecodeToSurface] cuvidMapVideoFrame failed for pic_idx=%d", pic_idx);
    my_slot.in_use.store(false);
    m_returnCounter.fetch_add(1);
    return false;
}

// 8. Copy to D3D12 surface (use target_surface from slot)
ID3D12Resource* d3d12Resource = static_cast<ID3D12Resource*>(my_slot.target_surface);
bool copySuccess = m_d3d12Handler->CopyNV12Frame(
    srcDevicePtr, srcPitch, d3d12Resource, m_width, m_height
);

// 9. Unmap frame
cuvidUnmapVideoFrame(m_decoder, srcDevicePtr);

// 10. Release slot
{
    std::lock_guard<std::mutex> lock(my_slot.slot_mutex);
    my_slot.in_use.store(false);
}

LOGF_DEBUG("[DecodeToSurface] Released slot %d", my_slot_idx);

// 11. Advance return counter (FIFO order)
m_returnCounter.fetch_add(1);

return copySuccess;

Key Points:

• ✅ Single picture per slot - no multi-frame complexity
• ✅ picture_index == CurrPicIdx - direct NVDEC slot index
• ✅ target_surface from slot - stored during HandlePictureDecode

---

Component 6: NVDEC Callback Integration (Simplified)

Purpose: Use NVDEC's CurrPicIdx directly as ring buffer slot index

int CUDAAPI NVDECAV1Decoder::HandlePictureDecode(void* user_data, CUVIDPICPARAMS* pic_params) {
    auto* decoder = static_cast<NVDECAV1Decoder*>(user_data);

    // 🎯 Use NVDEC's CurrPicIdx directly as slot index
    int slot_idx = pic_params->CurrPicIdx;  // 0-7 (NVDEC's ring buffer index)

    LOGF_DEBUG("[HandlePictureDecode] CurrPicIdx=%d, IntraPicFlag=%d",
               slot_idx, pic_params->intra_pic_flag);

    // Validate slot index (should always be 0-7)
    if (slot_idx < 0 || slot_idx >= RING_BUFFER_SIZE) {
        LOGF_ERROR("[HandlePictureDecode] Invalid CurrPicIdx=%d", slot_idx);
        return 0;
    }

    DecodeSlot& slot = decoder->m_ringBuffer[slot_idx];

    // Find pending submission context using submission_id
    uint64_t submission_id;
    size_t pending_idx;
    {
        std::lock_guard<std::mutex> lock(decoder->m_submissionMutex);

        // Find the most recent pending submission
        // (In practice, we use the last allocated submission_id)
        submission_id = decoder->m_submissionCounter.load() - 1;
        pending_idx = submission_id % RING_BUFFER_SIZE;

        auto& pending = decoder->m_pendingSubmissions[pending_idx];

        // Copy pending submission context to decode slot
        slot.target_surface = pending.target_surface;
        slot.surface_type = pending.surface_type;
        slot.submission_id = pending.submission_id;

        // Release pending slot for reuse
        pending.in_use.store(false);
    }

    slot.picture_index = slot_idx;  // Store CurrPicIdx (same as slot_idx)
    slot.in_use.store(true);
    slot.is_ready.store(false);

    LOGF_INFO("[HandlePictureDecode] Calling cuvidDecodePicture (slot=%d, submission_id=%llu, pending_idx=%zu)",
              slot_idx, slot.submission_id, pending_idx);

    // Submit frame to NVDEC decoder
    CUresult result = cuvidDecodePicture(decoder->m_decoder, pic_params);
    if (result != CUDA_SUCCESS) {
        LOGF_ERROR("[HandlePictureDecode] cuvidDecodePicture failed: %d", result);
        slot.in_use.store(false);
        return 0;
    }

    // Polling thread will check cuvidGetDecodeStatus() for this picture_index

    return 1;
}

Key Advantages of Simplified Design:

• ✅ Direct CurrPicIdx usage - no calculation, no mapping
• ✅ Ring buffer for pending contexts - multi-thread safe, no overwrites
• ✅ pending_idx = submission_id % 8 - deterministic context lookup
• ✅ Release after copy - pending slots can be reused immediately
• ✅ Single picture per slot - no multi-frame vector complexity
• ✅ Aligned with NVDEC design - use the API as intended

---

🎯 Simplified Design Summary

What Changed from Original Design

Eliminated Complexity:

1. ❌ Custom slot_id allocation system (m_slotIdCounter)
2. ❌ m_pictureIndexToSlotId mapping table
3. ❌ std::vector<int> picture_indices (multi-frame support)
4. ❌ ParseContext struct and user_data manipulation
5. ❌ Timestamp tricks to pass slot_id through callbacks

New Simplified Approach:

1. ✅ Use NVDEC's CurrPicIdx (0-7) directly as ring buffer index
2. ✅ Pass submission context via m_pendingSubmission member variable
3. ✅ Single picture per slot (one packet → one frame)
4. ✅ submission_id only for FIFO ordering, not slot allocation

Data Flow Comparison

Old (Complex):

DecodeToSurface:
  my_id = m_slotIdCounter++
  slot_idx = my_id % 8
  packet.timestamp = my_id

HandlePictureDecode:
  slot_id = pic_params->nTimeStamp
  slot_idx = slot_id % 8
  m_pictureIndexToSlotId[CurrPicIdx] = slot_id
  slot.picture_indices.push_back(CurrPicIdx)

PollingThread:
  Check ALL picture_indices in slot

New (Simplified):

DecodeToSurface:
  submission_id = m_submissionCounter++
  pending_idx = submission_id % 8
  m_pendingSubmissions[pending_idx] = {target_surface, surface_type, submission_id}

HandlePictureDecode:
  slot_idx = pic_params->CurrPicIdx  // 0-7 directly!
  pending_idx = submission_id % 8
  slot = m_ringBuffer[slot_idx]
  slot.copy(m_pendingSubmissions[pending_idx])
  m_pendingSubmissions[pending_idx].in_use = false  // Release for reuse
  slot.picture_index = slot_idx

PollingThread:
  Check slot.picture_index (single value)

Why This is Better

1. Aligned with NVDEC's Design: NVDEC provides CurrPicIdx as the canonical slot index
2. Multi-thread Safe: Ring buffer for pending contexts prevents overwrites
3. Less Code: Fewer data structures, less synchronization overhead
4. No Mapping Tables: Direct indexing, no hash map lookups
5. Simpler Debugging: CurrPicIdx == slot_idx == picture_index
6. Easier to Understand: Follow NVDEC's intended usage pattern
7. Deterministic Context Lookup: pending_idx = submission_id % 8

---

📐 Implementation Plan (Updated for Simplified Design)

Phase 1: Data Structure Setup

Files to Modify:

• NVDECAV1Decoder.h - Add simplified RingBuffer members
• NVDECAV1Decoder.cpp - Initialize RingBuffer in constructor

Tasks:

• Define simplified DecodeSlot structure (no picture_indices vector)
• Add m_ringBuffer[8] array
• Add m_submissionCounter, m_returnCounter atomic counters
• ⚠️ CRITICAL: Add PendingSubmission struct with in_use flag
• ⚠️ CRITICAL: Add m_pendingSubmissions[8] ring buffer array (NOT single struct!)
• Add m_submissionMutex for pending submission allocation
• Add m_pollingThread, m_pollingRunning members
• Remove old variables: m_currentSubmittingSlotId, any mapping tables

Estimated Time: 30 minutes

---

Phase 2: Polling Thread Implementation (Simplified)

Files to Modify:

• NVDECAV1Decoder.cpp - Implement PollingThreadFunc()

Tasks:

• Implement simple polling loop iterating all 8 slots
• Check slot.in_use and !slot.is_ready to skip idle slots
• Use cuvidGetDecodeStatus() for single slot.picture_index
• Add thread start in Initialize()
• Add thread stop in Cleanup()
• Add debug logging for slot readiness

Testing:

• Verify thread starts/stops correctly
• Verify single picture per slot handling
• Verify cuvidGetDecodeStatus() calls work

Estimated Time: 45 minutes

---

Phase 3: DecodeToSurface Refactoring (Simplified Implementation)

Files to Modify:

• NVDECAV1Decoder.cpp - Rewrite DecodeToSurface() with simplified design

Tasks:

• Phase 1: Allocate submission_id from m_submissionCounter
• Phase 2: Calculate pending_idx = submission_id % 8
• Phase 3: Wait if m_pendingSubmissions[pending_idx].in_use (overflow protection)
• Phase 4: Store submission context in m_pendingSubmissions[pending_idx]
• Phase 5: Call cuvidParseVideoData() (synchronous, callback completes)
• Phase 6: Find slot by searching for submission_id in ring buffer
• Phase 7: Wait for FIFO turn using m_returnCounter
• Phase 8: Wait for slot.is_ready condition variable
• Phase 9: Map/copy frame using slot.picture_index
• Phase 10: Release slot and increment m_returnCounter
• Error handling for all failure paths

Testing:

• Single-threaded decode test
• Multi-threaded decode test (2-3 threads)
• ⚠️ Multi-thread race test: Verify no pending context overwrites
• Verify CurrPicIdx is used correctly as slot index
• Verify FIFO ordering with out-of-order completion

Estimated Time: 1.5 hours

---

Phase 4: HandlePictureDecode Update (Simplified)

Files to Modify:

• NVDECAV1Decoder.cpp - Modify HandlePictureDecode() callback

Tasks:

• Direct CurrPicIdx: Use slot_idx = pic_params->CurrPicIdx (0-7)
• Find pending context: Calculate pending_idx = submission_id % 8
• Copy submission context: Copy m_pendingSubmissions[pending_idx] to slot
• Release pending slot: Set m_pendingSubmissions[pending_idx].in_use = false
• Store picture_index: Set slot.picture_index = slot_idx
• Mark slot active: slot.in_use = true, slot.is_ready = false
• Add debug logging for slot assignment and pending release

Testing:

• Verify CurrPicIdx maps correctly to slot index
• ⚠️ Critical: Verify pending_idx calculation is correct
• Verify submission context is copied correctly
• Verify pending slot is released immediately after copy
• Test with both simple and complex videos

Estimated Time: 25 minutes

---

Phase 5: Integration Testing (Simplified Design Validation)

Test Scenarios:

1. Single packet decode - Verify CurrPicIdx direct usage
2. Sequential 3 packets - Verify FIFO order using m_returnCounter
3. Out-of-order completion - Verify submission_id FIFO (I-frame after P-frame)
4. RingBuffer overflow - Verify error handling (9+ concurrent calls)
5. Decode errors - Verify graceful failure and slot release
6. Performance benchmark - Measure latency reduction vs old queue-based approach

Test Files:

• Simple test video (simple_test.webm) - basic validation
• Complex video (test_720p_stripe.webm) - stress testing

Validation Criteria:

• ✅ CurrPicIdx used correctly as slot index (no calculation errors)
• ✅ submission_id correctly tracks FIFO order
• ✅ FIFO order maintained even with out-of-order GPU completion
• ✅ No memory corruption or race conditions
• ✅ No mapping table lookups (simpler code path)

Estimated Time: 1.5 hours

---

Phase 6: Documentation & Cleanup

Tasks:

• Update NVDEC design documentation with simplified CurrPicIdx design
• Add inline code comments explaining CurrPicIdx direct usage
• Remove old queue-based code and any mapping table attempts
• Remove ParseContext struct and related code
• Move design doc to docs/completed/ after successful implementation
• Document NVDEC's ring buffer philosophy for future reference

Estimated Time: 45 minutes

---

Total Estimated Time: ~5 hours (reduced from ~7 hours with previous design)

---

📊 Performance Analysis

Expected Improvements

Scenario 1: Sequential 3-Frame Decode

Current (Sequential):

Frame 1: [Submit 1ms][Wait 10ms][Map 1ms][Copy 2ms][Unmap 1ms] = 15ms
Frame 2: [Submit 1ms][Wait 10ms][Map 1ms][Copy 2ms][Unmap 1ms] = 15ms
Frame 3: [Submit 1ms][Wait 10ms][Map 1ms][Copy 2ms][Unmap 1ms] = 15ms
Total: 45ms

With RingBuffer (Parallel):

Submit all 3:     [S1][S2][S3] = 3ms
GPU decode:       [─── 10ms ───] (parallel)
Sequential return:
  Frame 1: [Wait][Map][Copy][Unmap] = 5ms
  Frame 2: [Map][Copy][Unmap] = 4ms (already decoded)
  Frame 3: [Map][Copy][Unmap] = 4ms (already decoded)
Total: 3ms + 10ms + 13ms = 26ms

Improvement: 45ms → 26ms (42% faster)

---

Scenario 2: Complex I/P Frame Mix

Video: I-frame (15ms), P-frame (3ms), P-frame (3ms)

Current:

I: 15ms
P: 3ms
P: 3ms
Total: 21ms

With RingBuffer:

Submit: 3ms
GPU:    [I:15ms, P:3ms, P:3ms overlap] = 15ms (limited by I-frame)
Return: 9ms (sequential)
Total: 27ms (slower due to overhead)

But if I-frame completes first: 21ms (same)

Note: Benefit depends on GOP structure. Simple videos may see less improvement.

---

CPU & GPU Utilization

Current:

CPU: [Active──────][Idle────────][Active──────][Idle────────]
GPU:        [Decode──────]               [Decode──────]

With RingBuffer:

CPU: [Active][Active][Active][─────Wait─────][Active][Active]
GPU:        [Decode1][Decode2][Decode3]

GPU Utilization: ⬆️ Increased by ~30% CPU Utilization: ➡️ Similar (waiting in different places)

---

🛡️ Risk Assessment

Risk 1: RingBuffer Overflow

Scenario: Application calls DecodeToSurface() 9+ times before first frame completes

Mitigation:

if (my_slot.in_use) {
    LogError("RingBuffer overflow");
    return false;  // Fail fast
}

Alternative: Block until slot available

while (my_slot.in_use) {
    std::this_thread::sleep_for(std::chrono::milliseconds(1));
}

Recommendation: Fail fast + document max concurrent limit (8 frames)

---

Risk 2: Decode Timeout Deadlock

Scenario: GPU hangs, polling thread never sets is_ready

Mitigation:

if (!my_slot.frame_ready.wait_for(lock, std::chrono::milliseconds(500), ...)) {
    // Timeout - skip this slot
    my_slot.in_use = false;
    m_returnIndex.fetch_add(1);  // Advance to prevent deadlock
    return false;
}

Risk: Skipping slot may cause next slot to fail (reference frame missing)

Recommendation: Return error, let application decide (retry/abort)

---

Risk 3: Polling Thread CPU Usage

100us sleep → ~10,000 checks/second

CPU Impact:

Per check: ~1us (cuvidGetDecodeStatus overhead)
Total: 10,000 * 1us = 10ms/sec = 1% CPU

Mitigation: Acceptable overhead for real-time video decoding

Alternative: Adaptive polling (faster when frames pending, slower when idle)

---

Risk 4: Thread Safety - CUDA Context

Issue: cuvidGetDecodeStatus() requires correct CUDA context

Current Protection:

std::lock_guard<std::mutex> contextLock(m_cudaContextMutex);
cuCtxSetCurrent(m_cuContext);

In Polling Thread:

void PollingThreadFunc() {
    // Set CUDA context once at thread start
    cuCtxSetCurrent(m_cuContext);

    while (m_pollingRunning) {
        // cuvidGetDecodeStatus() now safe
        cuvidGetDecodeStatus(...);
    }
}

Recommendation: Set context once per thread (not per call)

---

📚 References

NVIDIA Documentation

1. NVDEC Video Decoder API Programming Guide

   • URL: https://docs.nvidia.com/video-technologies/video-codec-sdk/12.2/nvdec-video-decoder-api-prog-guide/
   • Section: "cuvidGetDecodeStatus" API reference

2. Video Codec SDK 12.2

   • URL: https://docs.nvidia.com/video-technologies/video-codec-sdk/12.2/
   • Section: "NVDECODE API" - asynchronous decoding patterns

3. CUDA Programming Guide

   • URL: https://docs.nvidia.com/cuda/cuda-c-programming-guide/
   • Section: "Multi-threading" - CUDA context management

Previous Design Documents

1. NVDEC Deferred Decoder Recreation Design (Abandoned)

   • Path: docs/completed/windows/nvdec/NVDEC_Deferred_Decoder_Recreation_Design.md
   • Reason for abandonment: Incompatible with NVDEC synchronous callback architecture
   • Lessons learned: NVDEC parser requires immediate decoder availability

2. VavCore Library Design

   • Path: VavCore_Library_Design.md
   • Relevant sections: C API design, cross-platform surface types

Code References

1. Current DecodeToSurface Implementation

   • File: platforms/windows/vavcore/src/Decoder/NVDECAV1Decoder.cpp
   • Lines: 976-1200
   • Current approach: Synchronous wait with condition variable

2. HandlePictureDisplay Callback

   • File: platforms/windows/vavcore/src/Decoder/NVDECAV1Decoder.cpp
   • Lines: 791-813
   • Current approach: Push picture_index to queue, notify condition variable

3. NVDEC Initialization

   • File: platforms/windows/vavcore/src/Decoder/NVDECAV1Decoder.cpp
   • Lines: 600-650
   • Key setting: m_createInfo.ulNumOutputSurfaces = 8

---

🔄 Change Log

Date	Author	Change Description
2025-10-04	Claude	Initial design document created
2025-10-04	Claude	Added RingBuffer architecture details
2025-10-04	Claude	Added polling thread design
2025-10-04	Claude	Added performance analysis
2025-10-05	Claude	MAJOR UPDATE: Simplified design to use NVDEC's CurrPicIdx directly
2025-10-05	Claude	Removed ParseContext approach (failed due to NVDEC parameter copying)
2025-10-05	Claude	Removed custom slot_id allocation and mapping tables
2025-10-05	Claude	Added "NVDEC CurrPicIdx Design Philosophy" section
2025-10-05	Claude	Updated all components to use simplified architecture
2025-10-05	Claude	Reduced implementation time estimate from 7h to 5h
2025-10-05	Claude	CRITICAL FIX: Changed m_pendingSubmission to ring buffer array
2025-10-05	Claude	Added PendingSubmission[8] to prevent multi-thread overwrites
2025-10-05	Claude	Updated all components to use pending_idx = submission_id % 8
2025-10-05	Claude	Added overflow protection and pending slot release logic

---

✅ Approval & Sign-off

Design Review:

• Architecture approved
• Performance estimates validated
• Risk mitigation strategies accepted

Implementation Ready:

• All design questions resolved
• Implementation plan reviewed
• Test plan defined

---

Next Steps: Proceed to Phase 1 - Data Structure Setup