{"record":{"id":"61c6424d937d7851","repo":"stride3d/stride","slug":"failed-to-get-hw-surface-format","errorCode":null,"errorMessage":"Failed to get HW surface format.","messagePattern":"Failed to get HW surface format\\.","errorType":"exception","errorClass":"ApplicationException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Video/FFmpeg/FFmpegCodec.Direct3D11.cs","lineNumber":52,"sourceCode":"                Logger.Info($\"FFmpegCodec: D3D11VA hwaccel unavailable (err={hwRet:X8}), using software decode\");\n                return;\n            }\n\n            IsHardwareAccelerated = true;\n            pHWDeviceContext = pHWDeviceContextLocal;\n            pCodecContext->hw_device_ctx = ffmpeg.av_buffer_ref(pHWDeviceContext);\n\n            getFormat = (context, formats) =>\n            {\n                AVPixelFormat* pixelFormat;\n\n                for (pixelFormat = formats; *pixelFormat != AVPixelFormat.AV_PIX_FMT_NONE; pixelFormat++)\n                {\n                    if (*pixelFormat == HardwarePixelFormat)\n                        return *pixelFormat;\n                }\n\n                throw new ApplicationException(\"Failed to get HW surface format.\");\n            };\n            pCodecContext->get_format = getFormat;\n            Logger.Info(\"FFmpegCodec: D3D11VA hwaccel enabled\");\n        }\n\n        // After avcodec_flush_buffers, FFmpeg resets get_format to its default — restoring our\n        // callback is required for HW decode to keep picking AV_PIX_FMT_D3D11 (native crash otherwise).\n        partial void RestoreGetFormatAfterFlush()\n        {\n            if (getFormat != null)\n                pAVCodecContext->get_format = getFormat;\n        }\n\n        partial void DisposeHardwareAcceleration()\n        {\n            var pHWDeviceContextLocal = pHWDeviceContext;\n            ffmpeg.av_buffer_unref(&pHWDeviceContextLocal);\n        }","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Video/FFmpeg/FFmpegCodec.Direct3D11.cs#L34-L70","documentation":"Thrown by the get_format callback installed in FFmpegCodec.SetupHardwareAcceleration (D3D11VA path) when none of the pixel formats FFmpeg offers matches the expected HardwarePixelFormat. It means the hardware-accelerated decoder cannot negotiate a D3D11 surface format compatible with what this backend requires.","triggerScenarios":"Decoding a codec/pixel-format combination (e.g. 10-bit HEVC, unusual YUV layouts) whose AVPixelFormat list does not include the backend's HardwarePixelFormat, or the D3D11VA hwaccel reports formats the code does not recognize.","commonSituations":"Playing 10-bit/4:2:2 or HDR content on a GPU/driver combination whose D3D11VA exposes only formats the backend didn't anticipate; older GPU lacking support for the codec's hw surface format; driver updates changing the offered format list.","solutions":["Re-encode or transcode the media to a widely supported format (8-bit 4:2:0 H.264/HEVC)","Disable hardware acceleration so decoding falls back to software","Update GPU drivers / FFmpeg build that supports the codec's hw surface formats","Extend the get_format callback to accept an alternative AVPixelFormat and map it"],"exampleFix":"// before\nif (*pixelFormat == HardwarePixelFormat)\n    return *pixelFormat;\nthrow new ApplicationException(\"Failed to get HW surface format.\");\n// after\nif (*pixelFormat == HardwarePixelFormat)\n    return *pixelFormat;\nLogger.Warning(\"HW surface format mismatch, falling back to software decode\");\nreturn formats[0]; // or AV_PIX_FMT_NONE to let FFmpeg fall back","handlingStrategy":"fallback","validationCode":"// Nothing the caller can probe cheaply; prefer an allowlist of known-decodable formats.\nvar codec = probe.VideoCodec; // e.g. h264, hevc\nvar pixFmt = probe.PixelFormat; // e.g. yuv420p\nbool hwSafe = codec is \"h264\" or \"hevc\" && pixFmt == \"yuv420p\";","typeGuard":null,"tryCatchPattern":"try\n{\n    codecWithHardwareAcceleration = new FFmpegCodec(codecpar); // D3D11VA path\n}\ncatch (ApplicationException ex) when (ex.Message == \"Failed to get HW surface format.\")\n{\n    Logger.Warning(\"D3D11VA format negotiation failed; retrying with software decode\");\n    codec = new FFmpegCodec(codecpar, useHardwareAcceleration: false);\n}","preventionTips":["Restrict hardware-accelerated playback to 8-bit 4:2:0 H.264/HEVC content","Keep GPU drivers and the FFmpeg build current","Provide a software-decode fallback path and test it on target hardware","Log the offered AVPixelFormat list in get_format to diagnose format mismatches"],"tags":["video","ffmpeg","d3d11","hardware-acceleration","pixel-format"],"backgroundTag":"unsupported-operation","analyzedSha":"96fad776d210c221682aac1ccdf4c79dc046fc38","analyzedAt":"2026-09-14T02:59:31.279Z","contentChangedAt":"2026-09-14T02:59:31.279Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}