RecordFormat.h

/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#pragma once
 
#include <map>
#include <memory>
#include <string>
#include <vector>
 
#include <vrs/Record.h>
#include <vrs/VrsExport.h>
 
namespace vrs {
 
using std::map;
using std::pair;
using std::string;
using std::unique_ptr;
using std::vector;
 
enum class ContentType : uint8_t {
  CUSTOM = 0, 
  EMPTY, 
  DATA_LAYOUT, 
  IMAGE, 
  AUDIO, 
  COUNT 
};
 
VRS_API string toString(ContentType contentType);
 
enum class ImageFormat : uint8_t {
  UNDEFINED = 0, 
  RAW, 
  JPG, 
  PNG, 
  VIDEO, 
  JXL, 
  CUSTOM_CODEC, 
  COUNT 
};
 
VRS_API string toString(ImageFormat imageFormat);
 
enum class PixelFormat : uint8_t {
  UNDEFINED = 0, 
 
  GREY8 = 1, 
  BGR8, 
  DEPTH32F, 
  RGB8, 
  YUV_I420_SPLIT, 
  YUV_I420_PLANAR = YUV_I420_SPLIT, 
  RGBA8, 
  RGB10, 
  RGB12, 
  GREY10, 
  GREY12, 
  GREY16, 
  RGB32F, 
  SCALAR64F, 
  YUY2, 
  RGB_IR_RAW_4X4, 
  RGBA32F, 
  BAYER8_RGGB, 
  RAW10, 
  RAW10_BAYER_RGGB, 
  RAW10_BAYER_BGGR, 
  YUV_420_NV21, 
  YUV_420_NV12, 
  GREY10PACKED, 
  BAYER8_BGGR, 
  BAYER10_GBRG, 
  BAYER8_GBRG, 
 
  COUNT, 
};
 
VRS_API string toString(PixelFormat pixelFormat);
 
enum class AudioFormat : uint8_t {
  UNDEFINED = 0, 
  PCM = 1, 
  OPUS = 2, 
  COUNT 
};
 
VRS_API string toString(AudioFormat audioFormat);
 
enum class AudioSampleFormat : uint8_t {
  UNDEFINED = 0, 
  S8, 
  U8, 
  A_LAW, 
  MU_LAW, 
  S16_LE, 
  U16_LE, 
  S16_BE, 
  U16_BE, 
  S24_LE, 
  U24_LE, 
  S24_BE, 
  U24_BE, 
  S32_LE, 
  U32_LE, 
  S32_BE, 
  U32_BE, 
  F32_LE, 
  F32_BE, 
  F64_LE, 
  F64_BE, 
  COUNT 
};
 
VRS_API string toString(AudioSampleFormat audioSampleFormat);
 
class ContentParser; // to workaround not being able to forward declare istringstream.
class RecordFormat;
 
class VRS_API ImageContentBlockSpec {
 public:
  static constexpr uint8_t kQualityUndefined = 255;
  static constexpr double kInvalidTimestamp = -1E-308; // arbitrary unrealistic value
 
  ImageContentBlockSpec() = default;
 
  ImageContentBlockSpec(const ImageContentBlockSpec&) = default;
  ImageContentBlockSpec(ImageContentBlockSpec&&) noexcept = default;
  ImageContentBlockSpec(
      ImageContentBlockSpec imageSpec,
      double keyFrameTimestamp,
      uint32_t keyFrameIndex);
 
  ImageContentBlockSpec(
      ImageFormat imageFormat,
      PixelFormat pixelFormat,
      uint32_t width = 0,
      uint32_t height = 0,
      uint32_t stride = 0,
      uint32_t stride2 = 0,
      string codecName = {},
      uint8_t codecQuality = kQualityUndefined,
      double keyFrameTimestamp = kInvalidTimestamp,
      uint32_t keyFrameIndex = 0);
 
  /* implicit */ ImageContentBlockSpec(
      ImageFormat imageFormat,
      uint32_t width = 0,
      uint32_t height = 0);
 
