Home | History | Annotate | Download | only in gui 
      1 /*
      2  * Copyright (C) 2012 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_CPUCONSUMER_H
     18 #define ANDROID_GUI_CPUCONSUMER_H
     19 
     20 #include <gui/ConsumerBase.h>
     21 
     22 #include <ui/GraphicBuffer.h>
     23 
     24 #include <utils/String8.h>
     25 #include <utils/Vector.h>
     26 #include <utils/threads.h>
     27 
     28 
     29 namespace android {
     30 
     31 class BufferQueue;
     32 
     33 /**
     34  * CpuConsumer is a BufferQueue consumer endpoint that allows direct CPU
     35  * access to the underlying gralloc buffers provided by BufferQueue. Multiple
     36  * buffers may be acquired by it at once, to be used concurrently by the
     37  * CpuConsumer owner. Sets gralloc usage flags to be software-read-only.
     38  * This queue is synchronous by default.
     39  */
     40 
     41 class CpuConsumer : public ConsumerBase
     42 {
     43   public:
     44     typedef ConsumerBase::FrameAvailableListener FrameAvailableListener;
     45 
     46     struct LockedBuffer {
     47         uint8_t    *data;
     48         uint32_t    width;
     49         uint32_t    height;
     50         PixelFormat format;
     51         uint32_t    stride;
     52         Rect        crop;
     53         uint32_t    transform;
     54         uint32_t    scalingMode;
     55         int64_t     timestamp;
     56         android_dataspace dataSpace;
     57         uint64_t    frameNumber;
     58         // this is the same as format, except for formats that are compatible with
     59         // a flexible format (e.g. HAL_PIXEL_FORMAT_YCbCr_420_888). In the latter
     60         // case this contains that flexible format
     61         PixelFormat flexFormat;
     62         // Values below are only valid when using HAL_PIXEL_FORMAT_YCbCr_420_888
     63         // or compatible format, in which case LockedBuffer::data
     64         // contains the Y channel, and stride is the Y channel stride. For other
     65         // formats, these will all be 0.
     66         uint8_t    *dataCb;
     67         uint8_t    *dataCr;
     68         uint32_t    chromaStride;
     69         uint32_t    chromaStep;
     70 
     71         LockedBuffer() :
     72             data(NULL),
     73             width(0),
     74             height(0),
     75             format(PIXEL_FORMAT_NONE),
     76             stride(0),
     77             crop(Rect::EMPTY_RECT),
     78             transform(0),
     79             scalingMode(NATIVE_WINDOW_SCALING_MODE_FREEZE),
     80             timestamp(0),
     81             dataSpace(HAL_DATASPACE_UNKNOWN),
     82             frameNumber(0),
     83             flexFormat(PIXEL_FORMAT_NONE),
     84             dataCb(NULL),
     85             dataCr(NULL),
     86             chromaStride(0),
     87             chromaStep(0)
     88         {}
     89     };
     90 
     91     // Create a new CPU consumer. The maxLockedBuffers parameter specifies
     92     // how many buffers can be locked for user access at the same time.
     93     CpuConsumer(const sp<IGraphicBufferConsumer>& bq,
     94             size_t maxLockedBuffers, bool controlledByApp = false);
     95 
     96     virtual ~CpuConsumer();
     97 
     98     // set the name of the CpuConsumer that will be used to identify it in
     99     // log messages.
    100     void setName(const String8& name);
    101 
    102     // Gets the next graphics buffer from the producer and locks it for CPU use,
    103     // filling out the passed-in locked buffer structure with the native pointer
    104     // and metadata. Returns BAD_VALUE if no new buffer is available, and
    105     // NOT_ENOUGH_DATA if the maximum number of buffers is already locked.
    106     //
    107     // Only a fixed number of buffers can be locked at a time, determined by the
    108     // construction-time maxLockedBuffers parameter. If INVALID_OPERATION is
    109     // returned by lockNextBuffer, then old buffers must be returned to the queue
    110     // by calling unlockBuffer before more buffers can be acquired.
    111     status_t lockNextBuffer(LockedBuffer *nativeBuffer);
    112 
    113     // Returns a locked buffer to the queue, allowing it to be reused. Since
    114     // only a fixed number of buffers may be locked at a time, old buffers must
    115     // be released by calling unlockBuffer to ensure new buffers can be acquired by
    116     // lockNextBuffer.
    117     status_t unlockBuffer(const LockedBuffer &nativeBuffer);
    118 
    119   private:
    120     // Maximum number of buffers that can be locked at a time
    121     size_t mMaxLockedBuffers;
    122 
    123     status_t releaseAcquiredBufferLocked(size_t lockedIdx);
    124 
    125     virtual void freeBufferLocked(int slotIndex);
    126 
    127     // Tracking for buffers acquired by the user
    128     struct AcquiredBuffer {
    129         // Need to track the original mSlot index and the buffer itself because
    130         // the mSlot entry may be freed/reused before the acquired buffer is
    131         // released.
    132         int mSlot;
    133         sp<GraphicBuffer> mGraphicBuffer;
    134         void *mBufferPointer;
    135 
    136         AcquiredBuffer() :
    137                 mSlot(BufferQueue::INVALID_BUFFER_SLOT),
    138                 mBufferPointer(NULL) {
    139         }
    140     };
    141     Vector<AcquiredBuffer> mAcquiredBuffers;
    142 
    143     // Count of currently locked buffers
    144     size_t mCurrentLockedBuffers;
    145 
    146 };
    147 
    148 } // namespace android
    149 
    150 #endif // ANDROID_GUI_CPUCONSUMER_H
    151