public class SurfaceTexture
Class Overview：
Captures frames from an image stream as an OpenGL ES texture.
從一個(gè)圖像流中捕獲圖像幀作為OpenGL ES紋理。
The image stream may come from either camera preview or video decode. A SurfaceTexture may be used in place of a SurfaceHolder when specifying the output destination of a Camera or MediaPlayer object. Doing so will cause all the frames from the image stream to be sent to the SurfaceTexture object rather than to the device's display. When updateTexImage() is called, the contents of the texture object specified when the SurfaceTexture was created are updated to contain the most recent image from the image stream. This may cause some frames of the stream to be skipped.
圖像流可以來自照相機(jī)預(yù)覽或視頻解碼。當(dāng)指定Camera或MediaPlayer對(duì)象的輸出目標(biāo)時(shí)，SurfaceTexture可以取代SurfaceHolder，這樣將使得從圖像流中得到的所有幀都輸出到SurfaceTexture對(duì)象，而不是用于在設(shè)備上顯示。當(dāng)調(diào)用updateTexImage()時(shí)，用來創(chuàng)建SurfaceTexture的紋理對(duì)象內(nèi)容被更新為包含圖像流中最近的圖片。這可能會(huì)使得流中的某些幀被跳過。
When sampling from the texture one should first transform the texture coordinates using the matrix queried via getTransformMatrix(float[]). The transform matrix may change each time updateTexImage() is called, so it should be re-queried each time the texture image is updated. This matrix transforms traditional 2D OpenGL ES texture coordinate column vectors of the form (s, t, 0, 1) where s and t are on the inclusive interval [0, 1] to the proper sampling location in the streamed texture. This transform compensates for any properties of the image stream source that cause it to appear different from a traditional OpenGL ES texture. For example, sampling from the bottom left corner of the image can be accomplished by transforming the column vector (0, 0, 0, 1) using the queried matrix, while sampling from the top right corner of the image can be done by transforming (1, 1, 0, 1).
當(dāng)對(duì)紋理進(jìn)行采樣的時(shí)候，應(yīng)該首先使用getTransformMatrix(float[])查詢得到的矩陣來變換紋理坐標(biāo)。每次調(diào)用updateTexImage()的時(shí)候，可能會(huì)導(dǎo)致變換矩陣發(fā)生變化，因此在紋理圖像更新時(shí)需要重新查詢。該矩陣將傳統(tǒng)的2D OpenGL ES紋理坐標(biāo)列向量(s,t,0,1)，其中s，t∈[0,1]，變換為紋理中對(duì)應(yīng)的采樣位置。該變換補(bǔ)償了圖像流中任何可能導(dǎo)致與傳統(tǒng)OpenGL ES紋理有差異的屬性。例如，從圖像的左下角開始采樣，可以通過使用查詢得到的矩陣來變換列向量(0,0,0,1)，而從右上角采樣可以通過變換(1,1,0,1)來得到。
The texture object uses the GL_TEXTURE_EXTERNAL_OES texture target, which is defined by the GL_OES_EGL_image_external OpenGL ES extension. This limits how the texture may be used. Each time the texture is bound it must be bound to the GL_TEXTURE_EXTERNAL_OES target rather than the GL_TEXTURE_2D target. Additionally, any OpenGL ES 2.0 shader that samples from the texture must declare its use of this extension using, for example, an "#extension GL_OES_EGL_image_external : require" directive. Such shaders must also access the texture using the samplerExternalOES GLSL sampler type.
紋理對(duì)象使用GL_TEXTURE_EXTERNAL_OES作為紋理目標(biāo)，其是OpenGL ES擴(kuò)展GL_OES_EGL_image_external定義的。這種紋理目標(biāo)會(huì)對(duì)紋理的使用方式造成一些限制。每次紋理綁定的時(shí)候，都要綁定到GL_TEXTURE_EXTERNAL_OES，而不是GL_TEXTURE_2D。而且，任何需要從紋理中采樣的OpenGL ES 2.0 shader都需要聲明其對(duì)此擴(kuò)展的使用，例如，使用指令”#extension GL_OES_EGL_image_external:require”。這些shader也必須使用samplerExternalOES采樣方式來訪問紋理。
SurfaceTexture objects may be created on any thread. updateTexImage() may only be called on the thread with the OpenGL ES context that contains the texture object. The frame-available callback is called on an arbitrary thread, so unless special care is taken updateTexImage() should not be called directly from the callback.
SurfaceTexture對(duì)象可以在任何線程里創(chuàng)建。updateTexImage()只能在包含紋理對(duì)象的OpenGL ES上下文所在的線程里創(chuàng)建。可以得到幀信息的回調(diào)可以在任何線程被調(diào)用，因此在沒有做必要的保護(hù)的情況下，updateTexImage()不應(yīng)該直接從回調(diào)函數(shù)中調(diào)用。
Summary
Nested Classes
interface SurfaceTexture.OnFrameAvailableListener Callback interface for being notified that a new stream frame is available. 當(dāng)新的幀流可用時(shí)通知該回調(diào)接口。
class SurfaceTexture.OutOfResourcesException Exception thrown when a surface couldn't be created or resized 當(dāng)無法創(chuàng)建surface或調(diào)整surface尺寸時(shí)，拋出異常。
Public Constructors
SurfaceTexture(int texName)
Construct a new SurfaceTexture to stream images to a given OpenGL texture.
構(gòu)造新的源自圖像流的SurfaceTexture到給定的OpenGL紋理。
Public Methods
long getTimestamp()
Retrieve the timestamp associated with the texture image set by the most recent call to updateTexImage.
void getTransformMatrix(float[] mtx)
Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by the most recent call to updateTexImage.
提取最近調(diào)用的updateTexImage()為紋理圖像設(shè)置的4×4的紋理坐標(biāo)變換矩陣。
void release()
release() frees all the buffers and puts the SurfaceTexture into the 'abandoned' state.
釋放所有的緩沖區(qū)，將SurfaceTexture置為abandoned狀態(tài)。
void setDefaultBufferSize(int width, int height)
Set the default size of the image buffers.
設(shè)置默認(rèn)的圖像緩沖區(qū)大小。
void setOnFrameAvailableListener(SurfaceTexture.OnFrameAvailableListener l)
Register a callback to be invoked when a new image frame becomes available to the SurfaceTexture.
注冊(cè)一個(gè)回調(diào)函數(shù)，當(dāng)新一幀圖像對(duì)SurfaceTexture可用時(shí)調(diào)用。
void updateTexImage()
Update the texture image to the most recent frame from the image stream.
更新紋理圖像為從圖像流中提取的最近一幀。
Protected Methods
void finalize()
Invoked when the garbage collector has detected that this instance is no longer reachable.
[Expand]
Inherited Methods
From class java.lang.Object
Public Constructors
public SurfaceTexture (int texName)
Since: API Level 11
Construct a new SurfaceTexture to stream images to a given OpenGL texture.
構(gòu)造新的源自圖像流的SurfaceTexture到給定的OpenGL紋理。
Parameters
texName the OpenGL texture object name (e.g. generated via glGenTextures)
texName：OpenGL紋理對(duì)象名字，如通過glGenTextures創(chuàng)建的。
Public Methods
public long getTimestamp ()
Since: API Level 14
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, 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.
提取最近調(diào)用的updateTexImage()為紋理圖像設(shè)置的時(shí)間戳。該時(shí)間戳以納秒為單位，通常是單調(diào)遞增的。該時(shí)間戳不應(yīng)受日立時(shí)間影響，對(duì)camera應(yīng)該是嚴(yán)格單調(diào)的，但是對(duì)MediaPlayer來說，設(shè)置播放位置時(shí)可能會(huì)重置。時(shí)間戳的特殊含義以及零點(diǎn)位置取決于為SurfaceTexture提供圖像的源。除非圖像源有特殊說明，時(shí)間戳不應(yīng)該在不同的SurfaceTexture實(shí)例之間，或多個(gè)程序調(diào)用之間進(jìn)行比較。它主要應(yīng)該用于在后續(xù)幀之間決定時(shí)間間隔。
public void getTransformMatrix (float[] mtx)
Since: API Level 11
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.
提取最近調(diào)用的updateTexImage()為紋理圖像設(shè)置的4×4的紋理坐標(biāo)變換矩陣。該變換矩陣將2D的其次紋理坐標(biāo)(s,t,0,1)，s，t∈[0,1]變換為對(duì)應(yīng)的用于從紋理中采樣的紋理坐標(biāo)。在本變換的范圍之外對(duì)紋理進(jìn)行采樣時(shí)未定義的行為。矩陣列主序存儲(chǔ)，可以通過glLoadMatrixf()或glUniformMatrix4fv()函數(shù)直接傳遞給OpenGL ES。
Parameters
mtx the array into which the 4x4 matrix will be stored. The array must have exactly 16 elements.
mtx用于存儲(chǔ)4×4矩陣。該矩陣必須是16個(gè)元素。
public void release ()
Since: API Level 14
release() frees all the buffers and puts the SurfaceTexture into the 'abandoned' state. Once put in this state the SurfaceTexture can never leave it. When in the 'abandoned' state, all methods of the ISurfaceTexture interface will fail with the NO_INIT error. Note that while calling this method causes all the buffers to be freed from the perspective of the the SurfaceTexture, if there are additional references on the buffers (e.g. if a buffer is referenced by a client or by OpenGL ES as a texture) then those buffer will remain allocated. Always call this method when you are done with SurfaceTexture. Failing to do so may delay resource deallocation for a significant amount of time.
釋放所有的緩沖區(qū)，將SurfaceTexture置為abandoned狀態(tài)。一旦進(jìn)入此狀態(tài)，SurfaceTexture將不會(huì)離開此狀態(tài)。一旦進(jìn)入abandoned狀態(tài)，ISurfaceTexture接口的所有方法都將返回NO_INIT錯(cuò)誤。注意：調(diào)用此方法時(shí)，從SurfaceTexture的角度看，所有的緩沖區(qū)都被釋放，如果仍然有其他的到緩沖區(qū)的引用(如，一緩沖區(qū)被客戶端引用，或者被OpenGL ES作為紋理引用)，那么該緩沖區(qū)將仍存在。當(dāng)使用完SurfaceTexture之后，一定要調(diào)用此方法，否則將會(huì)導(dǎo)致資源重新分配被延誤很長(zhǎng)時(shí)間。
public void setDefaultBufferSize (int width, int height)
Since: API Level 15
Set the default size of the image buffers. The image producer may override the buffer size, in which case the producer-set buffer size will be used, not the default size set by this method. Both video and camera based image producers do override the size. This method may be used to set the image size when producing images with Canvas (via lockCanvas(Rect)), or OpenGL ES (via an EGLSurface). The new default buffer size will take effect the next time the image producer requests a buffer to fill. For Canvas this will be the next time lockCanvas(Rect) is called. For OpenGL ES, the EGLSurface should be destroyed (via eglDestroySurface), made not-current (via eglMakeCurrent), and then recreated (via eglCreateWindowSurface) to ensure that the new default size has taken effect. The width and height parameters must be no greater than the minimum of GL_MAX_VIEWPORT_DIMS and GL_MAX_TEXTURE_SIZE (see glGetIntegerv). An error due to invalid dimensions might not be reported until updateTexImage() is called.
設(shè)置默認(rèn)的圖像緩沖區(qū)大小。圖像提供者可能會(huì)重寫緩沖區(qū)大小，這時(shí)，將使用新的緩沖區(qū)大小，而不是默認(rèn)大小?；谝曨l和camera的圖像生產(chǎn)者都會(huì)重寫緩沖區(qū)大小。該方法可以用于設(shè)置使用Canvas(通過lockCanvas(Rect))來產(chǎn)生圖像,或通過OpenGL ES(通過EGLSurface)來產(chǎn)生圖像時(shí)圖像的大小。新的默認(rèn)緩沖區(qū)大小將會(huì)在下一次圖像生產(chǎn)者請(qǐng)求填充一塊緩沖區(qū)時(shí)生效。對(duì)Canvas來說，是下一次調(diào)用lockCanvas(Rect)；對(duì)OpenGL ES，EGLSurface應(yīng)該被銷毀(通過eglDestroySurface)，變成非當(dāng)前的(通過eglMakeCurrent)，然后在重新創(chuàng)建(通過eglCreateWindowSurface)，以保證新的默認(rèn)大小生效。width和height參數(shù)值應(yīng)該不大于GL_MAX_VIEWPORT_DIMS和GL_MAX_TEXTURE_SIZE(參見glGetIntegerv)。不合理的尺寸所引起的錯(cuò)誤在updateTexImage()被調(diào)用之前不會(huì)被報(bào)告。
public void setOnFrameAvailableListener (SurfaceTexture.OnFrameAvailableListener l)
Since: API Level 11
Register a callback to be invoked when a new image frame becomes available to the SurfaceTexture. Note that this callback may be called on an arbitrary thread, so it is not safe to call updateTexImage() without first binding the OpenGL ES context to the thread invoking the callback.
注冊(cè)一個(gè)回調(diào)函數(shù)，當(dāng)新一幀圖像對(duì)SurfaceTexture可用時(shí)調(diào)用。注意：該回調(diào)可能在任何線程被調(diào)用，因此在事先不綁定OpenGL ES上下文到調(diào)用該回調(diào)的線程就調(diào)用updateTexImage()是不安全的。
public void updateTexImage ()
Since: API Level 11
Update the texture image to the most recent frame from the image stream. This may only be called while the OpenGL ES context that owns the texture is bound to the thread. It will implicitly bind its texture to the GL_TEXTURE_EXTERNAL_OES texture target.
更新紋理圖像為從圖像流中提取的最近一幀。只有在擁有該紋理的OpenGL ES上下文被綁定到線程之后調(diào)用。隱式綁定該紋理到GL_TEXTURE_EXTERNAL_OES紋理目標(biāo)。
Protected Methods
protected void finalize ()
Since: API Level 11
Invoked when the garbage collector has detected that this instance is no longer reachable. The default implementation does nothing, but this method can be overridden to free resources.
Note that objects that override finalize are significantly more expensive than objects that don't. Finalizers may be run a long time after the object is no longer reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup. Note also that finalizers are run on a single VM-wide finalizer thread, so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary for a class that has a native peer and needs to call a native method to destroy that peer. Even then, it's better to provide an explicit close method (and implement Closeable), and insist that callers manually dispose of instances. This works well for something like files, but less well for something like a BigInteger where typical calling code would have to deal with lots of temporaries. Unfortunately, code that creates lots of temporaries is the worst kind of code from the point of view of the single finalizer thread.
If you must use finalizers, consider at least providing your own ReferenceQueue and having your own thread process that queue.
Unlike constructors, finalizers are not automatically chained. You are responsible for calling super.finalize() yourself.
Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer thread. See Effective Java Item 7, "Avoid finalizers" for more.
Throws
Throwable
