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         uint64_t    frameNumber;
     57         // Values below are only valid when using
     58         // HAL_PIXEL_FORMAT_YCbCr_420_888, in which case LockedBuffer::data
     59         // contains the Y channel, and stride is the Y channel stride. For other
     60         // formats, these will all be 0.
     61         uint8_t    *dataCb;
     62         uint8_t    *dataCr;
     63         uint32_t    chromaStride;
     64         uint32_t    chromaStep;
     65     };
     66 
     67     // Create a new CPU consumer. The maxLockedBuffers parameter specifies
     68     // how many buffers can be locked for user access at the same time.
     69     CpuConsumer(const sp<IGraphicBufferConsumer>& bq,
     70             uint32_t maxLockedBuffers, bool controlledByApp = false);
     71 
     72     virtual ~CpuConsumer();
     73 
     74     // set the name of the CpuConsumer that will be used to identify it in
     75     // log messages.
     76     void setName(const String8& name);
     77 
     78     // setDefaultBufferSize is used to set the size of buffers returned by
     79     // requestBuffers when a width and height of zero is requested.
     80     // A call to setDefaultBufferSize() may trigger requestBuffers() to
     81     // be called from the client. Default size is 1x1.
     82     status_t setDefaultBufferSize(uint32_t width, uint32_t height);
     83 
     84     // setDefaultBufferFormat allows CpuConsumer's BufferQueue to create buffers
     85     // of a defaultFormat if no format is specified by producer. Formats are
     86     // enumerated in graphics.h; the initial default is
     87     // HAL_PIXEL_FORMAT_RGBA_8888.
     88     status_t setDefaultBufferFormat(uint32_t defaultFormat);
     89 
     90     // Gets the next graphics buffer from the producer and locks it for CPU use,
     91     // filling out the passed-in locked buffer structure with the native pointer
     92     // and metadata. Returns BAD_VALUE if no new buffer is available, and
     93     // NOT_ENOUGH_DATA if the maximum number of buffers is already locked.
     94     //
     95     // Only a fixed number of buffers can be locked at a time, determined by the
     96     // construction-time maxLockedBuffers parameter. If INVALID_OPERATION is
     97     // returned by lockNextBuffer, then old buffers must be returned to the queue
     98     // by calling unlockBuffer before more buffers can be acquired.
     99     status_t lockNextBuffer(LockedBuffer *nativeBuffer);
    100 
    101     // Returns a locked buffer to the queue, allowing it to be reused. Since
    102     // only a fixed number of buffers may be locked at a time, old buffers must
    103     // be released by calling unlockBuffer to ensure new buffers can be acquired by
    104     // lockNextBuffer.
    105     status_t unlockBuffer(const LockedBuffer &nativeBuffer);
    106 
    107   private:
    108     // Maximum number of buffers that can be locked at a time
    109     uint32_t mMaxLockedBuffers;
    110 
    111     status_t releaseAcquiredBufferLocked(int lockedIdx);
    112 
    113     virtual void freeBufferLocked(int slotIndex);
    114 
    115     // Tracking for buffers acquired by the user
    116     struct AcquiredBuffer {
    117         // Need to track the original mSlot index and the buffer itself because
    118         // the mSlot entry may be freed/reused before the acquired buffer is
    119         // released.
    120         int mSlot;
    121         sp<GraphicBuffer> mGraphicBuffer;
    122         void *mBufferPointer;
    123 
    124         AcquiredBuffer() :
    125                 mSlot(BufferQueue::INVALID_BUFFER_SLOT),
    126                 mBufferPointer(NULL) {
    127         }
    128     };
    129     Vector<AcquiredBuffer> mAcquiredBuffers;
    130 
    131     // Count of currently locked buffers
    132     uint32_t mCurrentLockedBuffers;
    133 
    134 };
    135 
    136 } // namespace android
    137 
    138 #endif // ANDROID_GUI_CPUCONSUMER_H
    139