StormByte-Multimedia 3.3.2
C++26 multimedia processing module of the StormByte suite
Loading...
Searching...
No Matches
display.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
56#include <StormByte/safe/binary.hxx>
57#include <StormByte/safe/pointers.hxx>
58#include <StormByte/safe/string.hxx>
59#include <StormByte/safe/vector.hxx>
60
61#include <array>
62#include <cstdint>
63
68namespace StormByte {
73 namespace Multimedia {
78 enum class PreviewColorMode {
81 };
82
91 PreviewVideo() = default;
92
97 PreviewVideo(const PreviewVideo& other) = default;
98
103 PreviewVideo(PreviewVideo&& other) noexcept = default;
104
108 ~PreviewVideo() noexcept = default;
109
115 PreviewVideo& operator=(const PreviewVideo& other) = default;
116
122 PreviewVideo& operator=(PreviewVideo&& other) noexcept = default;
123
124 Safe::Binary m_pixels;
125 std::uint32_t m_width = 0;
126 std::uint32_t m_height = 0;
127 std::uint64_t m_epoch = 0;
128 double m_position = 0;
129 double m_duration = 0;
130 };
131
141 PreviewHDRVideo() = default;
142 PreviewHDRVideo(const PreviewHDRVideo& other) = default;
143 PreviewHDRVideo(PreviewHDRVideo&& other) noexcept = default;
144 ~PreviewHDRVideo() noexcept = default;
145 PreviewHDRVideo& operator=(const PreviewHDRVideo& other) = default;
146 PreviewHDRVideo& operator=(PreviewHDRVideo&& other) noexcept = default;
147
148 Safe::Binary m_pixels;
149 std::uint32_t m_width = 0;
150 std::uint32_t m_height = 0;
151 std::uint64_t m_epoch = 0;
152 double m_position = 0;
153 double m_duration = 0;
154 Property::Primaries m_primaries = Property::Primaries::Unspecified;
155 Property::Transfer m_transfer = Property::Transfer::Unspecified;
156 std::array<std::array<double, 2>, 3> m_display_primaries{};
157 std::array<double, 2> m_white_point{};
160 std::uint32_t m_max_content_light_nits = 0;
163 bool m_has_content_light = false;
164 };
165
178
189
207 PreviewAudio() = default;
208
213 PreviewAudio(const PreviewAudio& other) = default;
214
219 PreviewAudio(PreviewAudio&& other) noexcept = default;
220
224 ~PreviewAudio() noexcept = default;
225
231 PreviewAudio& operator=(const PreviewAudio& other) = default;
232
238 PreviewAudio& operator=(PreviewAudio&& other) noexcept = default;
239
240 Safe::Vector<Safe::Binary> m_planes;
241 Safe::Vector<Safe::String> m_channels;
244 bool m_planar = false;
245 std::uint32_t m_rate = 0;
246 std::uint32_t m_frames = 0;
247 std::uint64_t m_epoch = 0;
248 double m_position = 0;
249 };
250
260
269 SubtitleRegion() = default;
270
275 SubtitleRegion(const SubtitleRegion& other) = default;
276
281 SubtitleRegion(SubtitleRegion&& other) noexcept = default;
282
286 ~SubtitleRegion() noexcept = default;
287
293 SubtitleRegion& operator=(const SubtitleRegion& other) = default;
294
300 SubtitleRegion& operator=(SubtitleRegion&& other) noexcept = default;
301
303 Safe::String m_text;
304 Safe::Binary m_pixels;
305 int m_x = 0;
306 int m_y = 0;
307 int m_width = 0;
308 int m_height = 0;
309 };
310 }
311}
312
317
322namespace StormByte {
327 namespace Multimedia {
336 PreviewSubtitle() = default;
337
342 PreviewSubtitle(const PreviewSubtitle& other) = default;
343
348 PreviewSubtitle(PreviewSubtitle&& other) noexcept = default;
349
353 ~PreviewSubtitle() noexcept = default;
354
360 PreviewSubtitle& operator=(const PreviewSubtitle& other) = default;
361
367 PreviewSubtitle& operator=(PreviewSubtitle&& other) noexcept = default;
368
371 Safe::Vector<Safe::Shared<const Attachment>> m_fonts;
374 std::uint64_t m_epoch = 0;
375 std::uint64_t m_id = 0;
376 double m_start = 0;
377 double m_end = 0;
378 };
379
392 AudioPresentation() = default;
393
398 AudioPresentation(const AudioPresentation& other) = default;
399
404 AudioPresentation(AudioPresentation&& other) noexcept = default;
405
409 ~AudioPresentation() noexcept = default;
410
416 AudioPresentation& operator=(const AudioPresentation& other) = default;
417
423 AudioPresentation& operator=(AudioPresentation&& other) noexcept = default;
424
425 bool m_valid = false;
426 bool m_drained = false;
427 double m_position = 0;
428 double m_latency = 0;
429 };
430
447 public:
451 Display() = default;
452
453 Display(const Display&) = delete;
454
455 Display(Display&&) = delete;
456
460 virtual ~Display() noexcept = default;
461
462 Display& operator=(const Display&) = delete;
463
464 Display& operator=(Display&&) = delete;
465
471 virtual void Invalidate(std::uint64_t epoch, bool active_video) = 0;
472
482 virtual bool InvalidateAudio(std::uint64_t epoch) {
483 (void)epoch;
484 return false;
485 }
486
492 virtual void Pause(bool paused, std::uint64_t epoch) = 0;
493
499
505
514
520 virtual AudioPresentation AudioClock(std::uint64_t epoch) = 0;
521
527 virtual void Position(double position, std::uint64_t epoch) = 0;
528
534 virtual bool Drained(std::uint64_t epoch) = 0;
535 };
536
546 public:
547 virtual ~HDRDisplay() noexcept = default;
548
553 virtual void VideoHDR(Safe::Shared<const PreviewHDRVideo> image) = 0;
554 };
555 }
556}
STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Buffer::Bridge)
Container attachment (cover, fonts).
Definition attachment.hxx:79
virtual AudioPresentation AudioClock(std::uint64_t epoch)=0
Read current epoch's audio device cursor and latency.
virtual void Position(double position, std::uint64_t epoch)=0
Advance subtitle timing, including when audio is disabled.
virtual void Invalidate(std::uint64_t epoch, bool active_video)=0
Flush presentation and synchronously invalidate old deliveries.
virtual void Audio(Safe::Shared< const PreviewAudio > audio)=0
Queue a PCM block without blocking for playback.
virtual void Video(Safe::Shared< const PreviewVideo > image)=0
Present an owned image after its scheduled time.
virtual void Subtitle(Safe::Shared< const PreviewSubtitle > subtitle)=0
Present a cue; expire it at m_end on the supplied media clock.
virtual bool InvalidateAudio(std::uint64_t epoch)
Flush only audio while retaining video, cues and the delivery epoch.
Definition display.hxx:482
Display(const Display &)=delete
virtual ~Display() noexcept=default
Release this sink, not managed by player Close.
Display(Display &&)=delete
Display()=default
Construct a sink.
virtual bool Drained(std::uint64_t epoch)=0
Whether all queued audio and GUI deliveries have completed.
virtual void Pause(bool paused, std::uint64_t epoch)=0
Freeze or resume device audio and subtitle timers; invalidate an old pause timer.
Optional HDR presentation extension for a Display implementation.
Definition display.hxx:545
virtual ~HDRDisplay() noexcept=default
virtual void VideoHDR(Safe::Shared< const PreviewHDRVideo > image)=0
Present a PQ/HLG image without SDR tone mapping.
Multimedia module of the StormByte suite.
Media property value types.
Multimedia module of the StormByte suite.
AudioLayout
Interpretation of ordered decoded channel identities.
Definition display.hxx:183
@ Ambisonic
Ambisonic components, not ordinary speakers.
Definition display.hxx:187
@ Unspecified
Count only; speaker mapping is unknown.
Definition display.hxx:184
@ Custom
Explicit decoder channel order; identities may be unknown.
Definition display.hxx:186
@ Speakers
Known native speaker order.
Definition display.hxx:185
PreviewColorMode
Selects SDR presentation or HDR signal preservation for preview.
Definition display.hxx:78
@ HDR
Deliver PQ/HLG as full-range RGBA16LE through HDRDisplay.
Definition display.hxx:80
@ SDR
Tone-map PQ/HLG to BT.709 and deliver RGBA8 through Display.
Definition display.hxx:79
AudioSample
Decoded native-endian PCM representation, without conversion.
Definition display.hxx:170
@ Float32
IEEE 32-bit float.
Definition display.hxx:175
@ Signed16
Signed 16-bit.
Definition display.hxx:172
@ Signed32
Signed 32-bit.
Definition display.hxx:173
@ Float64
IEEE 64-bit float.
Definition display.hxx:176
@ Signed64
Signed 64-bit.
Definition display.hxx:174
@ Unsigned8
Unsigned 8-bit.
Definition display.hxx:171
SubtitleContent
FFmpeg decoded subtitle representation.
Definition display.hxx:255
@ Ass
ASS event with the decoder's style header.
Definition display.hxx:257
@ Bitmap
Image-based cues.
Definition codec.hxx:85
@ Text
Text-based cues, including binary-packed text formats.
Definition codec.hxx:84
Root namespace of the StormByte C++ suite.
STL namespace.
Device clock feedback in media seconds for the requested epoch.
Definition display.hxx:388
double m_position
Device playback cursor in media seconds.
Definition display.hxx:427
AudioPresentation(const AudioPresentation &other)=default
Copy clock feedback.
bool m_drained
Whether all submitted audio samples have been heard (not GUI drain).
Definition display.hxx:426
AudioPresentation(AudioPresentation &&other) noexcept=default
Move clock feedback.
AudioPresentation()=default
Construct unavailable clock feedback.
bool m_valid
Whether device feedback is available.
Definition display.hxx:425
~AudioPresentation() noexcept=default
Destroy clock feedback.
double m_latency
Unheard device latency in seconds, nonnegative.
Definition display.hxx:428
std::uint32_t m_rate
Actual decoded samples per second per channel.
Definition display.hxx:245
Safe::Vector< Safe::String > m_channels
Identities in decoded sample order; size is channel count.
Definition display.hxx:241
bool m_planar
Separate channel planes rather than packed samples.
Definition display.hxx:244
PreviewAudio(PreviewAudio &&other) noexcept=default
Move samples.
AudioLayout m_layout
Channel identity interpretation.
Definition display.hxx:243
AudioSample m_format
Actual decoded sample representation.
Definition display.hxx:242
double m_position
First sample presentation time in media seconds.
Definition display.hxx:248
std::uint64_t m_epoch
Delivery generation.
Definition display.hxx:247
std::uint32_t m_frames
Samples per channel.
Definition display.hxx:246
Safe::Vector< Safe::Binary > m_planes
Exact owned sample planes.
Definition display.hxx:240
PreviewAudio()=default
Construct an empty block.
PreviewAudio(const PreviewAudio &other)=default
Copy samples.
~PreviewAudio() noexcept=default
Release samples.
Owned RGBA16LE image retaining its HDR transfer and color primaries.
Definition display.hxx:140
bool m_has_mastering_display
Whether mastering-display metadata is present.
Definition display.hxx:162
double m_position
Presentation time in media seconds.
Definition display.hxx:152
Safe::Binary m_pixels
Tightly packed RGBA16LE signal values.
Definition display.hxx:148
double m_duration
Image duration in seconds.
Definition display.hxx:153
std::array< std::array< double, 2 >, 3 > m_display_primaries
Optional R/G/B mastering chromaticities.
Definition display.hxx:156
std::uint32_t m_max_frame_average_light_nits
Optional MaxFALL.
Definition display.hxx:161
double m_min_luminance_nits
Optional mastering-display minimum.
Definition display.hxx:158
PreviewHDRVideo(PreviewHDRVideo &&other) noexcept=default
double m_max_luminance_nits
Optional mastering-display maximum.
Definition display.hxx:159
PreviewHDRVideo(const PreviewHDRVideo &other)=default
Property::Transfer m_transfer
PQ or HLG signal transfer.
Definition display.hxx:155
std::array< double, 2 > m_white_point
Optional mastering white point.
Definition display.hxx:157
std::uint32_t m_width
Pixel width.
Definition display.hxx:149
Property::Primaries m_primaries
Signal chromaticity primaries.
Definition display.hxx:154
std::uint32_t m_max_content_light_nits
Optional MaxCLL.
Definition display.hxx:160
std::uint64_t m_epoch
Delivery generation.
Definition display.hxx:151
std::uint32_t m_height
Pixel height.
Definition display.hxx:150
bool m_has_content_light
Whether content-light metadata is present.
Definition display.hxx:163
PreviewSubtitle()=default
Construct an empty cue.
Safe::String m_style_header
ASS/SSA decoder header, if supplied.
Definition display.hxx:370
double m_start
Inclusive start in media seconds.
Definition display.hxx:376
int m_canvas_width
Subtitle canvas width; zero if unspecified.
Definition display.hxx:372
std::uint64_t m_id
Cue identity within the epoch.
Definition display.hxx:375
~PreviewSubtitle() noexcept=default
Release cue storage.
int m_canvas_height
Subtitle canvas height; zero if unspecified.
Definition display.hxx:373
Safe::Vector< SubtitleRegion > m_regions
Decoded rectangles; empty means clear.
Definition display.hxx:369
PreviewSubtitle(PreviewSubtitle &&other) noexcept=default
Move a cue.
PreviewSubtitle(const PreviewSubtitle &other)=default
Copy a cue.
std::uint64_t m_epoch
Delivery generation.
Definition display.hxx:374
double m_end
Exclusive end; infinity means until a matching clear or stream drain.
Definition display.hxx:377
Safe::Vector< Safe::Shared< const Attachment > > m_fonts
Shared embedded TTF/OTF resources for styled rendering.
Definition display.hxx:371
~PreviewVideo() noexcept=default
Release image storage.
PreviewVideo(PreviewVideo &&other) noexcept=default
Move an image.
double m_position
Presentation time in media seconds.
Definition display.hxx:128
Safe::Binary m_pixels
Row-major RGBA8 bytes; stride is m_width * 4.
Definition display.hxx:124
double m_duration
Image duration in seconds.
Definition display.hxx:129
PreviewVideo(const PreviewVideo &other)=default
Copy an image.
std::uint32_t m_height
Pixel height.
Definition display.hxx:126
std::uint32_t m_width
Pixel width.
Definition display.hxx:125
std::uint64_t m_epoch
Delivery generation.
Definition display.hxx:127
PreviewVideo()=default
Construct an empty image.
One decoded subtitle rectangle.
Definition display.hxx:265
Safe::String m_text
UTF-8 text or an ASS event.
Definition display.hxx:303
SubtitleRegion(const SubtitleRegion &other)=default
Copy a rectangle.
SubtitleContent m_content
Interpretation of this rectangle.
Definition display.hxx:302
SubtitleRegion()=default
Construct an empty rectangle.
int m_y
Canvas top.
Definition display.hxx:306
int m_width
Bitmap width.
Definition display.hxx:307
int m_height
Bitmap height.
Definition display.hxx:308
SubtitleRegion(SubtitleRegion &&other) noexcept=default
Move a rectangle.
~SubtitleRegion() noexcept=default
Release rectangle storage.
int m_x
Canvas left.
Definition display.hxx:305
Safe::Binary m_pixels
RGBA8 bitmap, tightly packed.
Definition display.hxx:304
#define STORMBYTE_MULTIMEDIA_PUBLIC
Definition visibility.h:61