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/video_timestamp.hpp"
12#include "../indicator_component.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 /// ## Examples
29 ///
30 /// ### Video with automatically determined frames
31 /// ![image](https://static.rerun.io/video_manual_frames/320a44e1e06b8b3a3161ecbbeae3e04d1ccb9589/full.png)
32 ///
33 /// ```cpp
34 /// #include <rerun.hpp>
35 ///
36 /// #include <iostream>
37 ///
38 /// using namespace std::chrono_literals;
39 ///
40 /// int main(int argc, char* argv[]) {
41 /// if (argc <2) {
42 /// // TODO(#7354): Only mp4 is supported for now.
43 /// std::cerr <<"Usage: " <<argv[0] <<" <path_to_video.[mp4]>" <<std::endl;
44 /// return 1;
45 /// }
46 ///
47 /// const auto path = argv[1];
48 ///
49 /// const auto rec = rerun::RecordingStream("rerun_example_asset_video_auto_frames");
50 /// rec.spawn().exit_on_failure();
51 ///
52 /// // Log video asset which is referred to by frame references.
53 /// auto video_asset = rerun::AssetVideo::from_file(path).value_or_throw();
54 /// rec.log_static("video", video_asset);
55 ///
56 /// // Send automatically determined video frame timestamps.
57 /// std::vector<std::chrono::nanoseconds> frame_timestamps_ns =
58 /// video_asset.read_frame_timestamps_nanos().value_or_throw();
59 /// // Note timeline values don't have to be the same as the video timestamps.
60 /// auto time_column =
61 /// rerun::TimeColumn::from_durations("video_time", rerun::borrow(frame_timestamps_ns));
62 ///
63 /// std::vector<rerun::components::VideoTimestamp> video_timestamps(frame_timestamps_ns.size());
64 /// for (size_t i = 0; i <frame_timestamps_ns.size(); i++) {
65 /// video_timestamps[i] = rerun::components::VideoTimestamp(frame_timestamps_ns[i]);
66 /// }
67 /// auto video_frame_reference_indicators =
68 /// rerun::ComponentColumn::from_indicators<rerun::VideoFrameReference>(
69 /// static_cast<uint32_t>(video_timestamps.size())
70 /// );
71 ///
72 /// rec.send_columns(
73 /// "video",
74 /// time_column,
75 /// rerun::VideoFrameReference().with_many_timestamp(rerun::borrow(video_timestamps)).columns()
76 /// );
77 /// }
78 /// ```
79 ///
80 /// ### Demonstrates manual use of video frame references
81 /// ![image](https://static.rerun.io/video_manual_frames/9f41c00f84a98cc3f26875fba7c1d2fa2bad7151/full.png)
82 ///
83 /// ```cpp
84 /// #include <rerun.hpp>
85 ///
86 /// #include <iostream>
87 ///
88 /// using namespace std::chrono_literals;
89 ///
90 /// int main(int argc, char* argv[]) {
91 /// if (argc <2) {
92 /// // TODO(#7354): Only mp4 is supported for now.
93 /// std::cerr <<"Usage: " <<argv[0] <<" <path_to_video.[mp4]>" <<std::endl;
94 /// return 1;
95 /// }
96 ///
97 /// const auto path = argv[1];
98 ///
99 /// const auto rec = rerun::RecordingStream("rerun_example_asset_video_manual_frames");
100 /// rec.spawn().exit_on_failure();
101 ///
102 /// // Log video asset which is referred to by frame references.
103 /// rec.log_static("video_asset", rerun::AssetVideo::from_file(path).value_or_throw());
104 ///
105 /// // Create two entities, showing the same video frozen at different times.
106 /// rec.log("frame_1s", rerun::VideoFrameReference(1.0s).with_video_reference("video_asset"));
107 /// rec.log("frame_2s", rerun::VideoFrameReference(2.0s).with_video_reference("video_asset"));
108 ///
109 /// // TODO(#5520): log blueprint once supported
110 /// }
111 /// ```
113 /// References the closest video frame to this timestamp.
114 ///
115 /// Note that this uses the closest video frame instead of the latest at this timestamp
116 /// in order to be more forgiving of rounding errors for inprecise timestamp types.
117 ///
118 /// Timestamps are relative to the start of the video, i.e. a timestamp of 0 always corresponds to the first frame.
119 /// This is oftentimes equivalent to presentation timestamps (known as PTS), but in the presence of B-frames
120 /// (bidirectionally predicted frames) there may be an offset on the first presentation timestamp in the video.
121 std::optional<ComponentBatch> timestamp;
122
123 /// Optional reference to an entity with a `archetypes::AssetVideo`.
124 ///
125 /// If none is specified, the video is assumed to be at the same entity.
126 /// Note that blueprint overrides on the referenced video will be ignored regardless,
127 /// as this is always interpreted as a reference to the data store.
128 ///
129 /// For a series of video frame references, it is recommended to specify this path only once
130 /// at the beginning of the series and then rely on latest-at query semantics to
131 /// keep the video reference active.
132 std::optional<ComponentBatch> video_reference;
133
134 /// An optional floating point value that specifies the 2D drawing order.
135 ///
136 /// Objects with higher values are drawn on top of those with lower values.
137 /// Defaults to `-15.0`.
138 std::optional<ComponentBatch> draw_order;
139
140 public:
141 static constexpr const char IndicatorComponentName[] =
142 "rerun.components.VideoFrameReferenceIndicator";
143
144 /// Indicator component, used to identify the archetype when converting to a list of components.
146 /// The name of the archetype as used in `ComponentDescriptor`s.
147 static constexpr const char ArchetypeName[] = "rerun.archetypes.VideoFrameReference";
148
149 /// `ComponentDescriptor` for the `timestamp` field.
151 ArchetypeName, "timestamp",
153 );
154 /// `ComponentDescriptor` for the `video_reference` field.
156 ArchetypeName, "video_reference",
158 );
159 /// `ComponentDescriptor` for the `draw_order` field.
161 ArchetypeName, "draw_order",
163 );
164
165 public:
166 VideoFrameReference() = default;
167 VideoFrameReference(VideoFrameReference&& other) = default;
168 VideoFrameReference(const VideoFrameReference& other) = default;
169 VideoFrameReference& operator=(const VideoFrameReference& other) = default;
170 VideoFrameReference& operator=(VideoFrameReference&& other) = default;
171
173 : timestamp(ComponentBatch::from_loggable(std::move(_timestamp), Descriptor_timestamp)
174 .value_or_throw()) {}
175
176 /// Update only some specific fields of a `VideoFrameReference`.
178 return VideoFrameReference();
179 }
180
181 /// Clear all the fields of a `VideoFrameReference`.
183
184 /// References the closest video frame to this timestamp.
185 ///
186 /// Note that this uses the closest video frame instead of the latest at this timestamp
187 /// in order to be more forgiving of rounding errors for inprecise timestamp types.
188 ///
189 /// Timestamps are relative to the start of the video, i.e. a timestamp of 0 always corresponds to the first frame.
190 /// This is oftentimes equivalent to presentation timestamps (known as PTS), but in the presence of B-frames
191 /// (bidirectionally predicted frames) there may be an offset on the first presentation timestamp in the video.
193 timestamp =
194 ComponentBatch::from_loggable(_timestamp, Descriptor_timestamp).value_or_throw();
195 return std::move(*this);
196 }
197
198 /// This method makes it possible to pack multiple `timestamp` in a single component batch.
199 ///
200 /// This only makes sense when used in conjunction with `columns`. `with_timestamp` should
201 /// be used when logging a single row's worth of data.
204 ) && {
205 timestamp =
206 ComponentBatch::from_loggable(_timestamp, Descriptor_timestamp).value_or_throw();
207 return std::move(*this);
208 }
209
210 /// Optional reference to an entity with a `archetypes::AssetVideo`.
211 ///
212 /// If none is specified, the video is assumed to be at the same entity.
213 /// Note that blueprint overrides on the referenced video will be ignored regardless,
214 /// as this is always interpreted as a reference to the data store.
215 ///
216 /// For a series of video frame references, it is recommended to specify this path only once
217 /// at the beginning of the series and then rely on latest-at query semantics to
218 /// keep the video reference active.
220 const rerun::components::EntityPath& _video_reference
221 ) && {
224 .value_or_throw();
225 return std::move(*this);
226 }
227
228 /// This method makes it possible to pack multiple `video_reference` in a single component batch.
229 ///
230 /// This only makes sense when used in conjunction with `columns`. `with_video_reference` should
231 /// be used when logging a single row's worth of data.
233 const Collection<rerun::components::EntityPath>& _video_reference
234 ) && {
237 .value_or_throw();
238 return std::move(*this);
239 }
240
241 /// An optional floating point value that specifies the 2D drawing order.
242 ///
243 /// Objects with higher values are drawn on top of those with lower values.
244 /// Defaults to `-15.0`.
246 draw_order =
247 ComponentBatch::from_loggable(_draw_order, Descriptor_draw_order).value_or_throw();
248 return std::move(*this);
249 }
250
251 /// This method makes it possible to pack multiple `draw_order` in a single component batch.
252 ///
253 /// This only makes sense when used in conjunction with `columns`. `with_draw_order` should
254 /// be used when logging a single row's worth of data.
257 ) && {
258 draw_order =
259 ComponentBatch::from_loggable(_draw_order, Descriptor_draw_order).value_or_throw();
260 return std::move(*this);
261 }
262
263 /// Partitions the component data into multiple sub-batches.
264 ///
265 /// Specifically, this transforms the existing `ComponentBatch` data into `ComponentColumn`s
266 /// instead, via `ComponentBatch::partitioned`.
267 ///
268 /// This makes it possible to use `RecordingStream::send_columns` to send columnar data directly into Rerun.
269 ///
270 /// The specified `lengths` must sum to the total length of the component batch.
272
273 /// Partitions the component data into unit-length sub-batches.
274 ///
275 /// This is semantically similar to calling `columns` with `std::vector<uint32_t>(n, 1)`,
276 /// where `n` is automatically guessed.
278 };
279
280} // namespace rerun::archetypes
281
282namespace rerun {
283 /// \private
284 template <typename T>
285 struct AsComponents;
286
287 /// \private
288 template <>
289 struct AsComponents<archetypes::VideoFrameReference> {
290 /// Serialize all set component batches.
291 static Result<Collection<ComponentBatch>> as_batches(
292 const archetypes::VideoFrameReference& archetype
293 );
294 };
295} // 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:14
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:112
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:160
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:255
VideoFrameReference with_timestamp(const rerun::components::VideoTimestamp &_timestamp) &&
References the closest video frame to this timestamp.
Definition video_frame_reference.hpp:192
std::optional< ComponentBatch > draw_order
An optional floating point value that specifies the 2D drawing order.
Definition video_frame_reference.hpp:138
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:202
std::optional< ComponentBatch > timestamp
References the closest video frame to this timestamp.
Definition video_frame_reference.hpp:121
static constexpr const char ArchetypeName[]
The name of the archetype as used in ComponentDescriptors.
Definition video_frame_reference.hpp:147
static constexpr auto Descriptor_video_reference
ComponentDescriptor for the video_reference field.
Definition video_frame_reference.hpp:155
static constexpr auto Descriptor_timestamp
ComponentDescriptor for the timestamp field.
Definition video_frame_reference.hpp:150
Collection< ComponentColumn > columns(const Collection< uint32_t > &lengths_)
Partitions the component data into multiple sub-batches.
VideoFrameReference with_video_reference(const rerun::components::EntityPath &_video_reference) &&
Optional reference to an entity with a archetypes::AssetVideo.
Definition video_frame_reference.hpp:219
std::optional< ComponentBatch > video_reference
Optional reference to an entity with a archetypes::AssetVideo.
Definition video_frame_reference.hpp:132
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:232
static VideoFrameReference update_fields()
Update only some specific fields of a VideoFrameReference.
Definition video_frame_reference.hpp:177
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:245
Component: Draw order of 2D elements.
Definition draw_order.hpp:20
Component: A path to an entity, usually to reference some data that is part of the target entity.
Definition entity_path.hpp:17
Indicator component used by archetypes when converting them to component lists.
Definition indicator_component.hpp:32
Component: Timestamp inside a archetypes::AssetVideo.
Definition video_timestamp.hpp:16