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)]
109#[cfg(any(feature = "encoder", feature = "decoder"))]
110pub mod dynamic_integer_points_kd_tree;
111#[doc(hidden)]
112pub mod edgebreaker_connectivity_decoder;
113#[doc(hidden)]
114pub mod folded_bit32_coder;
115#[doc(hidden)]
116pub mod math_utils;
117#[doc(hidden)]
118pub mod mesh_edgebreaker_shared;
119#[doc(hidden)]
120pub mod mesh_prediction_scheme_data;
121#[doc(hidden)]
122pub mod normal_compression_utils;
123/// Point cloud geometry data.
124pub mod point_cloud;
125#[doc(hidden)]
126pub mod prediction_scheme;
127#[doc(hidden)]
128#[cfg(any(feature = "encoder", feature = "decoder"))]
129pub mod prediction_scheme_constrained_multi_parallelogram;
130#[doc(hidden)]
131#[cfg(any(feature = "encoder", feature = "decoder"))]
132pub mod prediction_scheme_delta;
133#[doc(hidden)]
134#[cfg(any(feature = "encoder", feature = "decoder"))]
135pub mod prediction_scheme_geometric_normal;
136#[cfg(any(
137    all(feature = "encoder", feature = "legacy_bitstream_encode"),
138    all(feature = "decoder", feature = "legacy_bitstream_decode")
139))]
140#[cfg_attr(
141    docsrs,
142    doc(cfg(any(
143        all(feature = "encoder", feature = "legacy_bitstream_encode"),
144        all(feature = "decoder", feature = "legacy_bitstream_decode")
145    )))
146)]
147#[doc(hidden)]
148pub mod prediction_scheme_multi_parallelogram;
149#[doc(hidden)]
150pub mod prediction_scheme_normal_octahedron_canonicalized_transform_base;
151#[doc(hidden)]
152pub mod prediction_scheme_normal_octahedron_transform_base;
153#[doc(hidden)]
154#[cfg(any(feature = "encoder", feature = "decoder"))]
155pub mod prediction_scheme_parallelogram;
156#[doc(hidden)]
157pub mod prediction_scheme_selection;
158#[cfg(any(
159    all(feature = "encoder", feature = "legacy_bitstream_encode"),
160    all(feature = "decoder", feature = "legacy_bitstream_decode")
161))]
162#[cfg_attr(
163    docsrs,
164    doc(cfg(any(
165        all(feature = "encoder", feature = "legacy_bitstream_encode"),
166        all(feature = "decoder", feature = "legacy_bitstream_decode")
167    )))
168)]
169#[doc(hidden)]
170pub mod prediction_scheme_tex_coords_deprecated;
171#[doc(hidden)]
172#[cfg(any(feature = "encoder", feature = "decoder"))]
173pub mod prediction_scheme_tex_coords_portable;
174#[doc(hidden)]
175#[cfg(any(feature = "encoder", feature = "decoder"))]
176pub mod prediction_scheme_wrap;
177#[doc(hidden)]
178pub mod quantization_utils;
179#[doc(hidden)]
180pub mod rans_symbol_coding;
181/// Error and status types.
182pub mod status;
183#[doc(hidden)]
184#[cfg(any(feature = "encoder", feature = "decoder"))]
185pub mod symbol_encoding;
186#[doc(hidden)]
187pub mod test_event_log;
188#[doc(hidden)]
189pub mod version;
190
191// =============================================================================
192// Decoder-only modules
193// =============================================================================
194
195#[cfg(feature = "decoder")]
196#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
197/// Decoder input buffer.
198pub mod decoder_buffer;
199#[cfg(feature = "decoder")]
200#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
201#[doc(hidden)]
202pub mod direct_bit_decoder;
203#[cfg(all(feature = "decoder", feature = "point_cloud_decode"))]
204#[cfg_attr(
205    docsrs,
206    doc(cfg(all(feature = "decoder", feature = "point_cloud_decode")))
207)]
208#[doc(hidden)]
209pub mod kd_tree_attributes_decoder;
210#[cfg(all(feature = "decoder", feature = "point_cloud_decode"))]
211#[cfg_attr(
212    docsrs,
213    doc(cfg(all(feature = "decoder", feature = "point_cloud_decode")))
214)]
215/// Keyframe animation decoder entry point.
216pub mod keyframe_animation_decoder;
217#[cfg(feature = "decoder")]
218#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
219/// Mesh decoder entry point.
220pub mod mesh_decoder;
221#[cfg(feature = "decoder")]
222#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
223#[doc(hidden)]
224pub mod mesh_edgebreaker_decoder;
225#[cfg(all(feature = "decoder", feature = "legacy_bitstream_decode"))]
226#[cfg_attr(
227    docsrs,
228    doc(cfg(all(feature = "decoder", feature = "legacy_bitstream_decode")))
229)]
230#[doc(hidden)]
231pub mod mesh_edgebreaker_traversal_predictive_decoder;
232#[cfg(all(feature = "decoder", feature = "edgebreaker_valence_decode"))]
233#[cfg_attr(
234    docsrs,
235    doc(cfg(all(feature = "decoder", feature = "edgebreaker_valence_decode")))
236)]
237#[doc(hidden)]
238pub mod mesh_edgebreaker_traversal_valence_decoder;
239#[cfg(feature = "decoder")]
240#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
241/// Point cloud decoder entry point.
242pub mod point_cloud_decoder;
243#[cfg(feature = "decoder")]
244#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
245#[doc(hidden)]
246pub mod prediction_scheme_normal_octahedron_canonicalized_decoding_transform;
247#[cfg(feature = "decoder")]
248#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
249#[doc(hidden)]
250pub mod rans_bit_decoder;
251#[cfg(feature = "decoder")]
252#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
253#[doc(hidden)]
254pub mod rans_symbol_decoder;
255#[cfg(feature = "decoder")]
256#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
257#[doc(hidden)]
258pub mod sequential_attribute_decoder;
259#[cfg(feature = "decoder")]
260#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
261#[doc(hidden)]
262pub mod sequential_generic_attribute_decoder;
263#[cfg(feature = "decoder")]
264#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
265#[doc(hidden)]
266pub mod sequential_integer_attribute_decoder;
267#[cfg(feature = "decoder")]
268#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
269#[doc(hidden)]
270pub mod sequential_normal_attribute_decoder;
271
272// =============================================================================
273// Encoder-only modules
274// =============================================================================
275
276#[cfg(feature = "encoder")]
277#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
278#[doc(hidden)]
279pub mod direct_bit_encoder;
280#[cfg(feature = "encoder")]
281#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
282/// Encoder output buffer.
283pub mod encoder_buffer;
284#[cfg(feature = "encoder")]
285#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
286/// Encoder configuration options.
287pub mod encoder_options;
288#[cfg(feature = "encoder")]
289#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
290#[doc(hidden)]
291pub mod kd_tree_attributes_encoder;
292#[cfg(feature = "encoder")]
293#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
294/// Keyframe animation encoder entry point.
295pub mod keyframe_animation_encoder;
296#[cfg(feature = "encoder")]
297#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
298#[doc(hidden)]
299pub mod mesh_edgebreaker_encoder;
300#[cfg(all(feature = "encoder", feature = "legacy_bitstream_encode"))]
301#[cfg_attr(
302    docsrs,
303    doc(cfg(all(feature = "encoder", feature = "legacy_bitstream_encode")))
304)]
305#[doc(hidden)]
306pub mod mesh_edgebreaker_traversal_predictive_encoder;
307#[cfg(all(feature = "encoder", feature = "edgebreaker_valence_encode"))]
308#[cfg_attr(
309    docsrs,
310    doc(cfg(all(feature = "encoder", feature = "edgebreaker_valence_encode")))
311)]
312#[doc(hidden)]
313pub mod mesh_edgebreaker_traversal_valence_encoder;
314#[cfg(feature = "encoder")]
315#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
316/// Mesh encoder entry point.
317pub mod mesh_encoder;
318#[cfg(feature = "encoder")]
319#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
320/// Point cloud encoder entry point.
321pub mod point_cloud_encoder;
322#[cfg(feature = "encoder")]
323#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
324#[doc(hidden)]
325pub mod prediction_scheme_normal_octahedron_canonicalized_encoding_transform;
326#[cfg(feature = "encoder")]
327#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
328#[doc(hidden)]
329pub mod rans_bit_encoder;
330#[cfg(feature = "encoder")]
331#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
332#[doc(hidden)]
333pub mod rans_symbol_encoder;
334#[cfg(feature = "encoder")]
335#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
336#[doc(hidden)]
337pub mod sequential_attribute_encoder;
338#[cfg(feature = "encoder")]
339#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
340#[doc(hidden)]
341pub mod sequential_integer_attribute_encoder;
342#[cfg(feature = "encoder")]
343#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
344#[doc(hidden)]
345pub mod sequential_normal_attribute_encoder;
346#[cfg(feature = "encoder")]
347#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
348#[doc(hidden)]
349pub mod shannon_entropy;
350
351// =============================================================================
352// Core re-exports - always available
353// =============================================================================
354
355pub use draco_types::DataType;
356pub use geometry_attribute::{GeometryAttribute, GeometryAttributeType, PointAttribute};
357pub use geometry_indices::{AttributeValueIndex, FaceIndex, PointIndex};
358pub use keyframe_animation::KeyframeAnimation;
359pub use mesh::Mesh;
360pub use metadata::{AttributeMetadata, GeometryMetadata, Metadata};
361pub use point_cloud::PointCloud;
362pub use status::{DracoError, Status};
363
364// =============================================================================
365// Decoder re-exports
366// =============================================================================
367
368#[cfg(feature = "decoder")]
369#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
370pub use decoder_buffer::DecoderBuffer;
371#[cfg(all(feature = "decoder", feature = "point_cloud_decode"))]
372#[cfg_attr(
373    docsrs,
374    doc(cfg(all(feature = "decoder", feature = "point_cloud_decode")))
375)]
376pub use keyframe_animation_decoder::KeyframeAnimationDecoder;
377#[cfg(feature = "decoder")]
378#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
379pub use mesh_decoder::MeshDecoder;
380#[cfg(feature = "decoder")]
381#[cfg_attr(docsrs, doc(cfg(feature = "decoder")))]
382pub use point_cloud_decoder::PointCloudDecoder;
383
384// =============================================================================
385// Encoder re-exports
386// =============================================================================
387
388#[cfg(feature = "encoder")]
389#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
390pub use encoder_buffer::EncoderBuffer;
391#[cfg(feature = "encoder")]
392#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
393pub use encoder_options::EncoderOptions;
394#[cfg(feature = "encoder")]
395#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
396pub use keyframe_animation_encoder::KeyframeAnimationEncoder;
397#[cfg(feature = "encoder")]
398#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
399pub use mesh_encoder::{EncodedAttributeInfo, EncodedMeshInfo, MeshEncoder};
400#[cfg(feature = "encoder")]
401#[cfg_attr(docsrs, doc(cfg(feature = "encoder")))]
402pub use point_cloud_encoder::PointCloudEncoder;
draco_core/lib.rs

draco_core/
lib.rs