  ImageContentBlockSpec(
      PixelFormat pixelFormat,
      uint32_t width,
      uint32_t height,
      uint32_t stride = 0, 
      uint32_t stride2 = 0 
  );
 
  ImageContentBlockSpec(
      ImageFormat imageFormat,
      string codecName,
      uint8_t codecQuality = kQualityUndefined,
      PixelFormat pixelFormat = PixelFormat::UNDEFINED,
      uint32_t width = 0,
      uint32_t height = 0,
      uint32_t stride = 0,
      uint32_t stride2 = 0);
 
  ImageContentBlockSpec(
      string codecName,
      uint8_t codecQuality,
      PixelFormat pixelFormat,
      uint32_t width,
      uint32_t height,
      uint32_t stride = 0,
      uint32_t stride2 = 0);
 
  explicit ImageContentBlockSpec(const string& formatStr);
 
  ~ImageContentBlockSpec() = default;
 
  void init(
      PixelFormat pixelFormat,
      uint32_t width = 0,
      uint32_t height = 0,
      uint32_t stride = 0,
      uint32_t stride2 = 0,
      string codecName = {},
      uint8_t codecQuality = kQualityUndefined,
      double keyFrameTimestamp = kInvalidTimestamp,
      uint32_t keyFrameIndex = 0);
 
  void set(ContentParser& parser);
  void clear();
 
  ImageContentBlockSpec core() const;
 
  string asString() const;
 
  size_t getBlockSize() const;
 
  size_t getRawImageSize() const;
 
  ImageContentBlockSpec& operator=(const ImageContentBlockSpec&) = default;
  ImageContentBlockSpec& operator=(ImageContentBlockSpec&&) noexcept = default;
 
  bool operator==(const ImageContentBlockSpec& rhs) const;
  bool operator!=(const ImageContentBlockSpec& rhs) const;
 
  ImageFormat getImageFormat() const {
    return imageFormat_;
  }
 
  string getImageFormatAsString() const;
 
  PixelFormat getPixelFormat() const {
    return pixelFormat_;
  }
  string getPixelFormatAsString() const;
  uint32_t getWidth() const {
    return width_;
  }
  uint32_t getHeight() const {
    return height_;
  }
  uint32_t getStride() const;
  uint32_t getRawStride() const {
    return stride_;
  }
  uint32_t getRawStride2() const {
    return stride2_;
  }
  uint32_t getDefaultStride() const;
  uint32_t getDefaultStride2() const;
 
  uint32_t getPlaneCount() const {
    return getPlaneCount(pixelFormat_);
  }
 
  uint32_t getPlaneStride(uint32_t planeIndex) const;
 
  uint32_t getPlaneHeight(uint32_t planeIndex) const;
 
  uint8_t getChannelCountPerPixel() const {
    return getChannelCountPerPixel(pixelFormat_);
  }
  size_t getBytesPerPixel() const {
    return getBytesPerPixel(pixelFormat_);
  }
 
  const string& getCodecName() const {
    return codecName_;
  }
  uint8_t getCodecQuality() const {
    return isQualityValid(codecQuality_) ? codecQuality_ : kQualityUndefined;
  }
 
  inline static bool isQualityValid(uint8_t quality) {
    return quality <= 100;
  }
 
  double getKeyFrameTimestamp() const {
    return keyFrameTimestamp_;
  }
  uint32_t getKeyFrameIndex() const {
    return keyFrameIndex_;
  }
 
  static uint8_t getChannelCountPerPixel(PixelFormat pixel);
  static size_t getBytesPerPixel(PixelFormat pixel);
 
  static string getPixelFormatAsString(PixelFormat pixelFormat) {
    return toString(pixelFormat);
  }
 
  static uint32_t getPlaneCount(PixelFormat pixelFormat);
 
  bool sanityCheckStrides() const;
 
