StormByte-Multimedia 3.3.2
C++26 multimedia processing module of the StormByte suite
Loading...
Searching...
No Matches
AVFrame.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This file is part of StormByte-Multimedia.
5 *
6 * StormByte-Multimedia original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte-Multimedia source in this
20 * file. Third-party components — including FFmpeg and embedded trained data —
21 * remain under their own licenses and are not covered by the commercial grant.
22 *
23 * A written StormByte commercial agreement may license this original source
24 * on terms other than the LGPL, including specific use, distribution or
25 * linking arrangements such as static linking, as stated in that agreement.
26 * It does not grant rights to dependencies or waive their license conditions.
27 * Enabling WITH_GPL or WITH_NONFREE may include components with separate
28 * obligations for modification, linking (static or dynamic), redistribution
29 * or works that incorporate them. The person modifying, linking, packaging or
30 * distributing the resulting work is responsible for determining and meeting
31 * all applicable requirements, including any needed patent permissions.
32 * A StormByte commercial agreement does not provide those rights for GPL or
33 * nonfree components.
34 *
35 * Neither license grants any patent rights. Any patent licenses required
36 * to use this software or third-party components must be obtained separately
37 * from the patent holders.
38 *
39 * StormByte-Multimedia is distributed in the hope that it will be useful,
40 * but WITHOUT ANY WARRANTY; without even the implied warranty of
41 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
42 * GNU Lesser General Public License for more details.
43 *
44 * You should have received a copy of the GNU Lesser General Public License
45 * version 3 along with StormByte-Multimedia. If not, see
46 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
47 *
48 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
49 */
50
51#pragma once
52
53#include <StormByte/size.hxx>
54#include <StormByte/buffer/typedefs.hxx>
61#include <StormByte/safe/binary.hxx>
62#include <StormByte/safe/vector.hxx>
63
64#include <cstddef>
65#include <cstdint>
66#include <string_view>
67#include <vector>
68
73namespace StormByte {
78 namespace Multimedia {
83 namespace Pipeline {
88 namespace Filter {
92 class FFmpeg;
93 }
94 }
95 }
96}
97
106 class Frame;
107}
108
113namespace StormByte {
118 namespace Multimedia {
123 namespace FFmpeg {
127 class AVDecoder;
128
132 class AVEncoder;
133
137 class AVFilterGraph;
138
142 class Swr;
143
147 class Sws;
148
162 public:
166 AVFrame() noexcept;
167
174 AVFrame(const AVFrame& other) noexcept;
175
180 AVFrame(AVFrame&& other) noexcept = default;
181
185 ~AVFrame() noexcept override;
186
192 AVFrame& operator=(const AVFrame& other) noexcept;
193
199 AVFrame& operator=(AVFrame&& other) noexcept = default;
200
205 explicit operator bool() const noexcept;
206
213 AVFrame Clone() const noexcept;
214
220 bool Ref(const AVFrame& other) noexcept;
221
227 bool Copy(const AVFrame& other) noexcept;
228
234 bool CopyProps(const AVFrame& other) noexcept;
235
241 bool GetBuffer(int align = 0) noexcept;
242
251 bool AllocVideo(int width, int height, int format, int align = 0) noexcept;
252
261 bool AllocAudio(int nb_samples, int format, const AVChannelLayout& layout, int sample_rate) noexcept;
262
266 void Unref() noexcept;
267
272 int Width() const noexcept;
273
278 void Width(int width) noexcept;
279
284 int Height() const noexcept;
285
290 void Height(int height) noexcept;
291
296 int Format() const noexcept;
297
302 void Format(int format) noexcept;
303
308 bool Hardware() const noexcept;
309
314 bool Download() noexcept;
315
320 static int FormatNone() noexcept;
321
326 static int FormatGray8() noexcept;
327
332 static int FormatRgba() noexcept;
333
338 static int FormatYUV420P() noexcept;
339
346 enum class VideoLayout: std::uint8_t {
348 Gray,
349 Yuv420,
350 Yuv422,
351 Yuv444
352 };
353
360 enum class Scaler: std::uint8_t {
361 Zimg,
363 };
364
372 enum class Resample: std::uint8_t {
373 Default,
374 Point,
375 Bilinear,
376 Bicubic,
377 Spline,
378 Lanczos
379 };
380
385 VideoLayout Layout() const noexcept;
386
399 static AVFrame DecodeImage(const std::uint8_t* data, StormByte::Size size,
400 std::string_view hint = {});
401
406 std::int64_t Pts() const noexcept;
407
412 void Pts(std::int64_t pts) noexcept;
413
418 std::int64_t BestEffortTimestamp() const noexcept;
419
424 void BestEffortTimestamp(std::int64_t ts) noexcept;
425
430 std::int64_t DurationTicks() const noexcept;
431
436 void DurationTicks(std::int64_t duration) noexcept;
437
442 AVRational TimeBase() const noexcept;
443
448 void TimeBase(AVRational timeBase) noexcept;
449
454 int ColorRange() const noexcept;
455
460 void ColorRange(int range) noexcept;
461
466 int ColorSpace() const noexcept;
467
472 void ColorSpace(int space) noexcept;
473
478 int ColorPrimaries() const noexcept;
479
484 void ColorPrimaries(int primaries) noexcept;
485
490 int ColorTransfer() const noexcept;
491
496 void ColorTransfer(int transfer) noexcept;
497
502 int ChromaLocation() const noexcept;
503
508 void ChromaLocation(int location) noexcept;
509
515
520 void SampleAspectRatio(AVRational sar) noexcept;
521
526 int PictType() const noexcept;
527
532 void PictType(int type) noexcept;
533
538 bool KeyFrame() const noexcept;
539
544 void KeyFrame(bool key) noexcept;
545
550 int RepeatPict() const noexcept;
551
556 void RepeatPict(int repeat) noexcept;
557
562 bool Interlaced() const noexcept;
563
569 void Interlaced(bool interlaced, bool top_first) noexcept;
570
575 bool TopFieldFirst() const noexcept;
576
581 int CropLeft() const noexcept;
582
587 int CropRight() const noexcept;
588
593 int CropTop() const noexcept;
594
599 int CropBottom() const noexcept;
600
608 void Crop(int left, int right, int top, int bottom) noexcept;
609
615 bool ApplyCropping(int flags = 0) noexcept;
616
622 int PlaneCount() const noexcept;
623
629 int PlaneWidth(int plane) const noexcept;
630
636 int PlaneHeight(int plane) const noexcept;
637
642 int BitsPerComponent() const noexcept;
643
648 bool PlanarInteger() const noexcept;
649
659 int PlanarLayout() const noexcept;
660
665 bool BigEndianSamples() const noexcept;
666
671 const char* FormatName() const noexcept;
672
678 const uint8_t* Data(int plane) const noexcept;
679
685 uint8_t* Data(int plane) noexcept;
686
692 int Linesize(int plane) const noexcept;
693
698 int NbSamples() const noexcept;
699
704 void NbSamples(int samples) noexcept;
705
710 int SampleRate() const noexcept;
711
716 void SampleRate(int rate) noexcept;
717
722 int Channels() const noexcept;
723
729
735 bool CopyChannelLayout(const AVChannelLayout& layout) noexcept;
736
741 uint8_t** ExtendedData() noexcept;
742
747 const uint8_t* const* ExtendedData() const noexcept;
748
754 const AVFrameSideData* SideData(int type) const noexcept;
755
761 AVFrameSideData* SideData(int type) noexcept;
762
767 void RemoveSideData(int type) noexcept;
768
773 int SideDataCount() const noexcept;
774
780 const AVFrameSideData* SideDataAt(int index) const noexcept;
781
788 uint8_t* NewSideData(int type, int size) noexcept;
789
794 void CopyPrimaryBuffer(StormByte::Safe::Binary& out) const noexcept;
795
800 void WriteHdr10(const StormByte::Multimedia::Property::HDR10& hdr10) noexcept;
801
806 void WriteSideData(const Safe::Vector<StormByte::Multimedia::Pipeline::SideData>& attachments) noexcept;
807
815 struct ColorTarget {
816 int transfer = -1;
817 int primaries = -1;
818 int matrix = -1;
819 int range = -1;
820 double peak = 0;
821 };
822
833 bool ScaleTo(AVFrame& dst, int dst_w, int dst_h,
835 Scaler scaler = Scaler::Zimg) const noexcept;
836
843 public:
848
852 ~ScaleContext() noexcept;
853
858 ScaleContext(const ScaleContext& other) = delete;
859
865 ScaleContext& operator=(const ScaleContext& other) = delete;
866
867 private:
871 friend class AVFrame;
872
876 class State;
877
878 State* m_state;
879 };
880
891 bool ScaleTo(ScaleContext& context, AVFrame& dst, int dst_w, int dst_h,
892 Resample filter = Resample::Default,
893 Scaler scaler = Scaler::Zimg) const noexcept;
894
906 bool ScaleTo(ScaleContext& context, AVFrame& dst, int dst_w, int dst_h,
907 Resample filter, Scaler scaler, ColorTarget color) const noexcept;
908
913 void Reset(::AVFrame* raw) noexcept;
914
915 private:
919 friend class AVDecoder;
920
924 friend class AVEncoder;
925
929 friend class AVFilterGraph;
930
935
939 friend class StormByte::Multimedia::Pipeline::Filter::FFmpeg;
940
944 friend class Swr;
945
949 friend class Sws;
950
954 void Free() noexcept override;
955
959 using AVPointer<::AVFrame>::Get;
960
964 using AVPointer<::AVFrame>::Detach;
965 };
966
968
971 extern template class STORMBYTE_MULTIMEDIA_PUBLIC AVPointer<::AVFrame>;
973 }
974 }
975}
976
STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Buffer::Bridge)
RAII AVChannelLayout (av_channel_layout_copy / uninit).
Definition AVChannelLayout.hxx:111
Reusable scaler graphs and workers with explicit owner lifetime.
Definition AVFrame.hxx:842
~ScaleContext() noexcept
Joins scaling workers and frees cached graphs.
friend class AVFrame
Grants frame scaling access to the cached backends.
Definition AVFrame.hxx:871
ScaleContext()
Creates an empty reusable scaler cache.
int Linesize(int plane) const noexcept
Bytes per row for plane, including padding.
int PlaneHeight(int plane) const noexcept
Height of plane accounting for chroma subsampling.
bool BigEndianSamples() const noexcept
Byte order of multi-byte video samples.
void CopyPrimaryBuffer(StormByte::Safe::Binary &out) const noexcept
Packs planar video/audio into out without linesize padding.
int ColorRange() const noexcept
Color range.
bool Interlaced() const noexcept
Whether the frame is interlaced.
Resample
Resample kernel for StormByte::Multimedia::FFmpeg::AVFrame::ScaleTo.
Definition AVFrame.hxx:372
@ Default
Backend default.
Definition AVFrame.hxx:373
Scaler
Resampling backend for StormByte::Multimedia::FFmpeg::AVFrame::ScaleTo.
Definition AVFrame.hxx:360
@ Zimg
zimg graph (default).
Definition AVFrame.hxx:361
void Unref() noexcept
Unreferences frame buffers (av_frame_unref).
VideoLayout
Planar video family, ignoring bit depth.
Definition AVFrame.hxx:346
bool PlanarInteger() const noexcept
Checks for independent integer YUV/gray planes at 8/10/12/16 bits.
friend class AVFilterGraph
Allows the filter graph to access the raw frame.
Definition AVFrame.hxx:929
bool CopyChannelLayout(const AVChannelLayout &layout) noexcept
Replaces the channel layout.
int RepeatPict() const noexcept
Extra delay in field durations (repeat_pict).
int Width() const noexcept
Frame width in pixels.
int PlaneWidth(int plane) const noexcept
Width of plane accounting for chroma subsampling.
int SampleRate() const noexcept
Audio sample rate in Hz.
AVRational SampleAspectRatio() const noexcept
Sample aspect ratio.
bool AllocAudio(int nb_samples, int format, const AVChannelLayout &layout, int sample_rate) noexcept
Sets audio samples, format and layout, then allocates planes.
AVFrame() noexcept
Allocates an empty frame (av_frame_alloc).
bool Hardware() const noexcept
Whether the pixel format is hardware-backed.
void WriteSideData(const Safe::Vector< StormByte::Multimedia::Pipeline::SideData > &attachments) noexcept
Copies raw SEI/side-data blobs onto the frame.
friend class StormByte::Multimedia::Backend::Pipeline::Frame
Allows the backend frame holder to access the raw frame.
Definition AVFrame.hxx:934
bool AllocVideo(int width, int height, int format, int align=0) noexcept
Sets video geometry and format, then allocates planes.
static int FormatNone() noexcept
AV_PIX_FMT_NONE as int.
bool ScaleTo(AVFrame &dst, int dst_w, int dst_h, Resample filter=Resample::Default, Scaler scaler=Scaler::Zimg) const noexcept
Scales this frame into dst (allocates dst if empty).
std::int64_t DurationTicks() const noexcept
Duration in stream ticks.
const AVFrameSideData * SideDataAt(int index) const noexcept
Side data at index.
int PlaneCount() const noexcept
Number of video components or audio channels.
int ColorTransfer() const noexcept
Transfer characteristics.
AVChannelLayout ChannelLayout() const noexcept
Channel layout owned by this frame.
int ChromaLocation() const noexcept
Chroma sample location.
VideoLayout Layout() const noexcept
Planar layout of this frame.
int CropTop() const noexcept
Top crop in pixels.
AVFrame Clone() const noexcept
New frame referencing the same planes (av_frame_ref).
bool KeyFrame() const noexcept
Whether this is a key frame.
friend class Swr
Allows the audio resampler to access the raw frame.
Definition AVFrame.hxx:944
friend class AVEncoder
Allows the encoder to access the raw frame.
Definition AVFrame.hxx:924
static AVFrame DecodeImage(const std::uint8_t *data, StormByte::Size size, std::string_view hint={})
Decodes one still image from a compressed buffer.
bool GetBuffer(int align=0) noexcept
Allocates plane buffers (av_frame_get_buffer).
void WriteHdr10(const StormByte::Multimedia::Property::HDR10 &hdr10) noexcept
Writes mastering display and content light from hdr10.
std::int64_t Pts() const noexcept
Presentation timestamp in stream ticks.
int PlanarLayout() const noexcept
Layout with one integer component per plane, as per-plane filters read it.
int CropLeft() const noexcept
Left crop in pixels.
const char * FormatName() const noexcept
Pixel or sample format name.
int ColorPrimaries() const noexcept
Color primaries.
int BitsPerComponent() const noexcept
Bits per component from the pixel descriptor.
static int FormatGray8() noexcept
AV_PIX_FMT_GRAY8 as int.
bool CopyProps(const AVFrame &other) noexcept
Copies metadata from other (av_frame_copy_props).
int Format() const noexcept
Pixel or sample format.
int CropBottom() const noexcept
Bottom crop in pixels.
int Channels() const noexcept
Audio channel count.
friend class AVDecoder
Allows the decoder to access the raw frame.
Definition AVFrame.hxx:919
bool Copy(const AVFrame &other) noexcept
Copies samples/planes from other (av_frame_copy).
friend class Sws
Allows the video scaler to access the raw frame.
Definition AVFrame.hxx:949
int Height() const noexcept
Frame height in pixels.
std::int64_t BestEffortTimestamp() const noexcept
Best-effort timestamp (best_effort_timestamp).
void Crop(int left, int right, int top, int bottom) noexcept
Sets crop window.
bool TopFieldFirst() const noexcept
Whether the top field is first (interlaced).
friend class StormByte::Multimedia::Pipeline::Filter::FFmpeg
Allows the filter base to access the raw frame.
Definition AVFrame.hxx:939
int NbSamples() const noexcept
Audio sample count.
AVRational TimeBase() const noexcept
Native timebase for frame timestamps.
void RemoveSideData(int type) noexcept
Removes side data of type.
static int FormatYUV420P() noexcept
AV_PIX_FMT_YUV420P as int.
int SideDataCount() const noexcept
Number of side-data entries.
void Reset(::AVFrame *raw) noexcept
Adopts raw.
uint8_t * NewSideData(int type, int size) noexcept
Allocates side data of type (av_frame_new_side_data).
int PictType() const noexcept
Picture type (I/P/B/...).
const AVFrameSideData * SideData(int type) const noexcept
Looks up side data.
uint8_t ** ExtendedData() noexcept
Planar audio / video data pointers (extended_data).
bool Download() noexcept
Downloads a hardware frame to a software frame, preserving properties.
int CropRight() const noexcept
Right crop in pixels.
bool ApplyCropping(int flags=0) noexcept
Applies the crop window (av_frame_apply_cropping).
static int FormatRgba() noexcept
AV_PIX_FMT_RGBA as int.
const uint8_t * Data(int plane) const noexcept
Const pointer to plane plane.
int ColorSpace() const noexcept
Matrix coefficients.
bool Ref(const AVFrame &other) noexcept
Shares buffers with other (av_frame_ref).
constexpr const std::decay_t< ::AVFrame > * Get() const noexcept
Definition AVPointer.hxx:151
constexpr std::decay_t< ::AVFrame > * Detach() noexcept
Definition AVPointer.hxx:172
Abstract base for every StormByte Multimedia filter.
Definition ffmpeg.hxx:261
Pair {num, den} matching libavutil AVRational.
Definition av_rational.hxx:85
Incomplete FFmpeg types for RAII headers.
Multimedia module of the StormByte suite.
Pipeline Demux / decode / filter / encode / mux types.
Media property value types.
Multimedia-owned pipeline stages and unit holders.
Private RAII wrappers over libav*.
Frame and packet steps attached to a job or a raw pipeline.
Multimedia module of the StormByte suite.
@ Unknown
Subtitle without a reliable representation classification.
Definition codec.hxx:83
Root namespace of the StormByte C++ suite.
STL namespace.
Output colorspace for the cached zimg scaler.
Definition AVFrame.hxx:815
int range
AVColorRange
Definition AVFrame.hxx:819
int primaries
AVColorPrimaries
Definition AVFrame.hxx:817
double peak
Nominal peak luminance, cd/m²
Definition AVFrame.hxx:820
int transfer
AVColorTransferCharacteristic
Definition AVFrame.hxx:816
int matrix
AVColorSpace
Definition AVFrame.hxx:818
#define STORMBYTE_MULTIMEDIA_PUBLIC
Definition visibility.h:61