draco_core/
lib.rs

1//! Core Draco geometry compression primitives.
2//!
3//! `draco-core` implements the raw Draco `.drc` bitstream layer for triangle
4//! meshes and point clouds. It intentionally stops at the geometry compression
5//! model: file containers such as glTF/GLB, OBJ, PLY, and FBX live in
6//! `draco-io`.
7//!
8//! # Main Entry Points
9//!
10//! - [`Mesh`] and [`PointCloud`] hold decoded geometry.
11//! - [`PointAttribute`] stores typed attribute data such as positions, normals,
12//!   colors, texture coordinates, and generic attributes.
13//! - [`Metadata`], [`GeometryMetadata`], and [`AttributeMetadata`] expose raw
14//!   Draco metadata plus C++-compatible typed helpers.
15//! - With the `encoder` feature, use [`MeshEncoder`] or [`PointCloudEncoder`].
16//! - With the `decoder` feature, use [`MeshDecoder`] or [`PointCloudDecoder`].
17//!
18//! # Features
19//!
20//! The default feature set enables both encoding and decoding, point-cloud
21//! KD-tree decoding, EdgeBreaker valence traversal, and legacy bitstream
22//! compatibility helpers. Disable default features when embedding only the
23//! geometry data model or one codec direction is needed.
24//!
25//! # Metadata
26//!
27//! Draco metadata entries are stored as untyped byte blobs in the bitstream.
28//! The typed helpers on [`Metadata`] write the same bytes used by C++ Draco
29//! convenience APIs for `int32`, `double`, arrays, and strings.
30//!
31//! # Example
32//!
33//! ```no_run
34//! use draco_core::{DecoderBuffer, Mesh, MeshDecoder};
35//!
36//! let bytes = std::fs::read("mesh.drc")?;
37//! let mut buffer = DecoderBuffer::new(&bytes);
38//! let mut mesh = Mesh::new();
39//! MeshDecoder::new().decode(&mut buffer, &mut mesh)?;
40//! println!("decoded {} faces", mesh.num_faces());
41//! # Ok::<(), Box<dyn std::error::Error>>(())
42//! ```
43
44#![cfg_attr(docsrs, feature(doc_cfg))]
45// Allow certain clippy lints that are intentional design decisions for C++ port compatibility
46#![allow(clippy::needless_range_loop)] // Many loops follow C++ patterns for array indexing
47#![allow(clippy::manual_memcpy)] // Manual copying matches C++ patterns for clarity
48
49#[cfg(feature = "debug_logs")]
50#[inline]
51pub(crate) fn debug_env_enabled(name: &str) -> bool {
52    std::env::var_os(name).is_some()
53}
54
55/// Emit a diagnostic line to stderr, but only when the `debug_logs` feature is
56/// enabled. `draco-core` is a library, so decode/encode paths must not print on
57/// their own. Using `if cfg!(...)` keeps the formatting arguments type-checked
58/// yet dead-code-eliminated in normal builds: nothing is evaluated and nothing
59/// is printed, so there is no runtime cost and no unused-variable churn.
60///
61/// Defined at the crate root before the module declarations below so every
62/// module can use it by bare name via textual macro scoping.
63macro_rules! debug_log {
64    ($($arg:tt)*) => {
65        if cfg!(feature = "debug_logs") {
66            eprintln!($($arg)*);
67        }
68    };
69}
70
71// =============================================================================
72// Core modules - always available
73// =============================================================================
74
75#[doc(hidden)]
76pub mod ans;
77#[doc(hidden)]
78pub mod attribute_octahedron_transform;
79#[doc(hidden)]
80pub mod attribute_transform;
81#[doc(hidden)]
82pub mod attribute_transform_data;
83#[doc(hidden)]
84pub mod bit_utils;
85#[doc(hidden)]
86pub mod compression_config;
87#[doc(hidden)]
88pub mod corner_table;
89/// Draco scalar data type identifiers.
90pub mod draco_types;
91/// Geometry attribute descriptors and point attribute storage.
92pub mod geometry_attribute;
93/// Strongly typed geometry index wrappers.
94pub mod geometry_indices;
95/// Keyframe animation container built on the point-cloud path.
96pub mod keyframe_animation;
97/// Triangle mesh geometry data.
98pub mod mesh;
99/// Draco metadata containers and bitstream serialization helpers.
100pub mod metadata;
101
102// Internal codec modules are kept public but hidden so existing parity tests can
103// exercise ported Draco internals without presenting them as the public API.
104#[doc(hidden)]
105pub mod attribute_quantization_transform;
106#[doc(hidden)]
107pub mod data_buffer;
108#[doc(hidden)]
109pub mod dynamic_integer_points_kd_tree;
110#[doc(hidden)]
111pub mod edgebreaker_connectivity_decoder;
112#[doc(hidden)]
113pub mod folded_bit32_coder;
114#[doc(hidden)]
115pub mod math_utils;
116#[doc(hidden)]
117pub mod mesh_edgebreaker_shared;
118#[doc(hidden)]
119pub mod mesh_prediction_scheme_data;
120#[doc(hidden)]
121pub mod normal_compression_utils;
122/// Point cloud geometry data.
123pub mod point_cloud;
124#[doc(hidden)]
125pub mod prediction_scheme;
126#[doc(hidden)]
127pub mod prediction_scheme_constrained_multi_parallelogram;
128#[doc(hidden)]
129pub mod prediction_scheme_delta;
130#[doc(hidden)]
131pub mod prediction_scheme_geometric_normal;
132#[cfg(any(
133    all(feature = "encoder", feature = "legacy_bitstream_encode"),
134    all(feature = "decoder", feature = "legacy_bitstream_decode")
135))]
136#[cfg_attr(
137    docsrs,
138    doc(cfg(any(
139        all(feature = "encoder", feature = "legacy_bitstream_encode"),
140        all(feature = "decoder", feature = "legacy_bitstream_decode")
141    )))
142)]
143#[doc(hidden)]
144pub mod prediction_scheme_multi_parallelogram;
145#[doc(hidden)]
146pub mod prediction_scheme_normal_octahedron_canonicalized_transform_base;
147#[doc(hidden)]
148pub mod prediction_scheme_normal_octahedron_transform_base;
149#[doc(hidden)]
150pub mod prediction_scheme_parallelogram;
151#[doc(hidden)]
152pub mod prediction_scheme_selection;
153#[cfg(any(
154    all(feature = "encoder", feature = "legacy_bitstream_encode"),
155    all(feature = "decoder", feature = "legacy_bitstream_decode")
156))]
157#[cfg_attr(
158    docsrs,
159    doc(cfg(any(
160        all(feature = "encoder", feature = "legacy_bitstream_encode"),
161        all(feature = "decoder", feature = "legacy_bitstream_decode")
162    )))
163)]
164#[doc(hidden)]
165pub mod prediction_scheme_tex_coords_deprecated;
166#[doc(hidden)]
167pub mod prediction_scheme_tex_coords_portable;
168#[doc(hidden)]
169pub mod prediction_scheme_wrap;
170#[doc(hidden)]
171pub mod quantization_utils;
172#[doc(hidden)]
173pub mod rans_symbol_coding;
174/// Error and status types.
175pub mod status;
176#[doc(hidden)]
177pub mod symbol_encoding;
178#[doc(hidden)]
179pub mod test_event_log;
180#[doc(hidden)]
181pub mod version;
182
183// =============================================================================
184// Decoder-only modules
185// =============================================================================
186
187#[cfg(feature = "decoder")]
188#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
189/// Decoder input buffer.
190pub mod decoder_buffer;
191#[cfg(feature = "decoder")]
192#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
193#[doc(hidden)]
194pub mod direct_bit_decoder;
195#[cfg(all(feature = "decoder", feature = "point_cloud_decode"))]
196#[cfg_attr(
197    docsrs,
198    doc(cfg(all(feature = "decoder", feature = "point_cloud_decode")))
199)]
200#[doc(hidden)]
201pub mod kd_tree_attributes_decoder;
202#[cfg(all(feature = "decoder", feature = "point_cloud_decode"))]
203#[cfg_attr(
204    docsrs,
205    doc(cfg(all(feature = "decoder", feature = "point_cloud_decode")))
206)]
207/// Keyframe animation decoder entry point.
208pub mod keyframe_animation_decoder;
209#[cfg(feature = "decoder")]
210#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
211/// Mesh decoder entry point.
212pub mod mesh_decoder;
213#[cfg(feature = "decoder")]
214#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
215#[doc(hidden)]
216pub mod mesh_edgebreaker_decoder;
217#[cfg(all(feature = "decoder", feature = "legacy_bitstream_decode"))]
218#[cfg_attr(
219    docsrs,
220    doc(cfg(all(feature = "decoder", feature = "legacy_bitstream_decode")))
221)]
222#[doc(hidden)]
223pub mod mesh_edgebreaker_traversal_predictive_decoder;
224#[cfg(all(feature = "decoder", feature = "edgebreaker_valence_decode"))]
225#[cfg_attr(
226    docsrs,
227    doc(cfg(all(feature = "decoder", feature = "edgebreaker_valence_decode")))
228)]
229#[doc(hidden)]
230pub mod mesh_edgebreaker_traversal_valence_decoder;
231#[cfg(feature = "decoder")]
232#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
233/// Point cloud decoder entry point.
234pub mod point_cloud_decoder;
235#[cfg(feature = "decoder")]
236#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
237#[doc(hidden)]
238pub mod prediction_scheme_normal_octahedron_canonicalized_decoding_transform;
239#[cfg(feature = "decoder")]
240#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
241#[doc(hidden)]
242pub mod rans_bit_decoder;
243#[cfg(feature = "decoder")]
244#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
245#[doc(hidden)]
246pub mod rans_symbol_decoder;
247#[cfg(feature = "decoder")]
248#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
249#[doc(hidden)]
250pub mod sequential_attribute_decoder;
251#[cfg(feature = "decoder")]
252#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
253#[doc(hidden)]
254pub mod sequential_generic_attribute_decoder;
255#[cfg(feature = "decoder")]
256#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
257#[doc(hidden)]
258pub mod sequential_integer_attribute_decoder;
259#[cfg(feature = "decoder")]
260#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
261#[doc(hidden)]
262pub mod sequential_normal_attribute_decoder;
263
264// =============================================================================
265// Encoder-only modules
266// =============================================================================
267
268#[cfg(feature = "encoder")]
269#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
270#[doc(hidden)]
271pub mod direct_bit_encoder;
272#[cfg(feature = "encoder")]
273#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
274/// Encoder output buffer.
275pub mod encoder_buffer;
276#[cfg(feature = "encoder")]
277#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
278/// Encoder configuration options.
279pub mod encoder_options;
280#[cfg(feature = "encoder")]
281#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
282#[doc(hidden)]
283pub mod kd_tree_attributes_encoder;
284#[cfg(feature = "encoder")]
285#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
286/// Keyframe animation encoder entry point.
287pub mod keyframe_animation_encoder;
288#[cfg(feature = "encoder")]
289#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
290#[doc(hidden)]
291pub mod mesh_edgebreaker_encoder;
292#[cfg(all(feature = "encoder", feature = "legacy_bitstream_encode"))]
293#[cfg_attr(
294    docsrs,
295    doc(cfg(all(feature = "encoder", feature = "legacy_bitstream_encode")))
296)]
297#[doc(hidden)]
298pub mod mesh_edgebreaker_traversal_predictive_encoder;
299#[cfg(all(feature = "encoder", feature = "edgebreaker_valence_encode"))]
300#[cfg_attr(
301    docsrs,
302    doc(cfg(all(feature = "encoder", feature = "edgebreaker_valence_encode")))
303)]
304#[doc(hidden)]
305pub mod mesh_edgebreaker_traversal_valence_encoder;
306#[cfg(feature = "encoder")]
307#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
308/// Mesh encoder entry point.
309pub mod mesh_encoder;
310#[cfg(feature = "encoder")]
311#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
312/// Point cloud encoder entry point.
313pub mod point_cloud_encoder;
314#[cfg(feature = "encoder")]
315#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
316#[doc(hidden)]
317pub mod prediction_scheme_normal_octahedron_canonicalized_encoding_transform;
318#[cfg(feature = "encoder")]
319#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
320#[doc(hidden)]
321pub mod rans_bit_encoder;
322#[cfg(feature = "encoder")]
323#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
324#[doc(hidden)]
325pub mod rans_symbol_encoder;
326#[cfg(feature = "encoder")]
327#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
328#[doc(hidden)]
329pub mod sequential_attribute_encoder;
330#[cfg(feature = "encoder")]
331#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
332#[doc(hidden)]
333pub mod sequential_integer_attribute_encoder;
334#[cfg(feature = "encoder")]
335#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
336#[doc(hidden)]
337pub mod sequential_normal_attribute_encoder;
338#[cfg(feature = "encoder")]
339#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
340#[doc(hidden)]
341pub mod shannon_entropy;
342
343// =============================================================================
344// Core re-exports - always available
345// =============================================================================
346
347pub use draco_types::DataType;
348pub use geometry_attribute::{GeometryAttribute, GeometryAttributeType, PointAttribute};
349pub use geometry_indices::{AttributeValueIndex, FaceIndex, PointIndex};
350pub use keyframe_animation::KeyframeAnimation;
351pub use mesh::Mesh;
352pub use metadata::{AttributeMetadata, GeometryMetadata, Metadata};
353pub use point_cloud::PointCloud;
354pub use status::{DracoError, Status};
355
356// =============================================================================
357// Decoder re-exports
358// =============================================================================
359
360#[cfg(feature = "decoder")]
361#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
362pub use decoder_buffer::DecoderBuffer;
363#[cfg(all(feature = "decoder", feature = "point_cloud_decode"))]
364#[cfg_attr(
365    docsrs,
366    doc(cfg(all(feature = "decoder", feature = "point_cloud_decode")))
367)]
368pub use keyframe_animation_decoder::KeyframeAnimationDecoder;
369#[cfg(feature = "decoder")]
370#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
371pub use mesh_decoder::MeshDecoder;
372#[cfg(feature = "decoder")]
373#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
374pub use point_cloud_decoder::PointCloudDecoder;
375
376// =============================================================================
377// Encoder re-exports
378// =============================================================================
379
380#[cfg(feature = "encoder")]
381#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
382pub use encoder_buffer::EncoderBuffer;
383#[cfg(feature = "encoder")]
384#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
385pub use encoder_options::EncoderOptions;
386#[cfg(feature = "encoder")]
387#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
388pub use keyframe_animation_encoder::KeyframeAnimationEncoder;
389#[cfg(feature = "encoder")]
390#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
391pub use mesh_encoder::{EncodedAttributeInfo, EncodedMeshInfo, MeshEncoder};
392#[cfg(feature = "encoder")]
393#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
394pub use point_cloud_encoder::PointCloudEncoder;
draco_core/lib.rs

draco_core/
lib.rs
