Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Note that a Surface acts like a weak reference

Browse Source 
This causes frequent programming errors, when developers assume
that holding onto a Surface will keep its associated SurfaceTexture,
ImageReader, etc, also alive.

Bug: 31551063
Test: m offline-sdk-docs, manual viewing of result
Change-Id: I5fb5bb3e3c80c7d5d735417b1697e0fe9a62fc46
This commit is contained in:
Eino-Ville Talvala
2016-09-16 13:34:52 -07:00
parent 492450c88a
commit c4faf0cb13
2 changed files with 16 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
core/java/android/view/Surface.java
View File

@@ -33,6 +33,18 @@ import dalvik.system.CloseGuard;
/** /**
* Handle onto a raw buffer that is being managed by the screen compositor. * Handle onto a raw buffer that is being managed by the screen compositor.
*
* <p>A Surface is generally created by or from a consumer of image buffers (such as a
* {@link android.graphics.SurfaceTexture}, {@link android.media.MediaRecorder}, or
* {@link android.renderscript.Allocation}), and is handed to some kind of producer (such as
* {@link android.opengl.EGL14#eglCreateWindowSurface(android.opengl.EGLDisplay,android.opengl.EGLConfig,java.lang.Object,int[],int) OpenGL},
* {@link android.media.MediaPlayer#setSurface MediaPlayer}, or
* {@link android.hardware.camera2.CameraDevice#createCaptureSession CameraDevice}) to draw
* into.</p>
*
* <p><strong>Note:</strong> A Surface acts like a
* {@link java.lang.ref.WeakReference weak reference} to the consumer it is associated with. By
* itself it will not keep its parent consumer from being reclaimed.</p>
*/ */
public class Surface implements Parcelable { public class Surface implements Parcelable {
private static final String TAG = "Surface"; private static final String TAG = "Surface";

4
media/java/android/media/ImageReader.java
View File

@@ -241,6 +241,10 @@ public class ImageReader implements AutoCloseable {
* same {@link Surface} can be reused with a different API once the first source is * same {@link Surface} can be reused with a different API once the first source is
* disconnected from the {@link Surface}.</p> * disconnected from the {@link Surface}.</p>
* *
* <p>Please note that holding on to the Surface object returned by this method is not enough
* to keep its parent ImageReader from being reclaimed. In that sense, a Surface acts like a
* {@link java.lang.ref.WeakReference weak reference} to the ImageReader that provides it.</p>
*
* @return A {@link Surface} to use for a drawing target for various APIs. * @return A {@link Surface} to use for a drawing target for various APIs.
*/ */
public Surface getSurface() { public Surface getSurface() {