blob: 7b0782f9c434df1494cf794a7c1602845b7faf10 [file] [log] [blame]
/*
* Copyright (c) 2015 The WebRTC project authors. All Rights Reserved.
*
* Use of this source code is governed by a BSD-style license
* that can be found in the LICENSE file in the root of the source
* tree. An additional intellectual property rights grant can be found
* in the file PATENTS. All contributing project authors may
* be found in the AUTHORS file in the root of the source tree.
*/
#ifndef API_VIDEO_VIDEO_FRAME_BUFFER_H_
#define API_VIDEO_VIDEO_FRAME_BUFFER_H_
#include <stdint.h>
#include "api/array_view.h"
#include "api/scoped_refptr.h"
#include "rtc_base/ref_count.h"
#include "rtc_base/system/rtc_export.h"
namespace webrtc {
class I420BufferInterface;
class I420ABufferInterface;
class I444BufferInterface;
class I010BufferInterface;
class NV12BufferInterface;
// Base class for frame buffers of different types of pixel format and storage.
// The tag in type() indicates how the data is represented, and each type is
// implemented as a subclass. To access the pixel data, call the appropriate
// GetXXX() function, where XXX represents the type. There is also a function
// ToI420() that returns a frame buffer in I420 format, converting from the
// underlying representation if necessary. I420 is the most widely accepted
// format and serves as a fallback for video sinks that can only handle I420,
// e.g. the internal WebRTC software encoders. A special enum value 'kNative' is
// provided for external clients to implement their own frame buffer
// representations, e.g. as textures. The external client can produce such
// native frame buffers from custom video sources, and then cast it back to the
// correct subclass in custom video sinks. The purpose of this is to improve
// performance by providing an optimized path without intermediate conversions.
// Frame metadata such as rotation and timestamp are stored in
// webrtc::VideoFrame, and not here.
class RTC_EXPORT VideoFrameBuffer : public rtc::RefCountInterface {
public:
// New frame buffer types will be added conservatively when there is an
// opportunity to optimize the path between some pair of video source and
// video sink.
// GENERATED_JAVA_ENUM_PACKAGE: org.webrtc
// GENERATED_JAVA_CLASS_NAME_OVERRIDE: VideoFrameBufferType
enum class Type {
kNative,
kI420,
kI420A,
kI444,
kI010,
kNV12,
};
// This function specifies in what pixel format the data is stored in.
virtual Type type() const = 0;
// The resolution of the frame in pixels. For formats where some planes are
// subsampled, this is the highest-resolution plane.
virtual int width() const = 0;
virtual int height() const = 0;
// Returns a memory-backed frame buffer in I420 format. If the pixel data is
// in another format, a conversion will take place. All implementations must
// provide a fallback to I420 for compatibility with e.g. the internal WebRTC
// software encoders.
// Conversion may fail, for example if reading the pixel data from a texture
// fails. If the conversion fails, nullptr is returned.
virtual rtc::scoped_refptr<I420BufferInterface> ToI420() = 0;
// GetI420() methods should return I420 buffer if conversion is trivial, i.e
// no change for binary data is needed. Otherwise these methods should return
// nullptr. One example of buffer with that property is
// WebrtcVideoFrameAdapter in Chrome - it's I420 buffer backed by a shared
// memory buffer. Therefore it must have type kNative. Yet, ToI420()
// doesn't affect binary data at all. Another example is any I420A buffer.
// TODO(https://crbug.com/webrtc/12021): Make this method non-virtual and
// behave as the other GetXXX methods below.
virtual const I420BufferInterface* GetI420() const;
// A format specific scale function. Default implementation works by
// converting to I420. But more efficient implementations may override it,
// especially for kNative.
// First, the image is cropped to `crop_width` and `crop_height` and then
// scaled to `scaled_width` and `scaled_height`.
virtual rtc::scoped_refptr<VideoFrameBuffer> CropAndScale(int offset_x,
int offset_y,
int crop_width,
int crop_height,
int scaled_width,
int scaled_height);
// Alias for common use case.
rtc::scoped_refptr<VideoFrameBuffer> Scale(int scaled_width,
int scaled_height) {
return CropAndScale(0, 0, width(), height(), scaled_width, scaled_height);
}
// These functions should only be called if type() is of the correct type.
// Calling with a different type will result in a crash.
const I420ABufferInterface* GetI420A() const;
const I444BufferInterface* GetI444() const;
const I010BufferInterface* GetI010() const;
const NV12BufferInterface* GetNV12() const;
// From a kNative frame, returns a VideoFrameBuffer with a pixel format in
// the list of types that is in the main memory with a pixel perfect
// conversion for encoding with a software encoder. Returns nullptr if the
// frame type is not supported, mapping is not possible, or if the kNative
// frame has not implemented this method. Only callable if type() is kNative.
virtual rtc::scoped_refptr<VideoFrameBuffer> GetMappedFrameBuffer(
rtc::ArrayView<Type> types);
protected:
~VideoFrameBuffer() override {}
};
// Update when VideoFrameBuffer::Type is updated.
const char* VideoFrameBufferTypeToString(VideoFrameBuffer::Type type);
// This interface represents planar formats.
class PlanarYuvBuffer : public VideoFrameBuffer {
public:
virtual int ChromaWidth() const = 0;
virtual int ChromaHeight() const = 0;
// Returns the number of steps(in terms of Data*() return type) between
// successive rows for a given plane.
virtual int StrideY() const = 0;
virtual int StrideU() const = 0;
virtual int StrideV() const = 0;
protected:
~PlanarYuvBuffer() override {}
};
// This interface represents 8-bit color depth formats: Type::kI420,
// Type::kI420A and Type::kI444.
class PlanarYuv8Buffer : public PlanarYuvBuffer {
public:
// Returns pointer to the pixel data for a given plane. The memory is owned by
// the VideoFrameBuffer object and must not be freed by the caller.
virtual const uint8_t* DataY() const = 0;
virtual const uint8_t* DataU() const = 0;
virtual const uint8_t* DataV() const = 0;
protected:
~PlanarYuv8Buffer() override {}
};
class RTC_EXPORT I420BufferInterface : public PlanarYuv8Buffer {
public:
Type type() const override;
int ChromaWidth() const final;
int ChromaHeight() const final;
rtc::scoped_refptr<I420BufferInterface> ToI420() final;
const I420BufferInterface* GetI420() const final;
protected:
~I420BufferInterface() override {}
};
class RTC_EXPORT I420ABufferInterface : public I420BufferInterface {
public:
Type type() const final;
virtual const uint8_t* DataA() const = 0;
virtual int StrideA() const = 0;
protected:
~I420ABufferInterface() override {}
};
class I444BufferInterface : public PlanarYuv8Buffer {
public:
Type type() const final;
int ChromaWidth() const final;
int ChromaHeight() const final;
protected:
~I444BufferInterface() override {}
};
// This interface represents 8-bit to 16-bit color depth formats: Type::kI010.
class PlanarYuv16BBuffer : public PlanarYuvBuffer {
public:
// Returns pointer to the pixel data for a given plane. The memory is owned by
// the VideoFrameBuffer object and must not be freed by the caller.
virtual const uint16_t* DataY() const = 0;
virtual const uint16_t* DataU() const = 0;
virtual const uint16_t* DataV() const = 0;
protected:
~PlanarYuv16BBuffer() override {}
};
// Represents Type::kI010, allocates 16 bits per pixel and fills 10 least
// significant bits with color information.
class I010BufferInterface : public PlanarYuv16BBuffer {
public:
Type type() const override;
int ChromaWidth() const final;
int ChromaHeight() const final;
protected:
~I010BufferInterface() override {}
};
class BiplanarYuvBuffer : public VideoFrameBuffer {
public:
virtual int ChromaWidth() const = 0;
virtual int ChromaHeight() const = 0;
// Returns the number of steps(in terms of Data*() return type) between
// successive rows for a given plane.
virtual int StrideY() const = 0;
virtual int StrideUV() const = 0;
protected:
~BiplanarYuvBuffer() override {}
};
class BiplanarYuv8Buffer : public BiplanarYuvBuffer {
public:
virtual const uint8_t* DataY() const = 0;
virtual const uint8_t* DataUV() const = 0;
protected:
~BiplanarYuv8Buffer() override {}
};
// Represents Type::kNV12. NV12 is full resolution Y and half-resolution
// interleved UV.
class RTC_EXPORT NV12BufferInterface : public BiplanarYuv8Buffer {
public:
Type type() const override;
int ChromaWidth() const final;
int ChromaHeight() const final;
rtc::scoped_refptr<VideoFrameBuffer> CropAndScale(int offset_x,
int offset_y,
int crop_width,
int crop_height,
int scaled_width,
int scaled_height) override;
protected:
~NV12BufferInterface() override {}
};
} // namespace webrtc
#endif // API_VIDEO_VIDEO_FRAME_BUFFER_H_