1 /*
2  * Copyright 2024 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 package androidx.compose.ui.graphics.layer
18 
19 import androidx.compose.runtime.Immutable
20 
21 /**
22  * Determines when to render the contents of a layer into an offscreen buffer before being drawn to
23  * the destination.
24  */
25 @Immutable
26 @kotlin.jvm.JvmInline
27 value class CompositingStrategy internal constructor(@Suppress("unused") private val value: Int) {
28 
29     companion object {
30 
31         /**
32          * Rendering to an offscreen buffer will be determined automatically by the rest of the
33          * graphicsLayer parameters. This is the default behavior. For example, whenever an alpha
34          * value less than 1.0f is provided on [Modifier.graphicsLayer], a compositing layer is
35          * created automatically to first render the contents fully opaque, then draw this offscreen
36          * buffer to the destination with the corresponding alpha. This is necessary for correctness
37          * otherwise alpha applied to individual drawing instructions that overlap will have a
38          * different result than expected. Additionally usage of [RenderEffect] on the graphicsLayer
39          * will also render into an intermediate offscreen buffer before being drawn into the
40          * destination.
41          */
42         val Auto = CompositingStrategy(0)
43 
44         /**
45          * Rendering of content will always be rendered into an offscreen buffer first then drawn to
46          * the destination regardless of the other parameters configured on the graphics layer. This
47          * is useful for leveraging different blending algorithms for masking content. For example,
48          * the contents can be drawn into this graphics layer and masked out by drawing additional
49          * shapes with [BlendMode.Clear]
50          */
51         val Offscreen = CompositingStrategy(1)
52 
53         /**
54          * Modulates alpha for each of the drawing instructions recorded within the graphicsLayer.
55          * This avoids usage of an offscreen buffer for purposes of alpha rendering. [ModulateAlpha]
56          * is more efficient than [Auto] in performance in scenarios where an alpha value less than
57          * 1.0f is provided. Otherwise the performance is similar to that of [Auto]. However, this
58          * can provide different results than [Auto] if there is overlapping content within the
59          * layer and alpha is applied. This should only be used if the contents of the layer are
60          * known well in advance and are expected to not be overlapping.
61          */
62         val ModulateAlpha = CompositingStrategy(2)
63     }
64 }
65