Add in-place modification helper

Author: twistedfall

src/manual/core.rs

@@ -1,6 +1,7 @@
 pub use affine3::*;
 pub use data_type::*;
 pub use directx::*;
+pub use inplace::*;
 pub use input_output_array::*;
 pub use mat::*;
 pub use mat_ops::*;
@@ -21,6 +22,7 @@ mod affine3;
 mod data_type;
 mod directx;
 mod gpumat;
+mod inplace;
 mod input_output_array;
 mod mat;
 mod mat_ops;

src/manual/core/inplace.rs

@@ -0,0 +1,35 @@
+use crate::boxed_ref::BoxedRefMut;
+use crate::traits::Boxed;
+
+pub trait ModifyInplace {
+	/// Helper function to call OpenCV functions that allow in-place modification of a `Mat` or another similar object. By passing
+	/// a mutable reference to the `Mat` to this function your closure will get called with the read reference and a write references
+	/// to the same `Mat`. This is of course unsafe as it breaks the Rust aliasing rules, but it might be useful for some performance
+	/// sensitive operations. One example of an OpenCV function that allows such in-place modification is `imgproc::threshold`.
+	///
+	/// # Safety
+	/// Caller must make sure that any functions called inside the closure can act on a `Mat` in-place.
+	unsafe fn modify_inplace<Res>(&mut self, f: impl FnOnce(&Self, &mut Self) -> Res) -> Res;
+}
+
+impl<Mat: Boxed> ModifyInplace for Mat {
+	#[inline(always)]
+	unsafe fn modify_inplace<Res>(&mut self, f: impl FnOnce(&Self, &mut Self) -> Res) -> Res {
+		let mut m_alias = Mat::from_raw(self.as_raw_mut());
+		let out = f(self, &mut m_alias);
+		// prevent running destructor on m_alias
+		let _ = m_alias.into_raw();
+		out
+	}
+}
+
+impl<'b, Mat: Boxed> ModifyInplace for BoxedRefMut<'b, Mat> {
+	#[inline(always)]
+	unsafe fn modify_inplace<Res>(&mut self, f: impl FnOnce(&Self, &mut Self) -> Res) -> Res {
+		let mut m_alias = BoxedRefMut::from(Mat::from_raw(self.reference.as_raw_mut()));
+		let out = f(self, &mut m_alias);
+		// prevent running destructor on m_alias
+		let _ = m_alias.reference.into_raw();
+		out
+	}
+}

src/manual/mod.rs

@@ -10,5 +10,5 @@ pub mod prelude {
 	pub use super::core::MatSizeTraitConstManual;
 	pub use super::core::VectorToVec;
 	#[cfg(ocvrs_has_module_core)]
-	pub use super::core::{MatConstIteratorTraitManual, MatTraitConstManual, MatTraitManual, MatxTrait};
+	pub use super::core::{MatConstIteratorTraitManual, MatTraitConstManual, MatTraitManual, MatxTrait, ModifyInplace};
 }

tests/inplace.rs

@@ -0,0 +1,37 @@
+use opencv::core::Vector;
+use opencv::prelude::*;
+use opencv::{imgproc, Result};
+
+#[test]
+fn inplace() -> Result<()> {
+	// owned Mat
+	{
+		let data: [f32; 9] = [1., 2., 3., 4., 5., 6., 7., 8., 9.];
+		let mut m = Mat::new_rows_cols_with_data(3, 3, &data)?.clone_pointee();
+		unsafe {
+			m.modify_inplace(|i, o| imgproc::threshold(i, o, 4., 100., imgproc::THRESH_BINARY))?;
+		}
+		assert_eq!([0., 0., 0., 0., 100., 100., 100., 100., 100.], m.data_typed::<f32>()?);
+	}
+
+	// BoxedRefMut<Mat>
+	{
+		let mut data: [f32; 9] = [1., 2., 3., 4., 5., 6., 7., 8., 9.];
+		let mut m = Mat::new_rows_cols_with_data_mut(3, 3, &mut data)?;
+		unsafe {
+			m.modify_inplace(|i, o| imgproc::threshold(i, o, 4., 100., imgproc::THRESH_BINARY))?;
+		}
+		assert_eq!([0., 0., 0., 0., 100., 100., 100., 100., 100.], m.data_typed::<f32>()?);
+		assert_eq!([0., 0., 0., 0., 100., 100., 100., 100., 100.], data);
+	}
+
+	// Vector
+	{
+		let mut data = Vector::<f64>::from_slice(&[1., 2., 3., 4., 5., 6., 7., 8., 9.]);
+		unsafe {
+			data.modify_inplace(|i, o| imgproc::threshold(i, o, 4., 100., imgproc::THRESH_BINARY))?;
+		}
+		assert_eq!([0., 0., 0., 0., 100., 100., 100., 100., 100.], data.as_slice());
+	}
+	Ok(())
+}