 private:
  ImageFormat imageFormat_{ImageFormat::UNDEFINED};
  PixelFormat pixelFormat_{PixelFormat::UNDEFINED};
  uint32_t width_{0};
  uint32_t height_{0};
  uint32_t stride_{0}; // Stride (bytes between lines) for the first pixel plane
  uint32_t stride2_{0}; // Stride for the other planes (same for all)
  // for ImageFormat::VIDEO
  string codecName_;
  double keyFrameTimestamp_{kInvalidTimestamp};
  uint32_t keyFrameIndex_{0};
  uint8_t codecQuality_{kQualityUndefined};
};
 
class VRS_API AudioContentBlockSpec {
 public:
  AudioContentBlockSpec() = default;
  AudioContentBlockSpec(const AudioContentBlockSpec&) = default;
  AudioContentBlockSpec(AudioContentBlockSpec&&) noexcept = default;
  explicit AudioContentBlockSpec(AudioFormat audioFormat, uint8_t channelCount = 0);
  AudioContentBlockSpec(
      AudioFormat audioFormat,
      AudioSampleFormat sampleFormat,
      uint8_t channelCount = 0,
      uint8_t sampleFrameStride = 0,
      uint32_t sampleFrameRate = 0,
      uint32_t sampleFrameCount = 0,
      uint8_t stereoPairCount = 0);
  ~AudioContentBlockSpec() = default;
 
  explicit AudioContentBlockSpec(const string& formatStr);
 
  void set(ContentParser& parser);
  void clear();
 
  AudioContentBlockSpec& operator=(const AudioContentBlockSpec&) = default;
  AudioContentBlockSpec& operator=(AudioContentBlockSpec&&) noexcept = default;
 
  bool operator==(const AudioContentBlockSpec& rhs) const;
  bool operator!=(const AudioContentBlockSpec& rhs) const {
    return !operator==(rhs);
  }
  string asString() const;
 
  size_t getBlockSize() const;
 
  size_t getPcmBlockSize() const;
 
  bool isCompatibleWith(const AudioContentBlockSpec& rhs) const;
  AudioFormat getAudioFormat() const {
    return audioFormat_;
  }
  AudioSampleFormat getSampleFormat() const {
    return sampleFormat_;
  }
  string getSampleFormatAsString() const;
  bool isLittleEndian() const {
    return isLittleEndian(sampleFormat_);
  }
  bool isIEEEFloat() const {
    return isIEEEFloat(sampleFormat_);
  }
  uint8_t getBitsPerSample() const {
    return getBitsPerSample(sampleFormat_);
  }
  uint8_t getBytesPerSample() const {
    return (getBitsPerSample(sampleFormat_) + 7) / 8; // round up
  }
  uint8_t getSampleFrameStride() const;
  uint8_t getChannelCount() const {
    return channelCount_;
  }
  uint32_t getSampleRate() const {
    return sampleFrameRate_;
  }
  uint32_t getSampleCount() const {
    return sampleFrameCount_;
  }
  void setSampleCount(uint32_t sampleCount) {
    sampleFrameCount_ = sampleCount;
  }
 
  uint8_t getStereoPairCount() const {
    return stereoPairCount_;
  }
 
  bool isSampleBlockFormatDefined() const;
 
  static bool isLittleEndian(AudioSampleFormat sampleFormat);
  static bool isIEEEFloat(AudioSampleFormat sampleFormat);
  static uint8_t getBitsPerSample(AudioSampleFormat sampleFormat);
  static uint8_t getBytesPerSample(AudioSampleFormat sampleFormat);
  static string getSampleFormatAsString(AudioSampleFormat sampleFormat) {
    return toString(sampleFormat);
  }
 
 private:
  AudioFormat audioFormat_{};
  AudioSampleFormat sampleFormat_{};
  uint8_t sampleFrameStride_{};
  uint8_t channelCount_{};
  uint32_t sampleFrameRate_{};
  uint32_t sampleFrameCount_{};
  uint8_t stereoPairCount_{};
};
 
class VRS_API ContentBlock {
 public:
  static const size_t kSizeUnknown;
 
