1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
//! Defines the pipeline type.
use super::{inactive::InactivePipeline, profile::PipelineProfile};
use crate::{check_rs2_error, frame::CompositeFrame, kind::Rs2Exception};
use anyhow::Result;
use realsense_sys as sys;
use std::{ptr::NonNull, task::Poll, time::Duration};
use thiserror::Error;
/// Enumeration over possible errors that can occur when waiting for a frame.
#[derive(Error, Debug)]
pub enum FrameWaitError {
/// librealsense2 had an internal error occur while waiting for frames.
#[error("An internal error occurred while waiting for frames. Type: {0}; Reason: {1}")]
DidErrorDuringFrameWait(Rs2Exception, String),
/// librealsense2 had an internal error while polling for the next set of frames.
#[error("An internal error occurred while polling for the next set of frames. Type: {0}; Reason: {1}")]
DidErrorDuringFramePoll(Rs2Exception, String),
/// The associated function timed out while waiting for frames.
#[error("Timed out while waiting for frame.")]
DidTimeoutBeforeFrameArrival,
}
/// Type representing an "active" pipeline which is configured and can acquire frames.
#[derive(Debug)]
pub struct ActivePipeline {
/// A (non-null) pointer to the pipeline.
pipeline_ptr: NonNull<sys::rs2_pipeline>,
/// The pipeline's profile, which contains the device the pipeline is configured for alongside
/// the stream profiles for streams in the pipeline.
profile: PipelineProfile,
}
impl Drop for ActivePipeline {
fn drop(&mut self) {
unsafe {
sys::rs2_delete_pipeline(self.pipeline_ptr.as_ptr());
}
}
}
unsafe impl Send for ActivePipeline {}
impl ActivePipeline {
/// Constructs a new active pipeline from the constituent components
///
/// This is only to be used / called from the [`InactivePipeline`] type.
pub(crate) fn new(pipeline_ptr: NonNull<sys::rs2_pipeline>, profile: PipelineProfile) -> Self {
Self {
pipeline_ptr,
profile,
}
}
/// Gets the active profile of pipeline.
pub fn profile(&self) -> &PipelineProfile {
&self.profile
}
/// Stop the pipeline.
///
/// This method consumes the pipeline instance and returns pipeline markered inactive.
pub fn stop(self) -> InactivePipeline {
unsafe {
let mut err = std::ptr::null_mut::<sys::rs2_error>();
// The only "error" that can occur here is if the pipeline pointer is null.
//
// We know it is not (state is managed so that this isn't a possibility, and we use
// `NonNull` to try and guarantee that even beyond our state management), so there
// dealing with the error (and thus returning a result type) is superfluous here.
sys::rs2_pipeline_stop(self.pipeline_ptr.as_ptr(), &mut err);
let inactive = InactivePipeline::new(self.pipeline_ptr);
std::mem::forget(self);
inactive
}
}
/// Waits to get a new composite frame, blocking the calling thread.
///
/// Returns a composite frame from the pipeline, blocking the calling thread until a frame is
/// available. This method can return an error if an internal exception occurs or if the thread
/// waits more than the duration provided by `timeout_ms` (in milliseconds).
///
/// # Arguments
///
/// * `timeout_ms` - The timeout in milliseconds. If the thread blocks for longer than this
/// duration, it will exit early with a [`FrameWaitError::DidTimeoutBeforeFrameArrival`]. If
/// `None` is passed in, the [default timeout](realsense_sys::RS2_DEFAULT_TIMEOUT) is applied.
///
/// # Errors
///
/// Returns [`FrameWaitError::DidErrorDuringFrameWait`] if an internal error occurs while
/// waiting for next frame(s).
///
/// Returns [`FrameWaitError::DidTimeoutBeforeFrameArrival`] if the thread waits more than
/// `timeout_ms` (in milliseconds) without returning a frame.
pub fn wait(&mut self, timeout_ms: Option<Duration>) -> Result<CompositeFrame, FrameWaitError> {
let timeout_ms = match timeout_ms {
Some(d) => d.as_millis() as u32,
None => sys::RS2_DEFAULT_TIMEOUT,
};
unsafe {
let mut err = std::ptr::null_mut::<sys::rs2_error>();
let mut frame = std::ptr::null_mut::<sys::rs2_frame>();
// NOTE: You may notice that there is a `sys::rs2_pipeline_wait_for_frames` and you
// might wonder why we only use this variant. Primarily, they do the same thing, but
// this API is a bit cleaner since it makes it easy to detect if a timeout occurred.
// If you use `rs2_pipeline_wait_for_frames` instead of
// `rs2_pipeline_try_wait_for_frames` then you need to parse the returned `rs2_error`
// message to determine if a timeout occurred. Here, we can just check if
// `did_get_frame` is false (0), and provided no other errors occurred, then that is
// indicative of a timeout.
let did_get_frame = sys::rs2_pipeline_try_wait_for_frames(
self.pipeline_ptr.as_ptr(),
&mut frame,
timeout_ms,
&mut err,
);
check_rs2_error!(err, FrameWaitError::DidErrorDuringFrameWait)?;
if did_get_frame != 0 {
Ok(CompositeFrame::from(NonNull::new(frame).unwrap()))
} else {
Err(FrameWaitError::DidTimeoutBeforeFrameArrival)
}
}
}
/// Poll if next frame is immediately available.
///
/// Unlike [`ActivePipeline::wait`], the method does not block and returns None immediately if
/// the next frame is not available. Returns [`Poll::Pending`] if no frame is yet available,
/// and returns [`Poll::Ready`] if the next composite frame is found.
///
/// # Errors
///
/// Returns [`FrameWaitError::DidErrorDuringFramePoll`] if an internal error occurs while
/// polling for the next frame.
pub fn poll(&mut self) -> Result<Poll<CompositeFrame>, FrameWaitError> {
unsafe {
let mut err = std::ptr::null_mut::<sys::rs2_error>();
let mut frame_ptr = std::ptr::null_mut::<sys::rs2_frame>();
let did_get_frame = sys::rs2_pipeline_poll_for_frames(
self.pipeline_ptr.as_ptr(),
&mut frame_ptr,
&mut err,
);
check_rs2_error!(err, FrameWaitError::DidErrorDuringFramePoll)?;
if did_get_frame != 0 {
Ok(Poll::Ready(CompositeFrame::from(
NonNull::new(frame_ptr).unwrap(),
)))
} else {
Ok(Poll::Pending)
}
}
}
}