1+ /*
2+ * Copyright (C) 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+ /**
18+ * @addtogroup NativeActivity Native Activity
19+ * @{
20+ */
21+
22+ /**
23+ * @file display_luts.h
24+ */
25+ #pragma once
26+
27+ #include <inttypes.h>
28+
29+ __BEGIN_DECLS
30+
31+ /**
32+ * The dimension of the lut
33+ */
34+ enum ADisplayLuts_Dimension : int32_t {
35+ ADISPLAYLUTS_ONE_DIMENSION = 1 ,
36+ ADISPLAYLUTS_THREE_DIMENSION = 3 ,
37+ };
38+ typedef enum ADisplayLuts_Dimension ADisplayLuts_Dimension ;
39+
40+ /**
41+ * The sampling key used by the lut
42+ */
43+ enum ADisplayLuts_SamplingKey : int32_t {
44+ ADISPLAYLUTS_SAMPLINGKEY_RGB = 0 ,
45+ ADISPLAYLUTS_SAMPLINGKEY_MAX_RGB = 1 ,
46+ };
47+ typedef enum ADisplayLuts_SamplingKey ADisplayLuts_SamplingKey ;
48+
49+ /**
50+ * Used to get and set display luts entry
51+ */
52+ typedef struct ADisplayLutsEntry ADisplayLutsEntry ;
53+
54+ /**
55+ * Used to get and set display luts
56+ */
57+ typedef struct ADisplayLuts ADisplayLuts ;
58+
59+ /**
60+ * Creates a \a ADisplayLutsEntry entry.
61+ *
62+ * You are responsible for mamanging the memory of the returned object.
63+ * Always call \a ADisplayLutsEntry_destroy to release it after use.
64+ *
65+ * Functions like \a ADisplayLuts_set create their own copies of entries,
66+ * therefore they don't take the ownership of the instance created by
67+ * \a ADisplayLutsEntry_create.
68+ *
69+ * @param buffer The lut raw buffer. The function creates a copy of it and does not need to
70+ * outlive the life of the ADisplayLutsEntry.
71+ * @param length The length of lut raw buffer
72+ * @param dimension The dimension of the lut. see \a ADisplayLuts_Dimension
73+ * @param key The sampling key used by the lut. see \a ADisplayLuts_SamplingKey
74+ * @return a new \a ADisplayLutsEntry instance.
75+ */
76+ ADisplayLutsEntry * _Nonnull ADisplayLutsEntry_createEntry (float * _Nonnull buffer ,
77+ int32_t length , int32_t dimension , int32_t key ) __INTRODUCED_IN (36 );
78+
79+ /**
80+ * Destroy the \a ADisplayLutsEntry instance.
81+ *
82+ * @param entry The entry to be destroyed
83+ */
84+ void ADisplayLutsEntry_destroy (ADisplayLutsEntry * _Nullable entry ) __INTRODUCED_IN (36 );
85+
86+ /**
87+ * Gets the dimension of the entry.
88+ *
89+ * The function is only valid for the lifetime of the `entry`.
90+ *
91+ * @param entry The entry to query
92+ * @return the dimension of the lut
93+ */
94+ ADisplayLuts_Dimension ADisplayLutsEntry_getDimension (const ADisplayLutsEntry * _Nonnull entry )
95+ __INTRODUCED_IN (36 );
96+
97+ /**
98+ * Gets the size for each dimension of the entry.
99+ *
100+ * The function is only valid for the lifetime of the `entry`.
101+ *
102+ * @param entry The entry to query
103+ * @return the size of each dimension of the lut
104+ */
105+ int32_t ADisplayLutsEntry_getSize (const ADisplayLutsEntry * _Nonnull entry )
106+ __INTRODUCED_IN (36 );
107+
108+ /**
109+ * Gets the sampling key used by the entry.
110+ *
111+ * The function is only valid for the lifetime of the `entry`.
112+ *
113+ * @param entry The entry to query
114+ * @return the sampling key used by the lut
115+ */
116+ ADisplayLuts_SamplingKey ADisplayLutsEntry_getSamplingKey (const ADisplayLutsEntry * _Nonnull entry )
117+ __INTRODUCED_IN (36 );
118+
119+ /**
120+ * Gets the lut buffer of the entry.
121+ *
122+ * The function is only valid for the lifetime of the `entry`.
123+ *
124+ * @param entry The entry to query
125+ * @return a pointer to the raw lut buffer
126+ */
127+ const float * _Nonnull ADisplayLutsEntry_getBuffer (const ADisplayLutsEntry * _Nonnull entry )
128+ __INTRODUCED_IN (36 );
129+
130+ /**
131+ * Creates a \a ADisplayLuts instance.
132+ *
133+ * You are responsible for mamanging the memory of the returned object.
134+ * Always call \a ADisplayLuts_destroy to release it after use. E.g., after calling
135+ * the function \a ASurfaceTransaction_setLuts.
136+ *
137+ * @return a new \a ADisplayLuts instance
138+ */
139+ ADisplayLuts * _Nonnull ADisplayLuts_create () __INTRODUCED_IN (36 );
140+
141+ /**
142+ * Sets Luts in order to be applied.
143+ *
144+ * The function accepts a single 1D Lut, or a single 3D Lut or both 1D and 3D Lut in order.
145+ * And the function will replace any previously set lut(s).
146+ * If you want to clear the previously set lut(s), set `entries` to be nullptr,
147+ * and `numEntries` will be internally ignored.
148+ *
149+ * @param luts the pointer of the \a ADisplayLuts instance
150+ * @param entries the pointer of the array of lut entries to be applied
151+ * @param numEntries the number of lut entries. The value should be either 1 or 2.
152+ */
153+ void ADisplayLuts_setEntries (ADisplayLuts * _Nonnull luts ,
154+ ADisplayLutsEntry * _Nullable * _Nullable entries , int32_t numEntries ) __INTRODUCED_IN (36 );
155+
156+ /**
157+ * Deletes the \a ADisplayLuts instance.
158+ *
159+ * @param luts The luts to be destroyed
160+ */
161+ void ADisplayLuts_destroy (ADisplayLuts * _Nullable luts ) __INTRODUCED_IN (36 );
162+
163+ __END_DECLS
164+
165+ /** @} */
0 commit comments