1/*
2 * Copyright (C) 2007 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_SURFACE_CONTROL_H
18#define ANDROID_GUI_SURFACE_CONTROL_H
19
20#include <stdint.h>
21#include <sys/types.h>
22
23#include <utils/KeyedVector.h>
24#include <utils/RefBase.h>
25#include <utils/threads.h>
26
27#include <ui/FrameStats.h>
28#include <ui/PixelFormat.h>
29#include <ui/Region.h>
30
31#include <gui/ISurfaceComposerClient.h>
32
33namespace android {
34
35// ---------------------------------------------------------------------------
36
37class IGraphicBufferProducer;
38class Surface;
39class SurfaceComposerClient;
40
41// ---------------------------------------------------------------------------
42
43class SurfaceControl : public RefBase
44{
45public:
46    static bool isValid(const sp<SurfaceControl>& surface) {
47        return (surface != 0) && surface->isValid();
48    }
49
50    bool isValid() {
51        return mHandle!=0 && mClient!=0;
52    }
53
54    static bool isSameSurface(
55            const sp<SurfaceControl>& lhs, const sp<SurfaceControl>& rhs);
56
57    // release surface data from java
58    void        clear();
59
60    // disconnect any api that's connected
61    void        disconnect();
62
63    status_t    setLayerStack(uint32_t layerStack);
64    status_t    setLayer(int32_t layer);
65
66    // Sets a Z order relative to the Surface specified by "relativeTo" but
67    // without becoming a full child of the relative. Z-ordering works exactly
68    // as if it were a child however.
69    //
70    // As a nod to sanity, only non-child surfaces may have a relative Z-order.
71    //
72    // This overrides any previous and is overriden by any future calls
73    // to setLayer.
74    //
75    // If the relative dissapears, the Surface will have no layer and be
76    // invisible, until the next time set(Relative)Layer is called.
77    //
78    // TODO: This is probably a hack. Currently it exists only to work around
79    // some framework usage of the hidden APPLICATION_MEDIA_OVERLAY window type
80    // which allows inserting a window between a SurfaceView and it's main application
81    // window. However, since we are using child windows for the SurfaceView, but not using
82    // child windows elsewhere in O, the WindowManager can't set the layer appropriately.
83    // This is only used by the "TvInputService" and following the port of ViewRootImpl
84    // to child surfaces, we can then port this and remove this method.
85    status_t    setRelativeLayer(const sp<IBinder>& relativeTo, int32_t layer);
86    status_t    setPosition(float x, float y);
87    status_t    setSize(uint32_t w, uint32_t h);
88    status_t    hide();
89    status_t    show();
90    status_t    setFlags(uint32_t flags, uint32_t mask);
91    status_t    setTransparentRegionHint(const Region& transparent);
92    status_t    setAlpha(float alpha=1.0f);
93    status_t    setMatrix(float dsdx, float dtdx, float dtdy, float dsdy);
94    status_t    setCrop(const Rect& crop);
95    status_t    setFinalCrop(const Rect& crop);
96
97    // If the size changes in this transaction, all geometry updates specified
98    // in this transaction will not complete until a buffer of the new size
99    // arrives. As some elements normally apply immediately, this enables
100    // freezing the total geometry of a surface until a resize is completed.
101    status_t    setGeometryAppliesWithResize();
102
103    // Defers applying any changes made in this transaction until the Layer
104    // identified by handle reaches the given frameNumber. If the Layer identified
105    // by handle is removed, then we will apply this transaction regardless of
106    // what frame number has been reached.
107    status_t deferTransactionUntil(const sp<IBinder>& handle, uint64_t frameNumber);
108
109    // A variant of deferTransactionUntil which identifies the Layer we wait for by
110    // Surface instead of Handle. Useful for clients which may not have the
111    // SurfaceControl for some of their Surfaces. Otherwise behaves identically.
112    status_t deferTransactionUntil(const sp<Surface>& barrier, uint64_t frameNumber);
113
114    // Reparents all children of this layer to the new parent handle.
115    status_t reparentChildren(const sp<IBinder>& newParentHandle);
116
117    // Detaches all child surfaces (and their children recursively)
118    // from their SurfaceControl.
119    // The child SurfaceControl's will not throw exceptions or return errors,
120    // but transactions will have no effect.
121    // The child surfaces will continue to follow their parent surfaces,
122    // and remain eligible for rendering, but their relative state will be
123    // frozen. We use this in the WindowManager, in app shutdown/relaunch
124    // scenarios, where the app would otherwise clean up its child Surfaces.
125    // Sometimes the WindowManager needs to extend their lifetime slightly
126    // in order to perform an exit animation or prevent flicker.
127    status_t detachChildren();
128
129    // Set an override scaling mode as documented in <system/window.h>
130    // the override scaling mode will take precedence over any client
131    // specified scaling mode. -1 will clear the override scaling mode.
132    status_t setOverrideScalingMode(int32_t overrideScalingMode);
133
134    static status_t writeSurfaceToParcel(
135            const sp<SurfaceControl>& control, Parcel* parcel);
136
137    sp<Surface> getSurface() const;
138    sp<Surface> createSurface() const;
139    sp<IBinder> getHandle() const;
140
141    status_t clearLayerFrameStats() const;
142    status_t getLayerFrameStats(FrameStats* outStats) const;
143
144private:
145    // can't be copied
146    SurfaceControl& operator = (SurfaceControl& rhs);
147    SurfaceControl(const SurfaceControl& rhs);
148
149    friend class SurfaceComposerClient;
150    friend class Surface;
151
152    SurfaceControl(
153            const sp<SurfaceComposerClient>& client,
154            const sp<IBinder>& handle,
155            const sp<IGraphicBufferProducer>& gbp);
156
157    ~SurfaceControl();
158
159    sp<Surface> generateSurfaceLocked() const;
160    status_t validate() const;
161    void destroy();
162
163    sp<SurfaceComposerClient>   mClient;
164    sp<IBinder>                 mHandle;
165    sp<IGraphicBufferProducer>  mGraphicBufferProducer;
166    mutable Mutex               mLock;
167    mutable sp<Surface>         mSurfaceData;
168};
169
170}; // namespace android
171
172#endif // ANDROID_GUI_SURFACE_CONTROL_H
173