diff --git a/ndk/src/surface_texture.rs b/ndk/src/surface_texture.rs index 51c0df41..051228cf 100644 --- a/ndk/src/surface_texture.rs +++ b/ndk/src/surface_texture.rs @@ -28,14 +28,14 @@ impl SurfaceTexture { Self { ptr } } + /// Get a reference to the native ASurfaceTexture from the corresponding java object. + // /// # Safety /// /// This function should be called with a healthy JVM pointer and with a non-null surface texture, /// which must be kept alive on the Java/Kotlin side. - /// Get a reference to the native ASurfaceTexture from the corresponding java object. - // - /// The caller must keep a reference to the Java `SurfaceTexture` during the lifetime of the returned [`SurfaceTexture`]. - /// Failing to do so could result in the [`SurfaceTexture`] to stop functioning properly once the Java object gets finalized. + /// The caller must keep a reference to the Java [`SurfaceTexture`](SurfaceTexture) during the lifetime of the returned [[`SurfaceTexture`](SurfaceTexture)]. + /// Failing to do so could result in the [`SurfaceTexture`](SurfaceTexture) to stop functioning properly once the Java object gets finalized. /// However, this will not result in program termination. pub unsafe fn from_surface_texture(env: *mut JNIEnv, surface_texture: jobject) -> Option { let a_surface_texture_ptr = ffi::ASurfaceTexture_fromSurfaceTexture(env, surface_texture); @@ -48,23 +48,23 @@ impl SurfaceTexture { self.ptr } - /// Returns a reference to a [`NativeWindow`] (i.e. the Producer) for this [`SurfaceTexture`]. + /// Returns a reference to a [`NativeWindow`] (i.e. the Producer) for this [`SurfaceTexture`(SurfaceTexture). /// /// This is equivalent to Java's: /// ```java /// Surface sur = new Surface(surfaceTexture); /// ``` - pub fn acquire_native_window(&mut self) -> Option { + pub fn acquire_native_window(&self) -> Option { let native_window = unsafe { ffi::ASurfaceTexture_acquireANativeWindow(self.ptr.as_ptr()) }; let n = NonNull::new(native_window)?; Some(unsafe { NativeWindow::from_ptr(n) }) } - /// Attach the [`SurfaceTexture`] to the OpenGL ES context that is current on the calling thread. + /// Attach the [`SurfaceTexture`](SurfaceTexture) to the OpenGL ES context that is current on the calling thread. /// A new OpenGL ES texture object is created and populated with the SurfaceTexture image frame /// that was current at the time of the last call to ASurfaceTexture_detachFromGLContext. /// This new texture is bound to the GL_TEXTURE_EXTERNAL_OES texture target. - /// This can be used to access the [`SurfaceTexture`] image contents from multiple OpenGL ES contexts. + /// This can be used to access the [`SurfaceTexture`](SurfaceTexture) image contents from multiple OpenGL ES contexts. /// Note, however, that the image contents are only accessible from one OpenGL ES context at a time. pub fn attach_to_gl_context(&self, tex_name: u32) -> Result<(), PosixError> { let r = unsafe { ffi::ASurfaceTexture_attachToGLContext(self.ptr.as_ptr(), tex_name) }; @@ -75,12 +75,12 @@ impl SurfaceTexture { } } - /// Detach the [`SurfaceTexture`] from the OpenGL ES context that owns the OpenGL ES texture object. + /// Detach the [`SurfaceTexture`](SurfaceTexture) from the OpenGL ES context that owns the OpenGL ES texture object. /// This call must be made with the OpenGL ES context current on the calling thread. The OpenGL /// ES texture object will be deleted as a result of this call. After calling this method all /// calls to [`update_tex_image()`][Self::update_tex_image()] will fail until a successful call to /// [`attach_to_gl_context()`][Self::attach_to_gl_context()] is made. - /// This can be used to access the [`SurfaceTexture`] image contents from multiple OpenGL ES contexts. + /// This can be used to access the [`SurfaceTexture`](SurfaceTexture) image contents from multiple OpenGL ES contexts. /// Note, however, that the image contents are only accessible from one OpenGL ES context at a time. pub fn detach_from_gl_context(&self) -> Result<(), PosixError> { let r = unsafe { ffi::ASurfaceTexture_detachFromGLContext(self.ptr.as_ptr()) }; @@ -98,15 +98,13 @@ impl SurfaceTexture { r } - /// Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by the most recent call to updateTexImage. - /// This transform matrix maps 2D homogeneous texture coordinates of the form (s, t, 0, 1) with s and t in the inclusive range [0, 1] to the texture coordinate - /// that should be used to sample that location from the texture. Sampling the texture outside of the range of this transform is undefined. - /// The matrix is stored in column-major order so that it may be passed directly to OpenGL ES via the glLoadMatrixf or glUniformMatrix4fv functions. - /// This timestamp is in nanoseconds, and is normally monotonically increasing. The timestamp should be unaffected by time-of-day adjustments, and for - /// a camera should be strictly monotonic but for a MediaPlayer may be reset when the position is set. The specific meaning and zero point of the timestamp depends - /// on the source providing images to the SurfaceTexture. Unless otherwise specified by the image source, timestamps cannot generally be compared across SurfaceTexture - /// instances, or across multiple program invocations. It is mostly useful for determining time offsets between subsequent frames - /// For EGL/Vulkan producers, this timestamp is the desired present time set with the EGL_ANDROID_presentation_time or VK_GOOGLE_display_timing extensions + + /// Retrieve the timestamp associated with the texture image set by the most recent call to updateTexImage(). + /// This timestamp is in nanoseconds, and is normally monotonically increasing. The timestamp should be unaffected + /// by time-of-day adjustments. The specific meaning and zero point of the timestamp depends on the source providing + /// images to the SurfaceTexture. Unless otherwise specified by the image source, timestamps cannot generally be + /// compared across SurfaceTexture instances, or across multiple program invocations. It is mostly useful for determining + /// time offsets between subsequent frames. pub fn timestamp(&self) -> i64 { unsafe { ffi::ASurfaceTexture_getTimestamp(self.ptr.as_ptr()) } }