xref: /aosp_15_r20/external/libgav1/src/gav1/frame_buffer.h (revision 095378508e87ed692bf8dfeb34008b65b3735891)

/*
 * Copyright 2020 The libgav1 Authors
 *
 * 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.
 */

#ifndef LIBGAV1_SRC_GAV1_FRAME_BUFFER_H_
#define LIBGAV1_SRC_GAV1_FRAME_BUFFER_H_

// All the declarations in this file are part of the public ABI. This file may
// be included by both C and C++ files.

#if defined(__cplusplus)
#include <cstddef>
#include <cstdint>
#else
#include <stddef.h>
#include <stdint.h>
#endif  // defined(__cplusplus)

#include "gav1/decoder_buffer.h"
#include "gav1/status_code.h"
#include "gav1/symbol_visibility.h"

// The callback functions use the C linkage conventions.
#if defined(__cplusplus)
extern "C" {
#endif

// This structure represents an allocated frame buffer.
typedef struct Libgav1FrameBuffer {
  // In the |plane| and |stride| arrays, the elements at indexes 0, 1, and 2
  // are for the Y, U, and V planes, respectively.
  uint8_t* plane[3];   // Pointers to the frame (excluding the borders) in the
                       // data buffers.
  int stride[3];       // Row strides in bytes.
  void* private_data;  // Frame buffer's private data. Available for use by the
                       // release frame buffer callback. Also copied to the
                       // |buffer_private_data| field of DecoderBuffer for use
                       // by the consumer of a DecoderBuffer.
} Libgav1FrameBuffer;

// This callback is invoked by the decoder to provide information on the
// subsequent frames in the video, until the next invocation of this callback
// or the end of the video.
//
// |width| and |height| are the maximum frame width and height in pixels.
// |left_border|, |right_border|, |top_border|, and |bottom_border| are the
// maximum left, right, top, and bottom border sizes in pixels.
// |stride_alignment| specifies the alignment of the row stride in bytes.
//
// Returns kLibgav1StatusOk on success, an error status on failure.
//
// NOTE: This callback may be omitted if the information is not useful to the
// application.
typedef Libgav1StatusCode (*Libgav1FrameBufferSizeChangedCallback)(
    void* callback_private_data, int bitdepth, Libgav1ImageFormat image_format,
    int width, int height, int left_border, int right_border, int top_border,
    int bottom_border, int stride_alignment);

// This callback is invoked by the decoder to allocate a frame buffer, which
// consists of three data buffers, for the Y, U, and V planes, respectively.
//
// The callback must set |frame_buffer->plane[i]| to point to the data buffers
// of the planes, and set |frame_buffer->stride[i]| to the row strides of the
// planes. If |image_format| is kLibgav1ImageFormatMonochrome400, the callback
// should set |frame_buffer->plane[1]| and |frame_buffer->plane[2]| to a null
// pointer and set |frame_buffer->stride[1]| and |frame_buffer->stride[2]| to
// 0. The callback may set |frame_buffer->private_data| to a value that will
// be useful to the release frame buffer callback and the consumer of a
// DecoderBuffer.
//
// Returns kLibgav1StatusOk on success, an error status on failure.

// |width| and |height| are the frame width and height in pixels.
// |left_border|, |right_border|, |top_border|, and |bottom_border| are the
// left, right, top, and bottom border sizes in pixels. |stride_alignment|
// specifies the alignment of the row stride in bytes.
typedef Libgav1StatusCode (*Libgav1GetFrameBufferCallback)(
    void* callback_private_data, int bitdepth, Libgav1ImageFormat image_format,
    int width, int height, int left_border, int right_border, int top_border,
    int bottom_border, int stride_alignment, Libgav1FrameBuffer* frame_buffer);

// After a frame buffer is allocated, the decoder starts to write decoded video
// to the frame buffer. When the frame buffer is ready for consumption, it is
// made available to the application in a Decoder::DequeueFrame() call.
// Afterwards, the decoder may continue to use the frame buffer in read-only
// mode. When the decoder is finished using the frame buffer, it notifies the
// application by calling the Libgav1ReleaseFrameBufferCallback.

// This callback is invoked by the decoder to release a frame buffer.
typedef void (*Libgav1ReleaseFrameBufferCallback)(void* callback_private_data,
                                                  void* buffer_private_data);

// Libgav1ComputeFrameBufferInfo() and Libgav1SetFrameBuffer() are intended to
// help clients implement frame buffer callbacks using memory buffers. First,
// call Libgav1ComputeFrameBufferInfo(). If it succeeds, allocate y_buffer of
// size info.y_buffer_size and allocate u_buffer and v_buffer, both of size
// info.uv_buffer_size. Finally, pass y_buffer, u_buffer, v_buffer, and
// buffer_private_data to Libgav1SetFrameBuffer().

// This structure contains information useful for allocating memory for a frame
// buffer.
typedef struct Libgav1FrameBufferInfo {
  size_t y_buffer_size;   // Size in bytes of the Y buffer.
  size_t uv_buffer_size;  // Size in bytes of the U or V buffer.

  // The following fields are consumed by Libgav1SetFrameBuffer(). Do not use
  // them directly.
  int y_stride;            // Row stride in bytes of the Y buffer.
  int uv_stride;           // Row stride in bytes of the U or V buffer.
  size_t y_plane_offset;   // Offset in bytes of the frame (excluding the
                           // borders) in the Y buffer.
  size_t uv_plane_offset;  // Offset in bytes of the frame (excluding the
                           // borders) in the U or V buffer.
  int stride_alignment;    // The stride_alignment argument passed to
                           // Libgav1ComputeFrameBufferInfo().
} Libgav1FrameBufferInfo;

// Computes the information useful for allocating memory for a frame buffer.
// On success, stores the output in |info|.
LIBGAV1_PUBLIC Libgav1StatusCode Libgav1ComputeFrameBufferInfo(
    int bitdepth, Libgav1ImageFormat image_format, int width, int height,
    int left_border, int right_border, int top_border, int bottom_border,
    int stride_alignment, Libgav1FrameBufferInfo* info);

// Sets the |frame_buffer| struct.
LIBGAV1_PUBLIC Libgav1StatusCode Libgav1SetFrameBuffer(
    const Libgav1FrameBufferInfo* info, uint8_t* y_buffer, uint8_t* u_buffer,
    uint8_t* v_buffer, void* buffer_private_data,
    Libgav1FrameBuffer* frame_buffer);

#if defined(__cplusplus)
}  // extern "C"