  /* implicit */ ContentBlock(ContentType type = ContentType::EMPTY, size_t size = kSizeUnknown);
 
  explicit ContentBlock(const string& formatStr);
 
  /* implicit */ ContentBlock(ImageFormat imageFormat, uint32_t width = 0, uint32_t height = 0);
 
  ContentBlock(
      std::string codecName,
      uint8_t codecQuality,
      PixelFormat pixelFormat = PixelFormat::UNDEFINED,
      uint32_t width = 0,
      uint32_t height = 0,
      uint32_t stride = 0,
      uint32_t stride2 = 0);
 
  ContentBlock(
      PixelFormat pixelFormat,
      uint32_t width,
      uint32_t height,
      uint32_t stride = 0,
      uint32_t stride2 = 0);
 
  /* implicit */ ContentBlock(const ImageContentBlockSpec& imageSpec, size_t size = kSizeUnknown);
  /* implicit */ ContentBlock(
      ImageContentBlockSpec&& imageSpec,
      size_t size = kSizeUnknown) noexcept;
  ContentBlock(
      const ContentBlock& imageContentBlock,
      double keyFrameTimestamp,
      uint32_t keyFrameIndex);
 
  /* implicit */ ContentBlock(AudioFormat audioFormat, uint8_t channelCount = 0);
  /* implicit */ ContentBlock(const AudioContentBlockSpec& audioSpec, size_t size);
 
  ContentBlock(
      AudioFormat audioFormat,
      AudioSampleFormat sampleFormat,
      uint8_t numChannels = 0,
      uint8_t sampleFrameStride = 0,
      uint32_t sampleRate = 0,
      uint32_t sampleCount = 0,
      uint8_t stereoPairCount = 0);
 
  ContentBlock(const ContentBlock&) = default;
  ContentBlock(ContentBlock&&) noexcept = default;
 
  ContentBlock(const ContentBlock& other, size_t size)
      : contentType_{other.contentType_}, size_{size} {
    if (contentType_ == ContentType::IMAGE) {
      imageSpec_ = other.imageSpec_;
    } else if (contentType_ == ContentType::AUDIO) {
      audioSpec_ = other.audioSpec_;
    } else if (contentType_ == ContentType::CUSTOM) {
      customContentBlockFormat_ = other.customContentBlockFormat_;
    }
  }
 
  ~ContentBlock() = default;
 
  ContentBlock& operator=(const ContentBlock& rhs) = default;
  ContentBlock& operator=(ContentBlock&& rhs) noexcept = default;
 
  string asString() const;
 
  size_t getBlockSize() const;
 
  ContentType getContentType() const {
    return contentType_;
  }
 
  string getCustomContentBlockFormat() const {
    return customContentBlockFormat_;
  }
 
  bool operator==(const ContentBlock& rhs) const;
 
  bool operator!=(const ContentBlock& rhs) const {
    return !operator==(rhs);
  }
 
  RecordFormat operator+(const ContentBlock&) const;
 
  const ImageContentBlockSpec& image() const;
  const AudioContentBlockSpec& audio() const;
 
 protected:
  ContentType contentType_ = ContentType::EMPTY;
  size_t size_ = kSizeUnknown;
  ImageContentBlockSpec imageSpec_;
  AudioContentBlockSpec audioSpec_;
  string customContentBlockFormat_;
};
 
class VRS_API CustomContentBlock : public ContentBlock {
 public:
  explicit CustomContentBlock(const string& customContentBlockFormat, size_t size = kSizeUnknown);
  explicit CustomContentBlock(size_t size = kSizeUnknown);
};
 
using RecordFormatMap = map<pair<Record::Type, uint32_t>, RecordFormat>;
 
class VRS_API ContentBlockId {
 public:
  ContentBlockId(
      RecordableTypeId typeIdIn,
      Record::Type recordTypeIn,
      uint32_t formatVersionIn,
      size_t blockIndexIn)
      : typeId(typeIdIn),
        recordType(recordTypeIn),
        formatVersion(formatVersionIn),
        blockIndex(blockIndexIn) {}
 
