Mark Window-Manager-specific APIs on android.view.Surface as @hide (b923066d) · Commits · e / os / android_frameworks_base

api/14.txt

+0 −28

Original line number	Diff line number	Diff line
		@@ -20979,45 +20979,17 @@ package android.view {

		public class Surface implements android.os.Parcelable {
		method public int describeContents();
		method public void freeze();
		method public void hide();
		method public boolean isValid();
		method public android.graphics.Canvas lockCanvas(android.graphics.Rect) throws java.lang.IllegalArgumentException, android.view.Surface.OutOfResourcesException;
		method public void readFromParcel(android.os.Parcel);
		method public void setAlpha(float);
		method public void setFlags(int, int);
		method public void setFreezeTint(int);
		method public void setLayer(int);
		method public void setMatrix(float, float, float, float);
		method public static void setOrientation(int, int);
		method public void setPosition(int, int);
		method public void setSize(int, int);
		method public void setTransparentRegionHint(android.graphics.Region);
		method public void show();
		method public void unfreeze();
		method public void unlockCanvas(android.graphics.Canvas);
		method public void unlockCanvasAndPost(android.graphics.Canvas);
		method public void writeToParcel(android.os.Parcel, int);
		field public static final android.os.Parcelable.Creator CREATOR;
		field public static final int FX_SURFACE_BLUR = 65536; // 0x10000
		field public static final int FX_SURFACE_DIM = 131072; // 0x20000
		field public static final int FX_SURFACE_MASK = 983040; // 0xf0000
		field public static final int FX_SURFACE_NORMAL = 0; // 0x0
		field public static final deprecated int GPU = 40; // 0x28
		field public static final deprecated int HARDWARE = 16; // 0x10
		field public static final int HIDDEN = 4; // 0x4
		field public static final int NON_PREMULTIPLIED = 256; // 0x100
		field public static final deprecated int PUSH_BUFFERS = 512; // 0x200
		field public static final int ROTATION_0 = 0; // 0x0
		field public static final int ROTATION_180 = 2; // 0x2
		field public static final int ROTATION_270 = 3; // 0x3
		field public static final int ROTATION_90 = 1; // 0x1
		field public static final int SECURE = 128; // 0x80
		field public static final deprecated int SURACE_FROZEN = 2; // 0x2
		field public static final int SURFACE_BLUR_FREEZE = 16; // 0x10
		field public static final int SURFACE_DITHER = 4; // 0x4
		field public static final int SURFACE_FROZEN = 2; // 0x2
		field public static final int SURFACE_HIDDEN = 1; // 0x1
		}

		public static class Surface.OutOfResourcesException extends java.lang.Exception {

api/current.txt

+1 −28

Original line number	Diff line number	Diff line
		@@ -22068,45 +22068,18 @@ package android.view {

		public class Surface implements android.os.Parcelable {
		method public int describeContents();
		method public void freeze();
		method public void hide();
		method public boolean isValid();
		method public android.graphics.Canvas lockCanvas(android.graphics.Rect) throws java.lang.IllegalArgumentException, android.view.Surface.OutOfResourcesException;
		method public void readFromParcel(android.os.Parcel);
		method public void setAlpha(float);
		method public void setFlags(int, int);
		method public void setFreezeTint(int);
		method public void setLayer(int);
		method public void setMatrix(float, float, float, float);
		method public static void setOrientation(int, int);
		method public void setPosition(int, int);
		method public void setSize(int, int);
		method public void setTransparentRegionHint(android.graphics.Region);
		method public void show();
		method public void unfreeze();
		method public void release();
		method public void unlockCanvas(android.graphics.Canvas);
		method public void unlockCanvasAndPost(android.graphics.Canvas);
		method public void writeToParcel(android.os.Parcel, int);
		field public static final android.os.Parcelable.Creator CREATOR;
		field public static final int FX_SURFACE_BLUR = 65536; // 0x10000
		field public static final int FX_SURFACE_DIM = 131072; // 0x20000
		field public static final int FX_SURFACE_MASK = 983040; // 0xf0000
		field public static final int FX_SURFACE_NORMAL = 0; // 0x0
		field public static final deprecated int GPU = 40; // 0x28
		field public static final deprecated int HARDWARE = 16; // 0x10
		field public static final int HIDDEN = 4; // 0x4
		field public static final int NON_PREMULTIPLIED = 256; // 0x100
		field public static final deprecated int PUSH_BUFFERS = 512; // 0x200
		field public static final int ROTATION_0 = 0; // 0x0
		field public static final int ROTATION_180 = 2; // 0x2
		field public static final int ROTATION_270 = 3; // 0x3
		field public static final int ROTATION_90 = 1; // 0x1
		field public static final int SECURE = 128; // 0x80
		field public static final deprecated int SURACE_FROZEN = 2; // 0x2
		field public static final int SURFACE_BLUR_FREEZE = 16; // 0x10
		field public static final int SURFACE_DITHER = 4; // 0x4
		field public static final int SURFACE_FROZEN = 2; // 0x2
		field public static final int SURFACE_HIDDEN = 1; // 0x1
		}

		public static class Surface.OutOfResourcesException extends java.lang.Exception {

core/java/android/view/Surface.java

+140 −156

Original line number	Diff line number	Diff line
		@@ -29,30 +29,84 @@ public class Surface implements Parcelable {
		private static final String LOG_TAG = "Surface";
		private static final boolean DEBUG_RELEASE = false;

		/* flags used in constructor (keep in sync with ISurfaceComposer.h) */
		/* orientations for setOrientation() */
		public static final int ROTATION_0 = 0;
		public static final int ROTATION_90 = 1;
		public static final int ROTATION_180 = 2;
		public static final int ROTATION_270 = 3;

		/** Surface is created hidden */
		public static final int HIDDEN = 0x00000004;
		/**
		* Does this object hold a valid surface? Returns true if it holds
		* a physical surface, so lockCanvas() will succeed. Otherwise
		* returns false.
		*/
		public native boolean isValid();

		/** Release the local reference to the server-side surface.
		* Always call release() when you're done with a Surface. This will
		* make the surface invalid.
		*/
		public native void release();

		/** draw into a surface */
		public Canvas lockCanvas(Rect dirty) throws OutOfResourcesException, IllegalArgumentException {
		/*
		* the dirty rectangle may be expanded to the surface's size, if for
		* instance it has been resized or if the bits were lost, since the last
		* call.
		*/
		return lockCanvasNative(dirty);
		}

		/** unlock the surface and asks a page flip */
		public native void unlockCanvasAndPost(Canvas canvas);

		/**
		* unlock the surface. the screen won't be updated until
		* post() or postAll() is called
		*/
		public native void unlockCanvas(Canvas canvas);

		@Override
		public String toString() {
		return "Surface(name=" + mName + ", identity=" + getIdentity() + ")";
		}

		public int describeContents() {
		return 0;
		}

		public native void readFromParcel(Parcel source);
		public native void writeToParcel(Parcel dest, int flags);

		/** The surface is to be used by hardware accelerators or DMA engines
		* @deprecated this is ignored, this value is set automatically when needed.
		/**
		* Exception thrown when a surface couldn't be created or resized
		*/
		@Deprecated
		public static final int HARDWARE = 0x00000010;
		public static class OutOfResourcesException extends Exception {
		public OutOfResourcesException() {
		}
		public OutOfResourcesException(String name) {
		super(name);
		}
		}

		/** Implies "HARDWARE", the surface is to be used by the GPU;
		* additionally the backbuffer is never preserved for these
		* surfaces.
		* @deprecated this is ignored, this value is set automatically when needed.
		/*
		* -----------------------------------------------------------------------
		* No user serviceable parts beyond this point
		* -----------------------------------------------------------------------
		*/
		@Deprecated
		public static final int GPU = 0x00000028;

		/* flags used in constructor (keep in sync with ISurfaceComposer.h) */

		/** Surface is created hidden @hide */
		public static final int HIDDEN = 0x00000004;

		/** The surface contains secure content, special measures will
		* be taken to disallow the surface's content to be copied from
		* another process. In particular, screenshots and VNC servers will
		* be disabled, but other measures can take place, for instance the
		* surface might not be hardware accelerated. */
		* surface might not be hardware accelerated.
		* @hide*/
		public static final int SECURE = 0x00000080;

		/** Creates a surface where color components are interpreted as
		@@ -75,19 +129,10 @@ public class Surface implements Parcelable {
		*
		* In some rare situations, a non pre-multiplied surface is preferable.
		*
		* @hide
		*/
		public static final int NON_PREMULTIPLIED = 0x00000100;

		/**
		* Creates a surface without a rendering buffer. Instead, the content
		* of the surface must be pushed by an external entity. This type
		* of surface can be used for efficient camera preview or movie
		* playback.
		*
		* @deprecated not support by the system anymore
		*/
		@Deprecated
		public static final int PUSH_BUFFERS = 0x00000200;
		/**
		* Indicates that the surface must be considered opaque, even if its
		* pixel format is set to translucent. This can be useful if an
		@@ -109,7 +154,7 @@ public class Surface implements Parcelable {

		// 0x1000 is reserved for an independent DRM protected flag in framework

		/** Creates a normal surface. This is the default. */
		/** Creates a normal surface. This is the default. @hide */
		public static final int FX_SURFACE_NORMAL = 0x00000000;

		/** Creates a Blur surface. Everything behind this surface is blurred
		@@ -117,6 +162,7 @@ public class Surface implements Parcelable {
		* is not settable or guaranteed.
		* It is an error to lock a Blur surface, since it doesn't have
		* a backing store.
		* @hide
		*/
		public static final int FX_SURFACE_BLUR = 0x00010000;

		@@ -124,55 +170,35 @@ public class Surface implements Parcelable {
		* by the amount specified in {@link #setAlpha}.
		* It is an error to lock a Dim surface, since it doesn't have
		* a backing store.
		* @hide
		*/
		public static final int FX_SURFACE_DIM = 0x00020000;

		/** Mask used for FX values above */
		/** Mask used for FX values above @hide */
		public static final int FX_SURFACE_MASK = 0x000F0000;

		/* flags used with setFlags() (keep in sync with ISurfaceComposer.h) */

		/** Hide the surface. Equivalent to calling hide(). */
		/** Hide the surface. Equivalent to calling hide(). @hide */
		public static final int SURFACE_HIDDEN = 0x01;

		/** Freeze the surface. Equivalent to calling freeze(). */
		/** Freeze the surface. Equivalent to calling freeze(). @hide */
		public static final int SURFACE_FROZEN = 0x02;

		/**
		* @deprecated Use {@link #SURFACE_FROZEN} instead.
		*/
		@Deprecated
		public static final int SURACE_FROZEN = 0x02;

		/** Enable dithering when compositing this surface */
		/** Enable dithering when compositing this surface @hide */
		public static final int SURFACE_DITHER = 0x04;

		public static final int SURFACE_BLUR_FREEZE= 0x10;

		/* orientations for setOrientation() */
		public static final int ROTATION_0 = 0;
		public static final int ROTATION_90 = 1;
		public static final int ROTATION_180 = 2;
		public static final int ROTATION_270 = 3;

		/**
		* Disable the orientation animation
		* {@hide}
		*/
		/** Disable the orientation animation @hide */
		public static final int FLAGS_ORIENTATION_ANIMATION_DISABLE = 0x000000001;

		// The mSurfaceControl will only be present for Surfaces used by the window
		// server or system processes. When this class is parceled we defer to the
		// mSurfaceControl to do the parceling. Otherwise we parcel the mNativeSurface.
		@SuppressWarnings("unused")
		// mSurfaceControl to do the parceling. Otherwise we parcel the
		// mNativeSurface.
		private int mSurfaceControl;
		@SuppressWarnings("unused")
		private int mSaveCount;
		@SuppressWarnings("unused")
		private Canvas mCanvas;
		@SuppressWarnings("unused")
		private int mNativeSurface;
		@SuppressWarnings("unused")
		private int mSurfaceGenerationId;
		private String mName;

		@@ -184,19 +210,8 @@ public class Surface implements Parcelable {
		// non compatibility mode.
		private Matrix mCompatibleMatrix;

		@SuppressWarnings("unused")
		private Exception mCreationStack;

		/**
		* Exception thrown when a surface couldn't be created or resized
		*/
		public static class OutOfResourcesException extends Exception {
		public OutOfResourcesException() {
		}
		public OutOfResourcesException(String name) {
		super(name);
		}
		}

		/*
		* We use a class initializer to allow the native code to cache some
		@@ -219,10 +234,7 @@ public class Surface implements Parcelable {
		initFromSurfaceTexture(surfaceTexture);
		}

		/**
		* create a surface
		* {@hide}
		*/
		/** create a surface @hide */
		public Surface(SurfaceSession s,
		int pid, int display, int w, int h, int format, int flags)
		throws OutOfResourcesException {
		@@ -233,10 +245,7 @@ public class Surface implements Parcelable {
		init(s,pid,null,display,w,h,format,flags);
		}

		/**
		* create a surface with a name
		* {@hide}
		*/
		/** create a surface with a name @hide */
		public Surface(SurfaceSession s,
		int pid, String name, int display, int w, int h, int format, int flags)
		throws OutOfResourcesException {
		@@ -251,7 +260,7 @@ public class Surface implements Parcelable {
		/**
		* Create an empty surface, which will later be filled in by
		* readFromParcel().
		* {@hide}
		* @hide
		*/
		public Surface() {
		if (DEBUG_RELEASE) {
		@@ -260,16 +269,35 @@ public class Surface implements Parcelable {
		mCanvas = new CompatibleCanvas();
		}

		private Surface(Parcel source) throws OutOfResourcesException {
		init(source);
		}

		/**
		* Copy another surface to this one. This surface now holds a reference
		* to the same data as the original surface, and is -not- the owner.
		* @hide
		*/
		public native void copyFrom(Surface o);

		/** @hide */
		public int getGenerationId() {
		return mSurfaceGenerationId;
		}

		/**
		* A Canvas class that can handle the compatibility mode. This does two things differently.
		* A Canvas class that can handle the compatibility mode. This does two
		* things differently.
		* <ul>
		* <li> Returns the width and height of the target metrics, rather than native.
		* For example, the canvas returns 320x480 even if an app is running in WVGA high density.
		* <li> Scales the matrix in setMatrix by the application scale, except if the matrix looks
		* like obtained from getMatrix. This is a hack to handle the case that an application
		* uses getMatrix to keep the original matrix, set matrix of its own, then set the original
		* matrix back. There is no perfect solution that works for all cases, and there are a lot of
		* cases that this model does not work, but we hope this works for many apps.
		* <li>Returns the width and height of the target metrics, rather than
		* native. For example, the canvas returns 320x480 even if an app is running
		* in WVGA high density.
		* <li>Scales the matrix in setMatrix by the application scale, except if
		* the matrix looks like obtained from getMatrix. This is a hack to handle
		* the case that an application uses getMatrix to keep the original matrix,
		* set matrix of its own, then set the original matrix back. There is no
		* perfect solution that works for all cases, and there are a lot of cases
		* that this model does not work, but we hope this works for many apps.
		* </ul>
		*/
		private class CompatibleCanvas extends Canvas {
		@@ -318,7 +346,8 @@ public class Surface implements Parcelable {
		}

		/**
		* Sets the translator used to scale canvas's width/height in compatibility mode.
		* Sets the translator used to scale canvas's width/height in compatibility
		* mode.
		*/
		void setCompatibilityTranslator(Translator translator) {
		if (translator != null) {
		@@ -328,73 +357,29 @@ public class Surface implements Parcelable {
		}
		}

		/**
		* Copy another surface to this one. This surface now holds a reference
		* to the same data as the original surface, and is -not- the owner.
		* {@hide}
		*/
		public native void copyFrom(Surface o);

		/**
		* Does this object hold a valid surface? Returns true if it holds
		* a physical surface, so lockCanvas() will succeed. Otherwise
		* returns false.
		*/
		public native boolean isValid();

		/**
		* @hide
		*/
		public int getGenerationId() {
		return mSurfaceGenerationId;
		}

		/** Free all server-side state associated with this surface and
		* release this object's reference. {@hide} */
		* release this object's reference. @hide */
		public native void destroy();

		/** Release the local reference to the server-side surface. @hide */
		public native void release();

		/** draw into a surface */
		public Canvas lockCanvas(Rect dirty) throws OutOfResourcesException, IllegalArgumentException
		{
		/* the dirty rectangle may be expanded to the surface's size, if
		* for instance it has been resized or if the bits were lost, since
		* the last call.
		*/
		return lockCanvasNative(dirty);
		}

		private native Canvas lockCanvasNative(Rect dirty);

		/** unlock the surface and asks a page flip */
		public native void unlockCanvasAndPost(Canvas canvas);

		/**
		* unlock the surface. the screen won't be updated until
		* post() or postAll() is called
		/*
		* set display parameters & screenshots
		*/
		public native void unlockCanvas(Canvas canvas);

		/** start/end a transaction {@hide} */
		public static native void openTransaction();
		/** {@hide} */
		public static native void closeTransaction();

		/**
		* Freezes the specified display, No updating of the screen will occur
		* until unfreezeDisplay() is called. Everything else works as usual though,
		* in particular transactions.
		* @param display
		* {@hide}
		* @hide
		*/
		public static native void freezeDisplay(int display);

		/**
		* resume updating the specified display.
		* @param display
		* {@hide}
		* @hide
		*/
		public static native void unfreezeDisplay(int display);

		@@ -403,7 +388,7 @@ public class Surface implements Parcelable {
		* @param display
		* @param orientation
		* @param flags
		* {@hide}
		* @hide
		*/
		public static native void setOrientation(int display, int orientation, int flags);

		@@ -411,6 +396,7 @@ public class Surface implements Parcelable {
		* set the orientation of the given display.
		* @param display
		* @param orientation
		* @hide
		*/
		public static void setOrientation(int display, int orientation) {
		setOrientation(display, orientation, 0);
		@@ -441,43 +427,42 @@ public class Surface implements Parcelable {
		*/
		public static native Bitmap screenshot(int width, int height, int minLayer, int maxLayer);

		/**

		/*
		* set surface parameters.
		* needs to be inside open/closeTransaction block
		*/

		/** start a transaction @hide */
		public static native void openTransaction();
		/** end a transaction @hide */
		public static native void closeTransaction();
		/** @hide */
		public native void setLayer(int zorder);
		/** @hide */
		public native void setPosition(int x, int y);
		/** @hide */
		public native void setSize(int w, int h);

		/** @hide */
		public native void hide();
		/** @hide */
		public native void show();
		/** @hide */
		public native void setTransparentRegionHint(Region region);
		/** @hide */
		public native void setAlpha(float alpha);
		public native void setMatrix(float dsdx, float dtdx,
		float dsdy, float dtdy);

		/** @hide */
		public native void setMatrix(float dsdx, float dtdx, float dsdy, float dtdy);
		/** @hide */
		public native void freeze();
		/** @hide */
		public native void unfreeze();

		/** @hide */
		public native void setFreezeTint(int tint);

		/** @hide */
		public native void setFlags(int flags, int mask);

		@Override
		public String toString() {
		return "Surface(name=" + mName + ", identity=" + getIdentity() + ")";
		}

		private Surface(Parcel source) throws OutOfResourcesException {
		init(source);
		}

		public int describeContents() {
		return 0;
		}

		public native void readFromParcel(Parcel source);
		public native void writeToParcel(Parcel dest, int flags);

		public static final Parcelable.Creator<Surface> CREATOR
		= new Parcelable.Creator<Surface>()
		@@ -496,7 +481,6 @@ public class Surface implements Parcelable {
		}
		};

		/* no user serviceable parts here ... */
		@Override
		protected void finalize() throws Throwable {
		try {