frame_buffer.h | Explore in Territory

/*
 * 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.
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.
Libgav1FrameBufferSizeChangedCallback;

// 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.
Libgav1GetFrameBufferCallback;

// 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.
Libgav1ReleaseFrameBufferCallback;

// 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.
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 {

FrameBuffer;
FrameBufferSizeChangedCallback;
GetFrameBufferCallback;
ReleaseFrameBufferCallback;
FrameBufferInfo;

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) { … }

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) { … }

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

#endif  // LIBGAV1_SRC_GAV1_FRAME_BUFFER_H_
chromium/third_party/libgav1/src/src/gav1/frame_buffer.h