  RecordableTypeId getRecordableTypeId() const {
    return typeId;
  }
 
  Record::Type getRecordType() const {
    return recordType;
  }
 
  uint32_t getFormatVersion() const {
    return formatVersion;
  }
 
  size_t getBlockIndex() const {
    return blockIndex;
  }
 
 private:
  RecordableTypeId typeId;
  Record::Type recordType;
  uint32_t formatVersion;
  size_t blockIndex;
};
 
class VRS_API RecordFormat {
 public:
  RecordFormat() = default;
  RecordFormat(const RecordFormat&) = default;
  /* implicit */ RecordFormat(RecordFormat&&) noexcept = default;
  ~RecordFormat() = default;
 
  RecordFormat& operator=(const RecordFormat&) = default;
  RecordFormat& operator=(RecordFormat&&) noexcept = default;
 
  explicit RecordFormat(const string& format) {
    set(format);
  }
  explicit RecordFormat(const char* format) {
    set(format);
  }
  /* implicit */ RecordFormat(const ContentBlock& block) {
    blocks_.emplace_back(block);
  }
  /* implicit */ RecordFormat(ContentBlock&& block) noexcept {
    blocks_.emplace_back(std::move(block));
  }
  RecordFormat(const ContentBlock& first, const ContentBlock& second) {
    blocks_.emplace_back(first);
    blocks_.emplace_back(second);
  }
  RecordFormat(ContentBlock&& first, ContentBlock&& second) noexcept {
    blocks_.emplace_back(std::move(first));
    blocks_.emplace_back(std::move(second));
  }
  /* implicit */ RecordFormat(ContentType type, size_t size = ContentBlock::kSizeUnknown) {
    blocks_.emplace_back(type, size);
  }
 
  RecordFormat& operator+(const ContentBlock& block) {
    blocks_.emplace_back(block);
    return *this;
  }
  RecordFormat& operator+(ContentBlock&& block) {
    blocks_.emplace_back(std::move(block));
    return *this;
  }
 
  bool operator==(const RecordFormat& rhs) const;
  bool operator!=(const RecordFormat& rhs) const {
    return !operator==(rhs);
  }
 
  void clear() {
    blocks_.clear();
  }
 
  void set(const string& format);
  string asString() const;
 
  size_t getRecordSize() const;
  size_t getUsedBlocksCount() const;
  size_t getBlocksOfTypeCount(ContentType type) const;
  const ContentBlock& getContentBlock(size_t index) const;
  const ContentBlock& getFirstContentBlock() const {
    return getContentBlock(0);
  }
  size_t getRemainingBlocksSize(size_t firstBlock) const;
  size_t getBlockSize(size_t blockIndex, size_t remainingSize) const;
 
  // Static VRS dedicated helper methods, for RecordFormat & DataLayout purposes.
 
  static string getRecordFormatTagName(Record::Type recordType, uint32_t formatVersion);
  static string getDataLayoutTagName(Record::Type type, uint32_t version, size_t blockIndex);
  static bool parseRecordFormatTagName(
      const string& tagName,
      Record::Type& recordType,
      uint32_t& formatVersion);
 
  static bool addRecordFormat(
      map<string, string>& inOutRecordFormatRegister,
      Record::Type recordType,
      uint32_t formatVersion,
      const RecordFormat& format,
      const vector<const DataLayout*>& layouts);
 
  static void getRecordFormats(
      const map<string, string>& recordFormatRegister,
      RecordFormatMap& outFormats);
 
  static unique_ptr<DataLayout> getDataLayout(
      const map<string, string>& recordFormatRegister,
      const ContentBlockId& blockId);
 
 private:
  vector<ContentBlock> blocks_;
};
 
} // namespace vrs