Revision control
++ // Copyright (C) 2026 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only
++
++ #ifndef HWFRAMECONTEXT_P_H
++ #define HWFRAMECONTEXT_P_H
++
++ #include <QtFFmpegMediaPluginImpl/private/qffmpeg_p.h>
++ #include <QtFFmpegMediaPluginImpl/private/qffmpeghwaccel_p.h>
++ #include <QtFFmpegMediaPluginImpl/private/qffmpegvideobuffer_p.h>
++
++ #include <QtMultimedia/qvideoframe.h>
++ #include <QtMultimedia/private/qvideoframe_p.h>
++ #include <QtMultimedia/private/qvideotexturehelper_p.h>
++ #include <QtMultimediaTestLib/private/qvideoframetestutils_p.h>
++
++ #include <QtCore/private/qexpected_p.h>
++ #include <QtCore/qbytearray.h>
++ #include <QtCore/qlist.h>
++ #include <QtCore/qsize.h>
++ #include <QtCore/qstring.h>
++
++ #include <memory>
++
++ extern "C" {
++ #include <libavutil/hwcontext.h>
++ #include <libavutil/pixfmt.h>
++ }
++
++ using namespace QFFmpeg;
++ using namespace Qt::Literals;
++
++ // A hw-frames context plus one hw AVFrame filled with a known per-plane byte pattern, suitable
++ // for exercising a texture converter or QVideoFrame::map() without a real decoder.
++ struct HwFrameContext
++ {
++ HWAccelUPtr hwAccel;
++ AVBufferUPtr framesContext;
++ AVFrameUPtr hwFrame;
++
++ QSize size;
++ QVideoFrameFormat::PixelFormat pixelFormat;
++ QList<QByteArray> planeTexels; // the fill pattern each plane was uniformly populated with
++ };
++
++ // Creates an HwFrameContext for a hw device of type "deviceType", with hw pixel format
++ // "hwFormat" and decoded (sw) pixel format "swFormat". Each entry in "planeTexels" is the byte
++ // pattern one plane is uniformly filled with (e.g. {luma}, {chromaU, chromaV} for NV12).
++ // "configureFramesContext" is invoked on the allocated AVHWFramesContext right before
++ // av_hwframe_ctx_init(), so that callers can set backend-specific fields (e.g. VAAPI surface
++ // attributes).
++ template <typename ConfigureFramesContext>
++ q23::expected<HwFrameContext, QString>
++ createHwFrameContext(AVHWDeviceType deviceType, AVPixelFormat hwFormat, AVPixelFormat swFormat,
++ QSize size, QList<QByteArray> planeTexels,
++ ConfigureFramesContext configureFramesContext)
++ {
++ const QVideoFrameFormat::PixelFormat pixelFormat =
++ QFFmpegVideoBuffer::toQtPixelFormat(swFormat);
++ // QFFmpegVideoBuffer::map() round-trips a hw frame's sw_format through toQtPixelFormat() and
++ // back via convertSWFrame(); a format whose round trip isn't the identity gets silently
++ // sws_scale'd, which would make a pixel-exact comparison against planeTexels meaningless.
++ Q_ASSERT(QFFmpegVideoBuffer::toAVPixelFormat(pixelFormat) == swFormat);
++
++ HWAccelUPtr hwAccel = HWAccel::create(deviceType);
++ if (!hwAccel)
++ return q23::unexpected(u"No usable hw device of the requested type on this system"_s);
++
++ AVBufferUPtr framesContext(av_hwframe_ctx_alloc(hwAccel->hwDeviceContextAsBuffer()));
++ if (!framesContext)
++ return q23::unexpected(u"av_hwframe_ctx_alloc failed"_s);
++
++ auto *ctx = reinterpret_cast<AVHWFramesContext *>(framesContext->data);
++ ctx->format = hwFormat;
++ ctx->sw_format = swFormat;
++ ctx->width = size.width();
++ ctx->height = size.height();
++
++ configureFramesContext(*ctx);
++
++ if (av_hwframe_ctx_init(framesContext.get()) < 0)
++ return q23::unexpected(
++ u"av_hwframe_ctx_init failed (format unsupported by this driver?)"_s);
++
++ AVFrameUPtr swFrame = makeAVFrame();
++ swFrame->format = swFormat;
++ swFrame->width = size.width();
++ swFrame->height = size.height();
++ if (av_frame_get_buffer(swFrame.get(), 32) < 0)
++ return q23::unexpected(u"av_frame_get_buffer failed"_s);
++
++ const auto *desc = QVideoTextureHelper::textureDescription(pixelFormat);
++ Q_ASSERT(desc->nplanes == planeTexels.size());
++ for (int plane = 0; plane < desc->nplanes; ++plane) {
++ const int width = desc->widthForPlane(size.width(), plane);
++ const int height = desc->heightForPlane(size.height(), plane);
++ QtMultimediaTest::fillPlaneRows(swFrame->data[plane], swFrame->linesize[plane], width,
++ height, planeTexels[plane]);
++ }
++
++ AVFrameUPtr hwFrame = makeAVFrame();
++ if (av_hwframe_get_buffer(framesContext.get(), hwFrame.get(), 0) < 0)
++ return q23::unexpected(u"av_hwframe_get_buffer failed"_s);
++
++ if (av_hwframe_transfer_data(hwFrame.get(), swFrame.get(), 0) < 0)
++ return q23::unexpected(u"av_hwframe_transfer_data failed"_s);
++
++ return HwFrameContext{ std::move(hwAccel), std::move(framesContext), std::move(hwFrame), size,
++ pixelFormat, std::move(planeTexels) };
++ }
++
++ // Convenience wrapper for a two-plane 4:2:0 8-bit format (NV12): a full-size luma plane and a
++ // half-size interleaved-chroma plane.
++ template <typename ConfigureFramesContext>
++ q23::expected<HwFrameContext, QString>
++ createNv12HwFrameContext(AVHWDeviceType deviceType, AVPixelFormat hwFormat, QSize size,
++ quint8 lumaValue, quint8 chromaUValue, quint8 chromaVValue,
++ ConfigureFramesContext configureFramesContext)
++ {
++ return createHwFrameContext(deviceType, hwFormat, AV_PIX_FMT_NV12, size,
++ { QByteArray(1, char(lumaValue)),
++ QtMultimediaTest::makeBytes({ chromaUValue, chromaVValue }) },
++ configureFramesContext);
++ }
++
++ // Convenience wrapper for a two-plane 4:2:0 10-bit format (P010): each plane's samples are
++ // 16-bit, with the 10-bit value left-shifted into the high bits (FFmpeg's P010 convention).
++ template <typename ConfigureFramesContext>
++ q23::expected<HwFrameContext, QString>
++ createP010HwFrameContext(AVHWDeviceType deviceType, AVPixelFormat hwFormat, QSize size,
++ quint16 lumaValue, quint16 chromaUValue, quint16 chromaVValue,
++ ConfigureFramesContext configureFramesContext)
++ {
++ const auto toBytes = [](quint16 value) {
++ const quint16 shifted = quint16(value << 6);
++ return QByteArray(reinterpret_cast<const char *>(&shifted), sizeof(shifted));
++ };
++ return createHwFrameContext(
++ deviceType, hwFormat, AV_PIX_FMT_P010, size,
++ { toBytes(lumaValue), toBytes(chromaUValue) + toBytes(chromaVValue) },
++ configureFramesContext);
++ }
++
++ // Convenience wrapper for a single-plane packed 8-bit format (BGRA8888).
++ template <typename ConfigureFramesContext>
++ q23::expected<HwFrameContext, QString>
++ createSinglePlaneHwFrameContext(AVHWDeviceType deviceType, AVPixelFormat hwFormat, QSize size,
++ QByteArray texel, ConfigureFramesContext configureFramesContext)
++ {
++ return createHwFrameContext(deviceType, hwFormat, AV_PIX_FMT_BGRA, size, { std::move(texel) },
++ configureFramesContext);
++ }
++
++ // Constructs a QFFmpegVideoBuffer/QVideoFrame around "hwFrame" (as QFFmpeg::VideoRenderer does)
++ // and maps it, verifying every plane's content against "planeTexels" -- exercising exactly the
++ // CPU (QVideoFrame::map()) path, independent of any GPU texture importer. Returns an error
++ // describing the mismatch, if any.
++ inline q23::expected<void, QString> verifyMappedHwFrame(AVFrameUPtr hwFrame,
++ const QList<QByteArray> &planeTexels)
++ {
++ auto buffer = std::make_unique<QFFmpegVideoBuffer>(std::move(hwFrame));
++ const QVideoFrameFormat::PixelFormat pixelFormat = buffer->pixelFormat();
++ QVideoFrameFormat format(buffer->size(), pixelFormat);
++ QVideoFrame frame = QVideoFramePrivate::createFrame(std::move(buffer), format);
++
++ if (!frame.map(QVideoFrame::ReadOnly))
++ return q23::unexpected(u"QVideoFrame::map() failed"_s);
++
++ const auto *desc = QVideoTextureHelper::textureDescription(pixelFormat);
++ if (desc->nplanes != planeTexels.size())
++ return q23::unexpected(u"Unexpected plane count: %1"_s.arg(desc->nplanes));
++
++ for (int plane = 0; plane < desc->nplanes; ++plane) {
++ const int width = desc->widthForPlane(frame.size().width(), plane);
++ const int height = desc->heightForPlane(frame.size().height(), plane);
++ const q23::expected<void, QString> result = QtMultimediaTest::comparePlaneRows(
++ frame.bits(plane), frame.bytesPerLine(plane), width, height, planeTexels[plane]);
++ if (!result)
++ return q23::unexpected(u"plane %1: %2"_s.arg(plane).arg(result.error()));
++ }
++
++ frame.unmap();
++ return {};
++ }
++
++ #endif // HWFRAMECONTEXT_P_H