video_decoder.h

/*
 * Copyright (C) 2026-present ifm electronic, gmbh
 * SPDX-License-Identifier: Apache-2.0
 *
 * ifm3d RTSP video decoder interface.
 *
 * Decoder implementations are compiled directly into the RTSP
 * module. Each implements the abstract VideoDecoder / VideoDecoderFactory C++
 * interfaces below; DecoderManager lists the available implementations and
 * selects one for a given codec. An implementation is free to load its own
 * heavy runtime dependencies lazily (e.g. the ffmpeg decoder resolves
 * libavcodec/libavutil at runtime) and to report, through IsAvailable(),
 * whether it can actually be used on the current system.
 *
 * Thread-safety contract
 * ----------------------
 * All calls (SendPacket, ReceiveFrame, Flush, ...) for a given VideoDecoder
 * instance MUST be made from a single thread at a time. Decoders are not
 * required to be thread-safe across instances.
 *
 * Buffer ownership
 * ----------------
 * - Buffers passed to SendPacket are owned by the caller and are only valid
 *   for the duration of that call; decoders must copy if they retain.
 * - VideoFrame plane pointers returned by ReceiveFrame are owned by the
 *   decoder and remain valid until the next call to ReceiveFrame, Flush, or
 *   the decoder's destruction.
 */
 
#ifndef IFM3D_RTSP_VIDEO_DECODER_H
#define IFM3D_RTSP_VIDEO_DECODER_H
 
#include <cstdint>
#include <memory>
#include <string>
 
namespace ifm3d::rtsp
{
  enum VideoCodec
  {
    VIDEO_CODEC_H264 = 1
  };
 
  enum VideoFormat
  {
    VIDEO_FORMAT_YUV420P = 1
  };
 
  struct VideoFrame
  {
    std::uint8_t* planes[4]{};
    int linesize[4]{};
    int width{0};
    int height{0};
    int format{0};        /* VideoFormat value, e.g. VIDEO_FORMAT_YUV420P */
    std::uint64_t pts{0}; /* echoed from the SendPacket call that built this
                             frame -- see the frame identity contract above */
  };
 
  class VideoDecoder
  {
  public:
    virtual ~VideoDecoder() = default;
 
    virtual int SendPacket(const std::uint8_t* data,
                           int size,
                           std::uint64_t pts) = 0;
 
    virtual int ReceiveFrame(VideoFrame& out) = 0;
 
    virtual int
    Flush()
    {
      return 0;
    }
 
    [[nodiscard]] virtual std::string
    LastError() const
    {
      return {};
    }
 
  protected:
    VideoDecoder() = default;
    VideoDecoder(const VideoDecoder&) = default;
    VideoDecoder& operator=(const VideoDecoder&) = default;
    VideoDecoder(VideoDecoder&&) = default;
    VideoDecoder& operator=(VideoDecoder&&) = default;
  };
 
  class VideoDecoderFactory
  {
  public:
    virtual ~VideoDecoderFactory() = default;
 
    [[nodiscard]] virtual std::string Name() const = 0;
 
    [[nodiscard]] virtual bool IsAvailable() const = 0;
 
    [[nodiscard]] virtual bool SupportsCodec(VideoCodec codec) const = 0;
 
    virtual std::unique_ptr<VideoDecoder> CreateDecoder(VideoCodec codec) = 0;
 
    [[nodiscard]] virtual std::string
    AvailabilityError() const
    {
      return {};
    }
 
  protected:
    VideoDecoderFactory() = default;
    VideoDecoderFactory(const VideoDecoderFactory&) = default;
    VideoDecoderFactory& operator=(const VideoDecoderFactory&) = default;
    VideoDecoderFactory(VideoDecoderFactory&&) = default;
    VideoDecoderFactory& operator=(VideoDecoderFactory&&) = default;
  };
 
} // namespace ifm3d::rtsp
 
#endif /* IFM3D_RTSP_VIDEO_DECODER_H */