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