libgui: add docs to geometry states and captureScreen
I think captureScreen is a bit fishy. We want it to capture the
logical display, but neither of the framework or surfaceflinger is
ready.
Bug: 113041375
Test: builds
Change-Id: Id5c76a4551e5260e83e64f0ca3ed2afaa34eecb5
diff --git a/libs/gui/include/gui/ISurfaceComposer.h b/libs/gui/include/gui/ISurfaceComposer.h
index 98ec338..8df2f03 100644
--- a/libs/gui/include/gui/ISurfaceComposer.h
+++ b/libs/gui/include/gui/ISurfaceComposer.h
@@ -171,8 +171,25 @@
virtual status_t setActiveColorMode(const sp<IBinder>& display,
ui::ColorMode colorMode) = 0;
- /* Capture the specified screen. requires READ_FRAME_BUFFER permission
- * This function will fail if there is a secure window on screen.
+ /**
+ * Capture the specified screen. This requires READ_FRAME_BUFFER
+ * permission. This function will fail if there is a secure window on
+ * screen.
+ *
+ * This function can capture a subregion (the source crop) of the screen.
+ * The subregion can be optionally rotated. It will also be scaled to
+ * match the size of the output buffer.
+ *
+ * At the moment, sourceCrop is ignored and is always set to the visible
+ * region (projected display viewport) of the screen.
+ *
+ * reqWidth and reqHeight specifies the size of the buffer. When either
+ * of them is 0, they are set to the size of the logical display viewport.
+ *
+ * When useIdentityTransform is true, layer transformations are disabled.
+ *
+ * rotation specifies the rotation of the source crop (and the pixels in
+ * it) around its center.
*/
virtual status_t captureScreen(const sp<IBinder>& display, sp<GraphicBuffer>* outBuffer,
Rect sourceCrop, uint32_t reqWidth, uint32_t reqHeight,
diff --git a/libs/gui/include/gui/LayerState.h b/libs/gui/include/gui/LayerState.h
index 0859aff..9a9f633 100644
--- a/libs/gui/include/gui/LayerState.h
+++ b/libs/gui/include/gui/LayerState.h
@@ -183,10 +183,24 @@
sp<IBinder> token;
sp<IGraphicBufferProducer> surface;
uint32_t layerStack;
+
+ // These states define how layers are projected onto the physical display.
+ //
+ // Layers are first clipped to `viewport'. They are then translated and
+ // scaled from `viewport' to `frame'. Finally, they are rotated according
+ // to `orientation', `width', and `height'.
+ //
+ // For example, assume viewport is Rect(0, 0, 200, 100), frame is Rect(20,
+ // 10, 420, 210), and the size of the display is WxH. When orientation is
+ // 0, layers will be scaled by a factor of 2 and translated by (20, 10).
+ // When orientation is 1, layers will be additionally rotated by 90
+ // degrees around the origin clockwise and translated by (W, 0).
uint32_t orientation;
Rect viewport;
Rect frame;
+
uint32_t width, height;
+
status_t write(Parcel& output) const;
status_t read(const Parcel& input);
};