// Declare type aliases for C++.
namespace libgav1 {

using FrameBuffer = Libgav1FrameBuffer;
using FrameBufferSizeChangedCallback = Libgav1FrameBufferSizeChangedCallback;
using GetFrameBufferCallback = Libgav1GetFrameBufferCallback;
using ReleaseFrameBufferCallback = Libgav1ReleaseFrameBufferCallback;
using FrameBufferInfo = Libgav1FrameBufferInfo;

inline StatusCode ComputeFrameBufferInfo(int bitdepth, ImageFormat image_format,
                                         int width, int height, int left_border,
                                         int right_border, int top_border,
                                         int bottom_border,
                                         int stride_alignment,
                                         FrameBufferInfo* info) {
  return Libgav1ComputeFrameBufferInfo(bitdepth, image_format, width, height,
                                       left_border, right_border, top_border,
                                       bottom_border, stride_alignment, info);
}

inline StatusCode SetFrameBuffer(const FrameBufferInfo* info, uint8_t* y_buffer,
                                 uint8_t* u_buffer, uint8_t* v_buffer,
                                 void* buffer_private_data,
                                 FrameBuffer* frame_buffer) {
  return Libgav1SetFrameBuffer(info, y_buffer, u_buffer, v_buffer,
                               buffer_private_data, frame_buffer);
}

}  // namespace libgav1
#endif  // defined(__cplusplus)

#endif  // LIBGAV1_SRC_GAV1_FRAME_BUFFER_H_