1/*
2 * Copyright 2014 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef ANDROID_GUI_BUFFERSLOT_H
18#define ANDROID_GUI_BUFFERSLOT_H
19
20#include <ui/Fence.h>
21#include <ui/GraphicBuffer.h>
22
23#include <EGL/egl.h>
24#include <EGL/eglext.h>
25
26#include <utils/StrongPointer.h>
27
28namespace android {
29
30class Fence;
31
32struct BufferSlot {
33
34    BufferSlot()
35    : mEglDisplay(EGL_NO_DISPLAY),
36      mBufferState(BufferSlot::FREE),
37      mRequestBufferCalled(false),
38      mFrameNumber(0),
39      mEglFence(EGL_NO_SYNC_KHR),
40      mAcquireCalled(false),
41      mNeedsCleanupOnRelease(false),
42      mAttachedByConsumer(false) {
43    }
44
45    // mGraphicBuffer points to the buffer allocated for this slot or is NULL
46    // if no buffer has been allocated.
47    sp<GraphicBuffer> mGraphicBuffer;
48
49    // mEglDisplay is the EGLDisplay used to create EGLSyncKHR objects.
50    EGLDisplay mEglDisplay;
51
52    // BufferState represents the different states in which a buffer slot
53    // can be.  All slots are initially FREE.
54    enum BufferState {
55        // FREE indicates that the buffer is available to be dequeued
56        // by the producer.  The buffer may be in use by the consumer for
57        // a finite time, so the buffer must not be modified until the
58        // associated fence is signaled.
59        //
60        // The slot is "owned" by BufferQueue.  It transitions to DEQUEUED
61        // when dequeueBuffer is called.
62        FREE = 0,
63
64        // DEQUEUED indicates that the buffer has been dequeued by the
65        // producer, but has not yet been queued or canceled.  The
66        // producer may modify the buffer's contents as soon as the
67        // associated ready fence is signaled.
68        //
69        // The slot is "owned" by the producer.  It can transition to
70        // QUEUED (via queueBuffer) or back to FREE (via cancelBuffer).
71        DEQUEUED = 1,
72
73        // QUEUED indicates that the buffer has been filled by the
74        // producer and queued for use by the consumer.  The buffer
75        // contents may continue to be modified for a finite time, so
76        // the contents must not be accessed until the associated fence
77        // is signaled.
78        //
79        // The slot is "owned" by BufferQueue.  It can transition to
80        // ACQUIRED (via acquireBuffer) or to FREE (if another buffer is
81        // queued in asynchronous mode).
82        QUEUED = 2,
83
84        // ACQUIRED indicates that the buffer has been acquired by the
85        // consumer.  As with QUEUED, the contents must not be accessed
86        // by the consumer until the fence is signaled.
87        //
88        // The slot is "owned" by the consumer.  It transitions to FREE
89        // when releaseBuffer is called.
90        ACQUIRED = 3
91    };
92
93    static const char* bufferStateName(BufferState state);
94
95    // mBufferState is the current state of this buffer slot.
96    BufferState mBufferState;
97
98    // mRequestBufferCalled is used for validating that the producer did
99    // call requestBuffer() when told to do so. Technically this is not
100    // needed but useful for debugging and catching producer bugs.
101    bool mRequestBufferCalled;
102
103    // mFrameNumber is the number of the queued frame for this slot.  This
104    // is used to dequeue buffers in LRU order (useful because buffers
105    // may be released before their release fence is signaled).
106    uint64_t mFrameNumber;
107
108    // mEglFence is the EGL sync object that must signal before the buffer
109    // associated with this buffer slot may be dequeued. It is initialized
110    // to EGL_NO_SYNC_KHR when the buffer is created and may be set to a
111    // new sync object in releaseBuffer.  (This is deprecated in favor of
112    // mFence, below.)
113    EGLSyncKHR mEglFence;
114
115    // mFence is a fence which will signal when work initiated by the
116    // previous owner of the buffer is finished. When the buffer is FREE,
117    // the fence indicates when the consumer has finished reading
118    // from the buffer, or when the producer has finished writing if it
119    // called cancelBuffer after queueing some writes. When the buffer is
120    // QUEUED, it indicates when the producer has finished filling the
121    // buffer. When the buffer is DEQUEUED or ACQUIRED, the fence has been
122    // passed to the consumer or producer along with ownership of the
123    // buffer, and mFence is set to NO_FENCE.
124    sp<Fence> mFence;
125
126    // Indicates whether this buffer has been seen by a consumer yet
127    bool mAcquireCalled;
128
129    // Indicates whether this buffer needs to be cleaned up by the
130    // consumer.  This is set when a buffer in ACQUIRED state is freed.
131    // It causes releaseBuffer to return STALE_BUFFER_SLOT.
132    bool mNeedsCleanupOnRelease;
133
134    // Indicates whether the buffer was attached on the consumer side.
135    // If so, it needs to set the BUFFER_NEEDS_REALLOCATION flag when dequeued
136    // to prevent the producer from using a stale cached buffer.
137    bool mAttachedByConsumer;
138};
139
140} // namespace android
141
142#endif
143