1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
|
/**
* Copyright (c) 2021, The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.graphics.composer3;
import android.hardware.graphics.composer3.Buffer;
import android.hardware.graphics.composer3.ClientTarget;
import android.hardware.graphics.composer3.ClockMonotonicTimestamp;
import android.hardware.graphics.composer3.DisplayBrightness;
import android.hardware.graphics.composer3.LayerCommand;
@VintfStability
parcelable DisplayCommand {
/**
* The display which this commands refers to.
* @see IComposer.createDisplay
*/
long display;
/**
* Sets layer commands for this display.
* @see LayerCommand.
*/
LayerCommand[] layers;
/**
* Sets a color transform which will be applied after composition.
*
* If the device is not capable of either using the matrix to
* apply the desired color transform, it must force all layers to client
* composition during VALIDATE_DISPLAY.
*
* If Capability.SKIP_CLIENT_COLOR_TRANSFORM is present, then
* the client must never apply the color transform during client
* composition, even if all layers are being composed by the client.
*
* The matrix provided is an affine color transformation of the following
* form:
*
* |r.r r.g r.b 0|
* |g.r g.g g.b 0|
* |b.r b.g b.b 0|
* |Tr Tg Tb 1|
*
* This matrix must be provided in row-major form:
*
* {r.r, r.g, r.b, 0, g.r, ...}.
*
* Given a matrix of this form and an input color [R_in, G_in, B_in], the
* output color [R_out, G_out, B_out] will be:
*
* R_out = R_in * r.r + G_in * g.r + B_in * b.r + Tr
* G_out = R_in * r.g + G_in * g.g + B_in * b.g + Tg
* B_out = R_in * r.b + G_in * g.b + B_in * b.b + Tb
*
*/
@nullable float[] colorTransformMatrix;
/**
* Sets the desired brightness of the display.
*
* Ideally, the brightness of the display will take effect within this frame so that it can be
* aligned with color transforms. Some display architectures may take multiple frames to apply
* the display brightness, for example when internally switching the display between multiple
* power modes to achieve higher luminance. In those cases, the underlying display panel's real
* brightness may not be applied atomically; however, layer dimming when mixing HDR and SDR
* content must be synchronized.
*
* As an illustrative example: suppose two layers have white
* points of 200 nits and 1000 nits respectively, the old display luminance is 200 nits, and the
* new display luminance is 1000 nits. If the new display luminance takes two frames to apply,
* then: In the first frame, there must not be any relative dimming of layers (treat both layers
* as 200 nits as the maximum luminance of the display is 200 nits). In the second frame, there
* dimming should be applied to ensure that the first layer does not become perceptually
* brighter during the transition.
*
* The display luminance must be updated by this command even if there is not pending validate
* or present command.
*/
@nullable DisplayBrightness brightness;
/**
* Sets the buffer handle which will receive the output of client
* composition. Layers marked as Composition.CLIENT must be composited
* into this buffer prior to the call to PRESENT_DISPLAY, and layers not
* marked as Composition.CLIENT must be composited with this buffer by
* the device.
*
* The buffer handle provided may be empty if no layers are being
* composited by the client. This must not result in an error (unless an
* invalid display handle is also provided).
*
* Also provides a file descriptor referring to an acquire sync fence
* object, which must be signaled when it is safe to read from the client
* target buffer. If it is already safe to read from this buffer, an
* empty handle may be passed instead.
*
* For more about dataspaces, see SET_LAYER_DATASPACE.
*
* The damage parameter describes a surface damage region as defined in
* the description of SET_LAYER_SURFACE_DAMAGE.
*
* Will be called before PRESENT_DISPLAY if any of the layers are marked
* as Composition.CLIENT. If no layers are so marked, then it is not
* necessary to call this function. It is not necessary to call
* validateDisplay after changing the target through this function.
*/
@nullable ClientTarget clientTarget;
/**
* Sets the output buffer for a virtual display. That is, the buffer to
* which the composition result will be written.
*
* Also provides a file descriptor referring to a release sync fence
* object, which must be signaled when it is safe to write to the output
* buffer. If it is already safe to write to the output buffer, an empty
* handle may be passed instead.
*
* Must be called at least once before PRESENT_DISPLAY, but does not have
* any interaction with layer state or display validation.
*/
@nullable Buffer virtualDisplayOutputBuffer;
/**
* Sets the expected present time to present the current content on screen.
* The implementation should try to present the display as close as possible
* to the given expectedPresentTime. If expectedPresentTime is 0, the
* implementation should present the display as soon as possible.
*/
@nullable ClockMonotonicTimestamp expectedPresentTime;
/**
* Instructs the device to inspect all of the layer state and determine if
* there are any composition type changes necessary before presenting the
* display. Permitted changes are described in the definition of
* Composition above.
*/
boolean validateDisplay;
/**
* Accepts the changes required by the device from the previous
* validateDisplay call (which may be queried using
* getChangedCompositionTypes) and revalidates the display. This function
* is equivalent to requesting the changed types from
* getChangedCompositionTypes, setting those types on the corresponding
* layers, and then calling validateDisplay again.
*
* After this call it must be valid to present this display. Calling this
* after validateDisplay returns 0 changes must succeed with NONE, but
* must have no other effect.
*/
boolean acceptDisplayChanges;
/**
* Presents the current display contents on the screen (or in the case of
* virtual displays, into the output buffer).
*
* Prior to calling this function, the display must be successfully
* validated with validateDisplay. Note that setLayerBuffer and
* setLayerSurfaceDamage specifically do not count as layer state, so if
* there are no other changes to the layer state (or to the buffer's
* properties as described in setLayerBuffer), then it is safe to call
* this function without first validating the display.
*/
boolean presentDisplay;
/**
* Presents the current display contents on the screen (or in the case of
* virtual displays, into the output buffer) if validate can be skipped,
* or perform a VALIDATE_DISPLAY action instead.
*/
boolean presentOrValidateDisplay;
}
|
