C++ Example setup, examples for point3d/arrow3d/disconnectedspace (#2908

)

### What

Adds C++ example build setup and examples for:

* Point3D  #2789
* Arrow3D #2785
* DisconnectedSpace #2791

as before Point2D example is blocked on rects for the moment.

Generating a bunch more methods now for better usability. Still lacking
user extensions though, in particular Point3D construction is poor right
now

Examples can be built in bulk with `
./tests/cpp/build_all_doc_examples.sh`
Then run with `./build/tests/cpp/doc_example_point3d_EXAMPLE_NAME`
They all connect to localhost on default port for now.


Point3D Simple:
<img width="1336" alt="image"
src="https://github.com/rerun-io/rerun/assets/1220815/61ca8dba-690f-4bcf-96d2-25cb010881fb">

Point3D Random:
<img width="1341" alt="image"
src="https://github.com/rerun-io/rerun/assets/1220815/48fa902d-7858-4580-b64b-69815dab47e3">

Arrow3D:
<img width="1360" alt="image"
src="https://github.com/rerun-io/rerun/assets/1220815/131d0efa-af94-418a-b08f-653c1d9eafb0">

Disconnected Space:
<img width="1339" alt="image"
src="https://github.com/rerun-io/rerun/assets/1220815/5da1bb64-984a-4ff5-903a-1ea060dd296a">

Dependent on #2906 

