Rerun C++ SDK
Loading...
Searching...
No Matches
video_frame_reference.hpp
1// DO NOT EDIT! This file was auto-generated by crates/build/re_types_builder/src/codegen/cpp/mod.rs
2// Based on "crates/store/re_types/definitions/rerun/archetypes/video_frame_reference.fbs".
3
4#pragma once
5
6#include "../collection.hpp"
7#include "../component_batch.hpp"
8#include "../component_column.hpp"
9#include "../components/draw_order.hpp"
10#include "../components/entity_path.hpp"
11#include "../components/opacity.hpp"
12#include "../components/video_timestamp.hpp"
13#include "../result.hpp"
14
15#include <cstdint>
16#include <optional>
17#include <utility>
18#include <vector>
19
20namespace rerun::archetypes {
21 /// **Archetype**: References a single video frame.
22 ///
23 /// Used to display individual video frames from a `archetypes::AssetVideo`.
24 /// To show an entire video, a video frame reference for each frame of the video should be logged.
25 ///
26 /// See <https://rerun.io/docs/reference/video> for details of what is and isn't supported.
27 ///
28 /// TODO(#10422): `archetypes::VideoFrameReference` does not yet work with `archetypes::VideoStream`.
29 ///
30 /// ## Examples
31 ///
32 /// ### Video with automatically determined frames
33 /// ![image](https://static.rerun.io/video_manual_frames/320a44e1e06b8b3a3161ecbbeae3e04d1ccb9589/full.png)
34 ///
35 /// ```cpp
36 /// #include <rerun.hpp>
37 ///
38 /// #include <iostream>
39 ///
40 /// using namespace std::chrono_literals;
41 ///
42 /// int main(int argc, char* argv[]) {
43 /// if (argc <2) {
44 /// // TODO(#7354): Only mp4 is supported for now.
45 /// std::cerr <<"Usage: " <<argv[0] <<" <path_to_video.[mp4]>" <<std::endl;
46 /// return 1;
47 /// }
48 ///
49 /// const auto path = argv[1];
50 ///
51 /// const auto rec = rerun::RecordingStream("rerun_example_asset_video_auto_frames");
52 /// rec.spawn().exit_on_failure();
53 ///
54 /// // Log video asset which is referred to by frame references.
55 /// auto video_asset = rerun::AssetVideo::from_file(path).value_or_throw();
56 /// rec.log_static("video", video_asset);
57 ///
58 /// // Send automatically determined video frame timestamps.
59 /// std::vector<std::chrono::nanoseconds> frame_timestamps_ns =
60 /// video_asset.read_frame_timestamps_nanos().value_or_throw();
61 /// // Note timeline values don't have to be the same as the video timestamps.
62 /// auto time_column =
63 /// rerun::TimeColumn::from_durations("video_time", rerun::borrow(frame_timestamps_ns));
64 ///
65 /// std::vector<rerun::components::VideoTimestamp> video_timestamps(frame_timestamps_ns.size());
66 /// for (size_t i = 0; i <frame_timestamps_ns.size(); i++) {
67 /// video_timestamps[i] = rerun::components::VideoTimestamp(frame_timestamps_ns[i]);
68 /// }
69 ///
70 /// rec.send_columns(
71 /// "video",
72 /// time_column,
73 /// rerun::VideoFrameReference().with_many_timestamp(rerun::borrow(video_timestamps)).columns()
74 /// );
75 /// }
76 /// ```
77 ///
78 /// ### Demonstrates manual use of video frame references
79 /// ![image](https://static.rerun.io/video_manual_frames/9f41c00f84a98cc3f26875fba7c1d2fa2bad7151/full.png)
80 ///
81 /// ```cpp
82 /// #include <rerun.hpp>
83 ///
84 /// #include <iostream>
85 ///
86 /// using namespace std::chrono_literals;
87 ///
88 /// int main(int argc, char* argv[]) {
89 /// if (argc <2) {
90 /// // TODO(#7354): Only mp4 is supported for now.
91 /// std::cerr <<"Usage: " <<argv[0] <<" <path_to_video.[mp4]>" <<std::endl;
92 /// return 1;
93 /// }
94 ///
95 /// const auto path = argv[1];
96 ///
97 /// const auto rec = rerun::RecordingStream("rerun_example_asset_video_manual_frames");
98 /// rec.spawn().exit_on_failure();
99 ///
100 /// // Log video asset which is referred to by frame references.
101 /// rec.log_static("video_asset", rerun::AssetVideo::from_file(path).value_or_throw());
102 ///
103 /// // Create two entities, showing the same video frozen at different times.
104 /// rec.log("frame_1s", rerun::VideoFrameReference(1.0s).with_video_reference("video_asset"));
105 /// rec.log("frame_2s", rerun::VideoFrameReference(2.0s).with_video_reference("video_asset"));
106 ///
107 /// // TODO(#5520): log blueprint once supported
108 /// }
109 /// ```
111 /// References the closest video frame to this timestamp.
112 ///
113 /// Note that this uses the closest video frame instead of the latest at this timestamp
114 /// in order to be more forgiving of rounding errors for inprecise timestamp types.
115 ///
116 /// Timestamps are relative to the start of the video, i.e. a timestamp of 0 always corresponds to the first frame.
117 /// This is oftentimes equivalent to presentation timestamps (known as PTS), but in the presence of B-frames
118 /// (bidirectionally predicted frames) there may be an offset on the first presentation timestamp in the video.
119 std::optional<ComponentBatch> timestamp;
120
121 /// Optional reference to an entity with a `archetypes::AssetVideo`.
122 ///
123 /// If none is specified, the video is assumed to be at the same entity.
124 /// Note that blueprint overrides on the referenced video will be ignored regardless,
125 /// as this is always interpreted as a reference to the data store.
126 ///
127 /// For a series of video frame references, it is recommended to specify this path only once
128 /// at the beginning of the series and then rely on latest-at query semantics to
129 /// keep the video reference active.
130 std::optional<ComponentBatch> video_reference;
131
132 /// Opacity of the video, useful for layering several media.
133 ///
134 /// Defaults to 1.0 (fully opaque).
135 std::optional<ComponentBatch> opacity;
136
137 /// An optional floating point value that specifies the 2D drawing order.
138 ///
139 /// Objects with higher values are drawn on top of those with lower values.
140 /// Defaults to `-15.0`.
141 std::optional<ComponentBatch> draw_order;
142
143 public:
144 /// The name of the archetype as used in `ComponentDescriptor`s.
145 static constexpr const char ArchetypeName[] = "rerun.archetypes.VideoFrameReference";
146
147 /// `ComponentDescriptor` for the `timestamp` field.
149 ArchetypeName, "VideoFrameReference:timestamp",
151 );
152 /// `ComponentDescriptor` for the `video_reference` field.
154 ArchetypeName, "VideoFrameReference:video_reference",
156 );
157 /// `ComponentDescriptor` for the `opacity` field.
159 ArchetypeName, "VideoFrameReference:opacity",
161 );
162 /// `ComponentDescriptor` for the `draw_order` field.
164 ArchetypeName, "VideoFrameReference:draw_order",
166 );
167
168 public:
169 VideoFrameReference() = default;
170 VideoFrameReference(VideoFrameReference&& other) = default;
171 VideoFrameReference(const VideoFrameReference& other) = default;
172 VideoFrameReference& operator=(const VideoFrameReference& other) = default;
173 VideoFrameReference& operator=(VideoFrameReference&& other) = default;
174
176 : timestamp(ComponentBatch::from_loggable(std::move(_timestamp), Descriptor_timestamp)
177 .value_or_throw()) {}
178
179 /// Update only some specific fields of a `VideoFrameReference`.
181 return VideoFrameReference();
182 }
183
184 /// Clear all the fields of a `VideoFrameReference`.
186
187 /// References the closest video frame to this timestamp.
188 ///
189 /// Note that this uses the closest video frame instead of the latest at this timestamp
190 /// in order to be more forgiving of rounding errors for inprecise timestamp types.
191 ///
192 /// Timestamps are relative to the start of the video, i.e. a timestamp of 0 always corresponds to the first frame.
193 /// This is oftentimes equivalent to presentation timestamps (known as PTS), but in the presence of B-frames
194 /// (bidirectionally predicted frames) there may be an offset on the first presentation timestamp in the video.
196 timestamp =
197 ComponentBatch::from_loggable(_timestamp, Descriptor_timestamp).value_or_throw();
198 return std::move(*this);
199 }
200
201 /// This method makes it possible to pack multiple `timestamp` in a single component batch.
202 ///
203 /// This only makes sense when used in conjunction with `columns`. `with_timestamp` should
204 /// be used when logging a single row's worth of data.
207 ) && {
208 timestamp =
209 ComponentBatch::from_loggable(_timestamp, Descriptor_timestamp).value_or_throw();
210 return std::move(*this);
211 }
212
213 /// Optional reference to an entity with a `archetypes::AssetVideo`.
214 ///
215 /// If none is specified, the video is assumed to be at the same entity.
216 /// Note that blueprint overrides on the referenced video will be ignored regardless,
217 /// as this is always interpreted as a reference to the data store.
218 ///
219 /// For a series of video frame references, it is recommended to specify this path only once
220 /// at the beginning of the series and then rely on latest-at query semantics to
221 /// keep the video reference active.
223 const rerun::components::EntityPath& _video_reference
224 ) && {
227 .value_or_throw();
228 return std::move(*this);
229 }
230
231 /// This method makes it possible to pack multiple `video_reference` in a single component batch.
232 ///
233 /// This only makes sense when used in conjunction with `columns`. `with_video_reference` should
234 /// be used when logging a single row's worth of data.
236 const Collection<rerun::components::EntityPath>& _video_reference
237 ) && {
240 .value_or_throw();
241 return std::move(*this);
242 }
243
244 /// Opacity of the video, useful for layering several media.
245 ///
246 /// Defaults to 1.0 (fully opaque).
248 opacity = ComponentBatch::from_loggable(_opacity, Descriptor_opacity).value_or_throw();
249 return std::move(*this);
250 }
251
252 /// This method makes it possible to pack multiple `opacity` in a single component batch.
253 ///
254 /// This only makes sense when used in conjunction with `columns`. `with_opacity` should
255 /// be used when logging a single row's worth of data.
257 ) && {
258 opacity = ComponentBatch::from_loggable(_opacity, Descriptor_opacity).value_or_throw();
259 return std::move(*this);
260 }
261
262 /// An optional floating point value that specifies the 2D drawing order.
263 ///
264 /// Objects with higher values are drawn on top of those with lower values.
265 /// Defaults to `-15.0`.
267 draw_order =
268 ComponentBatch::from_loggable(_draw_order, Descriptor_draw_order).value_or_throw();
269 return std::move(*this);
270 }
271
272 /// This method makes it possible to pack multiple `draw_order` in a single component batch.
273 ///
274 /// This only makes sense when used in conjunction with `columns`. `with_draw_order` should
275 /// be used when logging a single row's worth of data.
278 ) && {
279 draw_order =
280 ComponentBatch::from_loggable(_draw_order, Descriptor_draw_order).value_or_throw();
281 return std::move(*this);
282 }
283
284 /// Partitions the component data into multiple sub-batches.
285 ///
286 /// Specifically, this transforms the existing `ComponentBatch` data into `ComponentColumn`s
287 /// instead, via `ComponentBatch::partitioned`.
288 ///
289 /// This makes it possible to use `RecordingStream::send_columns` to send columnar data directly into Rerun.
290 ///
291 /// The specified `lengths` must sum to the total length of the component batch.
293
294 /// Partitions the component data into unit-length sub-batches.
295 ///
296 /// This is semantically similar to calling `columns` with `std::vector<uint32_t>(n, 1)`,
297 /// where `n` is automatically guessed.
299 };
300
301} // namespace rerun::archetypes
302
303namespace rerun {
304 /// \private
305 template <typename T>
306 struct AsComponents;
307
308 /// \private
309 template <>
310 struct AsComponents<archetypes::VideoFrameReference> {
311 /// Serialize all set component batches.
312 static Result<Collection<ComponentBatch>> as_batches(
313 const archetypes::VideoFrameReference& archetype
314 );
315 };
316} // namespace rerun
Generic collection of elements that are roughly contiguous in memory.
Definition collection.hpp:49
A class for representing either a usable value, or an error.
Definition result.hpp:14
All built-in archetypes. See Types in the Rerun manual.
Definition rerun.hpp:76
All Rerun C++ types and functions are in the rerun namespace or one of its nested namespaces.
Definition rerun.hpp:23
Arrow-encoded data of a single batch of components together with a component descriptor.
Definition component_batch.hpp:28
static Result< ComponentBatch > from_loggable(const rerun::Collection< T > &components, const ComponentDescriptor &descriptor)
Creates a new component batch from a collection of component instances.
Definition component_batch.hpp:46
A ComponentDescriptor fully describes the semantics of a column of data.
Definition component_descriptor.hpp:16
The Loggable trait is used by all built-in implementation of rerun::AsComponents to serialize a colle...
Definition loggable.hpp:11
Archetype: References a single video frame.
Definition video_frame_reference.hpp:110
Collection< ComponentColumn > columns()
Partitions the component data into unit-length sub-batches.
static constexpr auto Descriptor_draw_order
ComponentDescriptor for the draw_order field.
Definition video_frame_reference.hpp:163
VideoFrameReference with_many_draw_order(const Collection< rerun::components::DrawOrder > &_draw_order) &&
This method makes it possible to pack multiple draw_order in a single component batch.
Definition video_frame_reference.hpp:276
VideoFrameReference with_timestamp(const rerun::components::VideoTimestamp &_timestamp) &&
References the closest video frame to this timestamp.
Definition video_frame_reference.hpp:195
std::optional< ComponentBatch > draw_order
An optional floating point value that specifies the 2D drawing order.
Definition video_frame_reference.hpp:141
VideoFrameReference with_many_timestamp(const Collection< rerun::components::VideoTimestamp > &_timestamp) &&
This method makes it possible to pack multiple timestamp in a single component batch.
Definition video_frame_reference.hpp:205
std::optional< ComponentBatch > timestamp
References the closest video frame to this timestamp.
Definition video_frame_reference.hpp:119
static constexpr const char ArchetypeName[]
The name of the archetype as used in ComponentDescriptors.
Definition video_frame_reference.hpp:145
VideoFrameReference with_many_opacity(const Collection< rerun::components::Opacity > &_opacity) &&
This method makes it possible to pack multiple opacity in a single component batch.
Definition video_frame_reference.hpp:256
VideoFrameReference with_opacity(const rerun::components::Opacity &_opacity) &&
Opacity of the video, useful for layering several media.
Definition video_frame_reference.hpp:247
static constexpr auto Descriptor_video_reference
ComponentDescriptor for the video_reference field.
Definition video_frame_reference.hpp:153
std::optional< ComponentBatch > opacity
Opacity of the video, useful for layering several media.
Definition video_frame_reference.hpp:135
static constexpr auto Descriptor_timestamp
ComponentDescriptor for the timestamp field.
Definition video_frame_reference.hpp:148
Collection< ComponentColumn > columns(const Collection< uint32_t > &lengths_)
Partitions the component data into multiple sub-batches.
static constexpr auto Descriptor_opacity
ComponentDescriptor for the opacity field.
Definition video_frame_reference.hpp:158
VideoFrameReference with_video_reference(const rerun::components::EntityPath &_video_reference) &&
Optional reference to an entity with a archetypes::AssetVideo.
Definition video_frame_reference.hpp:222
std::optional< ComponentBatch > video_reference
Optional reference to an entity with a archetypes::AssetVideo.
Definition video_frame_reference.hpp:130
VideoFrameReference with_many_video_reference(const Collection< rerun::components::EntityPath > &_video_reference) &&
This method makes it possible to pack multiple video_reference in a single component batch.
Definition video_frame_reference.hpp:235
static VideoFrameReference update_fields()
Update only some specific fields of a VideoFrameReference.
Definition video_frame_reference.hpp:180
static VideoFrameReference clear_fields()
Clear all the fields of a VideoFrameReference.
VideoFrameReference with_draw_order(const rerun::components::DrawOrder &_draw_order) &&
An optional floating point value that specifies the 2D drawing order.
Definition video_frame_reference.hpp:266
Component: Draw order of 2D elements.
Definition draw_order.hpp:19
Component: A path to an entity, usually to reference some data that is part of the target entity.
Definition entity_path.hpp:16
Component: Degree of transparency ranging from 0.0 (fully transparent) to 1.0 (fully opaque).
Definition opacity.hpp:17
Component: Timestamp inside a archetypes::AssetVideo.
Definition video_timestamp.hpp:15