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