### Checklist
* [x] I have read and agree to [Contributor
Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and
the [Code of
Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md)
* [x] I've included a screenshot or gif (if applicable)
* [x] I have tested [demo.rerun.io](https://demo.rerun.io/pr/2908) (if
applicable)

- [PR Build Summary](https://build.rerun.io/pr/2908)
- [Docs
preview](https://rerun.io/preview/pr%3Aandreas%2Fcpp%2Fexamplesv2/docs)
- [Examples
preview](https://rerun.io/preview/pr%3Aandreas%2Fcpp%2Fexamplesv2/examples)

.github/workflows/reusable_checks.yml

@@ -345,3 +345,7 @@ jobs:
       - name: Build and run rerun_cpp tests
         shell: bash
         run: ./rerun_cpp/build_and_run_tests.sh
+
+      - name: Build code examples
+        shell: bash
+        run: ./tests/cpp/build_all_doc_examples.sh

crates/re_types/definitions/rerun/archetypes/arrows3d.fbs

@@ -21,6 +21,12 @@ namespace rerun.archetypes;
 /// \rs ```ignore
 /// \rs \include:../../../../../docs/code-examples/arrow3d_simple_v2.rs
 /// \rs ```
+///
+/// \cpp ## Example
+/// \cpp
+/// \cpp ```
+/// \cpp \include:../../../../../docs/code-examples/arrow3d_simple_v2.cpp
+/// \cpp ```
 table Arrows3D (
   "attr.rust.derive": "PartialEq",
   order: 100

crates/re_types/definitions/rerun/archetypes/disconnected_space.fbs

@@ -24,6 +24,12 @@ namespace rerun.archetypes;
 /// \rs ```ignore
 /// \rs \include:../../../../../docs/code-examples/disconnected_space_v2.rs
 /// \rs ```
+///
+/// \cpp ## Example
+/// \cpp
+/// \cpp ```
+/// \cpp \include:../../../../../docs/code-examples/disconnected_space_v2.cpp
+/// \cpp ```
 table DisconnectedSpace (
   "attr.rust.derive": "Copy, PartialEq, Eq",
   order: 100

crates/re_types/definitions/rerun/archetypes/points3d.fbs

@@ -21,6 +21,12 @@ namespace rerun.archetypes;
 /// \rs ```ignore
 /// \rs \include:../../../../../docs/code-examples/point3d_simple_v2.rs
 /// \rs ```
+///
+/// \cpp ## Example
+/// \cpp
+/// \cpp ```
+/// \cpp \include:../../../../../docs/code-examples/point3d_simple_v2.cpp
+/// \cpp ```
 table Points3D (
   "attr.rust.derive": "PartialEq",
   order: 100

crates/re_types/definitions/rerun/components/point3d.fbs

@@ -17,5 +17,5 @@ struct Point3D (
   "attr.rust.derive": "Default, Copy, PartialEq, PartialOrd",
   order: 100
 ) {
-  xy: rerun.datatypes.Vec3D (order: 100);
+  xyz: rerun.datatypes.Vec3D (order: 100);
 }

crates/re_types_builder/src/codegen/cpp/mod.rs

@@ -252,7 +252,7 @@ impl QuotedObject {
             ObjectKind::Datatype | ObjectKind::Component => {
                 if obj.fields.len() == 1 {
                     // Single-field struct - it is a newtype wrapper.
-                    // Create a implicit constructor from its own field-type - do so by copy, and if meaningful by rvalue reference.
+                    // Create a implicit constructor and assignment from its own field-type.
                     let obj_field = &obj.fields[0];
                     if let Type::Array { .. } = &obj_field.typ {
                         // TODO(emilk): implicit constructor for arrays
@@ -261,15 +261,30 @@ impl QuotedObject {
                         // If it was a temporary it gets moved into the value and then moved again into the field.
                         // If it was a lvalue it gets copied into the value and then moved into the field.
                         let field_ident = format_ident!("{}", obj_field.name);
+                        let param_ident = format_ident!("_{}", obj_field.name);
                         let parameter_declaration =
-                            quote_variable(&mut hpp_includes, obj_field, &field_ident);
+                            quote_variable(&mut hpp_includes, obj_field, &param_ident);
                         hpp_includes.system.insert("utility".to_owned()); // std::move
                         methods.push(Method {
                                 declaration: MethodDeclaration::constructor(quote! {
-                                    #type_ident(#parameter_declaration) : #field_ident(std::move(#field_ident))
+                                    #type_ident(#parameter_declaration) : #field_ident(std::move(#param_ident))
                                 }),
                                 ..Method::default()
                             });
+                        methods.push(Method {
+                            declaration: MethodDeclaration {
+                                is_static: false,
+                                return_type: quote!(#type_ident&),
+                                name_and_parameters: quote! {
+                                    operator=(#parameter_declaration)
+                                },
+                            },
+                            definition_body: quote! {
+                                #field_ident = std::move(#param_ident);
+                                return *this;
+                            },
+                            ..Method::default()
+                        });
                     }
                 };
 
@@ -301,15 +316,16 @@ impl QuotedObject {
                     .filter(|field| !field.is_nullable)
                     .collect_vec();
 
-                // Constructor with all required components.
+                // Constructors with all required components.
                 {
                     let (arguments, assignments): (Vec<_>, Vec<_>) = required_component_fields
                         .iter()
                         .map(|obj_field| {
                             let field_ident = format_ident!("{}", obj_field.name);
+                            let arg_ident = format_ident!("_{}", obj_field.name);
                             (
-                                quote_variable(&mut hpp_includes, obj_field, &field_ident),
-                                quote! { #field_ident(std::move(#field_ident)) },
+                                quote_variable(&mut hpp_includes, obj_field, &arg_ident),
+                                quote! { #field_ident(std::move(#arg_ident)) },
                             )
                         })
                         .unzip();
@@ -320,6 +336,40 @@ impl QuotedObject {
                         }),
                         ..Method::default()
                     });
+
+                    // Provide a non-array version if there's any vectors.
+                    if required_component_fields
+                        .iter()
+                        .any(|obj_field| matches!(obj_field.typ, Type::Vector { .. }))
+                    {
+                        let (arguments, assignments): (Vec<_>, Vec<_>) = required_component_fields
+                            .iter()
+                            .map(|obj_field| {
+                                let field_ident = format_ident!("{}", obj_field.name);
+                                let arg_ident = format_ident!("_{}", obj_field.name);
+
+                                if let Type::Vector { elem_type } = &obj_field.typ {
+                                    let elem_type =
+                                        quote_element_type(&mut hpp_includes, elem_type);
+                                    (
+                                        quote! { #elem_type #arg_ident },
+                                        quote! { #field_ident(1, std::move(#arg_ident)) },
+                                    )
+                                } else {
+                                    (
+                                        quote_variable(&mut hpp_includes, obj_field, &arg_ident),
+                                        quote! { #field_ident(std::move(#arg_ident)) },
+                                    )
+                                }
+                            })
+                            .unzip();
+                        methods.push(Method {
+                            declaration: MethodDeclaration::constructor(quote! {
+                                #type_ident(#(#arguments),*) : #(#assignments),*
+                            }),
+                            ..Method::default()
+                        });
+                    }
                 }
                 // Builder methods for all optional components.
                 for obj_field in obj.fields.iter().filter(|field| field.is_nullable) {
@@ -348,6 +398,26 @@ impl QuotedObject {
                         },
                         inline: true,
                     });
+
+                    // Provide a non-array version if it's a vector.
+                    if let Type::Vector { elem_type } = &obj_field.typ {
+                        let elem_type = quote_element_type(&mut hpp_includes, elem_type);
+                        methods.push(Method {
+                            docs: obj_field.docs.clone().into(),
+                            declaration: MethodDeclaration {
+                                is_static: false,
+                                return_type: quote!(#type_ident&),
+                                name_and_parameters: quote! {
+                                    #method_ident(#elem_type #parameter_ident)
+                                },
+                            },
+                            definition_body: quote! {
+                                #field_ident = std::move(std::vector(1, std::move(#parameter_ident)));
+                                return *this;
+                            },
+                            inline: true,
+                        });
+                    }
                 }
 
                 // Num instances gives the number of primary instances.
@@ -387,6 +457,9 @@ impl QuotedObject {
             let methods_hpp = methods.iter().map(|m| m.to_hpp_tokens());
             quote! {
                 public:
+                    #type_ident() = default;
+                    #NEWLINE_TOKEN
+                    #NEWLINE_TOKEN
                     #(#methods_hpp)*
             }
         };
@@ -686,6 +759,8 @@ impl QuotedObject {
                     struct #pascal_case_ident {
                         #(#constants_hpp;)*
 
+                        #pascal_case_ident() : _tag(detail::#tag_typename::NONE) {}
+
                         #copy_constructor
 
                         // Copy-assignment
@@ -724,10 +799,6 @@ impl QuotedObject {
                     private:
                         detail::#tag_typename _tag;
                         detail::#data_typename _data;
-
-                        // Empty state required by static constructors:
-                        #pascal_case_ident() : _tag(detail::#tag_typename::NONE) {}
-                        public:
                     };
                 }
             }

docs/code-examples/arrow3d_simple_v2.cpp

@@ -0,0 +1,29 @@
+// Log a batch of 3D arrows.
+
+#include <rerun.hpp>
+
+#include <cmath>
+#include <numeric>
+
+namespace rr = rerun;
+
+int main() {
+    auto rr_stream = rr::RecordingStream("arrow3d");
+    rr_stream.connect("127.0.0.1:9876");
+
+    std::vector<rr::components::Vector3D> vectors;
+    std::vector<rr::components::Color> colors;
+
+    for (int i = 0; i < 100; ++i) {
+        float angle = 2.0 * M_PI * i * 0.01f;
+        float length = log2f(i + 1);
+        vectors.push_back(rr::datatypes::Vec3D{length * sinf(angle), 0.0, length * cosf(angle)});
+
+        // TODO(andreas): provide `unmultiplied_rgba`
+        uint8_t c = static_cast<uint8_t>((angle / (2.0 * M_PI) * 255.0) + 0.5);
+        uint32_t color = ((255 - c) << 24) + (c << 16) + (128 << 8) + (128 << 0);
+        colors.push_back(color);
+    }
+
+    rr_stream.log("arrows", rr::archetypes::Arrows3D(vectors).with_colors(colors));
+}

docs/code-examples/disconnected_space_v2.cpp

@@ -0,0 +1,27 @@
+// Disconnect two spaces.
+
+#include <rerun.hpp>
+
+namespace rr = rerun;
+
+int main() {
+    auto rr_stream = rr::RecordingStream("disconnected_space");
+    rr_stream.connect("127.0.0.1:9876");
+
+    // These two points can be projected into the same space..
+    rr_stream.log(
+        "world/room1/point",
+        rr::archetypes::Points3D(rr::datatypes::Vec3D{0.0f, 0.0f, 0.0f})
+    );
+    rr_stream.log(
+        "world/room2/point",
+        rr::archetypes::Points3D(rr::datatypes::Vec3D{1.0f, 1.0f, 1.0f})
+    );
+
+    // ..but this one lives in a completely separate space!
+    rr_stream.log("world/wormhole", rr::archetypes::DisconnectedSpace(true));
+    rr_stream.log(
+        "world/wormhole/point",
+        rr::archetypes::Points3D(rr::datatypes::Vec3D{2.0f, 2.0f, 2.0f})
+    );
+}

docs/code-examples/point3d_random_v2.cpp

@@ -0,0 +1,35 @@
+// Log some random points with color and radii.
+
+#include <rerun.hpp>
+
+#include <algorithm>
+#include <random>
+
+namespace rr = rerun;
+
+int main() {
+    auto rr_stream = rr::RecordingStream("points3d_random");
+    rr_stream.connect("127.0.0.1:9876");
+
+    std::default_random_engine gen;
+    std::uniform_real_distribution<float> dist_pos(-5.0, 5.0);
+    std::uniform_real_distribution<float> dist_radius(0.1, 1.0);
+    std::uniform_int_distribution<uint8_t> dist_color(0, 255);
+
+    std::vector<rr::components::Point3D> points3d(10);
+    std::generate(points3d.begin(), points3d.end(), [&] {
+        return rr::datatypes::Vec3D{dist_pos(gen), dist_pos(gen), dist_pos(gen)};
+    });
+    std::vector<rr::components::Color> colors(10);
+    std::generate(colors.begin(), colors.end(), [&] {
+        // TODO(andreas): provide a `rgb` factory method.
+        return (dist_color(gen) << 24) + (dist_color(gen) << 16) + (dist_color(gen) << 8) + 255;
+    });
+    std::vector<rr::components::Radius> radii(10);
+    std::generate(radii.begin(), radii.end(), [&] { return dist_radius(gen); });
+
+    rr_stream.log(
+        "random",
+        rr::archetypes::Points3D(points3d).with_colors(colors).with_radii(radii)
+    );
+}

docs/code-examples/point3d_random_v2.rs

@@ -1,4 +1,5 @@
-//! Log some random points with color and radii."""
+//! Log some random points with color and radii.
+
 use rand::distributions::Uniform;
 use rand::Rng;
 use rerun::{archetypes::Points3D, components::Color, MsgSender, RecordingStreamBuilder};

docs/code-examples/point3d_simple_v2.cpp

@@ -0,0 +1,17 @@
+// Log some very simple points.
+
+#include <rerun.hpp>
+
+namespace rr = rerun;
+
+int main() {
+    auto rr_stream = rr::RecordingStream("points3d_simple");
+    rr_stream.connect("127.0.0.1:9876");
+
+    rr_stream.log(
+        "points",
+        rr::archetypes::Points3D(
+            {rr::datatypes::Vec3D{0.0f, 0.0f, 0.0f}, rr::datatypes::Vec3D{1.0f, 1.0f, 1.0f}}
+        )
+    );
+}