1 /* 2 * Copyright (c) 2022, Alliance for Open Media. All rights reserved. 3 * 4 * This source code is subject to the terms of the BSD 2 Clause License and 5 * the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License 6 * was not distributed with this source code in the LICENSE file, you can 7 * obtain it at www.aomedia.org/license/software. If the Alliance for Open 8 * Media Patent License 1.0 was not distributed with this source code in the 9 * PATENTS file, you can obtain it at www.aomedia.org/license/patent. 10 */ 11 12 #ifndef AOM_AOM_DSP_PYRAMID_H_ 13 #define AOM_AOM_DSP_PYRAMID_H_ 14 15 #include <stddef.h> 16 #include <stdint.h> 17 #include <stdbool.h> 18 19 #include "config/aom_config.h" 20 21 #include "aom_scale/yv12config.h" 22 #include "aom_util/aom_pthread.h" 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 // Minimum dimensions of a downsampled image 29 #define MIN_PYRAMID_SIZE_LOG2 3 30 #define MIN_PYRAMID_SIZE (1 << MIN_PYRAMID_SIZE_LOG2) 31 32 // Size of border around each pyramid image, in pixels 33 // Similarly to the border around regular image buffers, this border is filled 34 // with copies of the outermost pixels of the frame, to allow for more efficient 35 // convolution code 36 // TODO(rachelbarker): How many pixels do we actually need here? 37 // I think we only need 9 for disflow, but how many for corner matching? 38 #define PYRAMID_PADDING 16 39 40 // Byte alignment of each line within the image pyramids. 41 // That is, the first pixel inside the image (ie, not in the border region), 42 // on each row of each pyramid level, is aligned to this byte alignment. 43 // This value must be a power of 2. 44 #define PYRAMID_ALIGNMENT 32 45 46 typedef struct { 47 uint8_t *buffer; 48 int width; 49 int height; 50 int stride; 51 } PyramidLayer; 52 53 // Struct for an image pyramid 54 typedef struct image_pyramid { 55 #if CONFIG_MULTITHREAD 56 // Mutex which is used to prevent the pyramid being computed twice at the 57 // same time 58 // 59 // Semantics: 60 // * This mutex must be held whenever reading or writing the 61 // `filled_levels` field 62 // 63 // * This mutex must also be held while computing the image pyramid, 64 // to ensure that only one thread may do so at a time. 65 // 66 // * However, once you have read the filled_levels field and observed 67 // a value N, it is safe to drop the mutex and read from the remaining 68 // fields, including the first N pyramid levels (but no higher). 69 // Note that filled_levels must be read once and cached in a local variable 70 // in order for this to be safe - it cannot be re-read without retaking 71 // the mutex. 72 // 73 // This works because, once the image pyramid is computed, its contents 74 // will not be changed until the parent frame buffer is recycled, 75 // which will not happen until there are no more outstanding references 76 // to the frame buffer. 77 pthread_mutex_t mutex; 78 #endif 79 // Maximum number of levels for the given frame size 80 // We always allocate enough memory for this many levels, as the memory 81 // cost of higher levels of the pyramid is minimal. 82 int max_levels; 83 // Number of levels which currently hold valid data 84 int filled_levels; 85 // Pointer to allocated buffer 86 uint8_t *buffer_alloc; 87 // Data for each level 88 // The `buffer` pointers inside this array point into the region which 89 // is stored in the `buffer_alloc` field here 90 PyramidLayer *layers; 91 } ImagePyramid; 92 93 size_t aom_get_pyramid_alloc_size(int width, int height, bool image_is_16bit); 94 95 ImagePyramid *aom_alloc_pyramid(int width, int height, bool image_is_16bit); 96 97 // Fill out a downsampling pyramid for a given frame. 98 // 99 // The top level (index 0) will always be an 8-bit copy of the input frame, 100 // regardless of the input bit depth. Additional levels are then downscaled 101 // by powers of 2. 102 // 103 // This function will ensure that the first `n_levels` levels of the pyramid 104 // are filled, unless the frame is too small to have this many levels. 105 // In that case, we will fill all available levels and then stop. 106 // 107 // Returns the actual number of levels filled, capped at n_levels, 108 // or -1 on error. 109 int aom_compute_pyramid(const YV12_BUFFER_CONFIG *frame, int bit_depth, 110 int n_levels, ImagePyramid *pyr); 111 112 #ifndef NDEBUG 113 // Check if a pyramid has already been computed to at least n levels 114 // This is mostly a debug helper - as it is necessary to hold pyr->mutex 115 // while reading the number of already-computed levels, we cannot just write: 116 // assert(pyr->filled_levels >= n_levels); 117 // This function allows the check to be correctly written as: 118 // assert(aom_is_pyramid_valid(pyr, n_levels)); 119 // 120 // Note: This deliberately does not restrict n_levels based on the maximum 121 // number of permitted levels for the frame size. This allows the check to 122 // catch cases where the caller forgets to handle the case where 123 // max_levels is less than the requested number of levels 124 bool aom_is_pyramid_valid(ImagePyramid *pyr, int n_levels); 125 #endif 126 127 // Mark a pyramid as no longer containing valid data. 128 // This must be done whenever the corresponding frame buffer is reused 129 void aom_invalidate_pyramid(ImagePyramid *pyr); 130 131 // Release the memory associated with a pyramid 132 void aom_free_pyramid(ImagePyramid *pyr); 133 134 #ifdef __cplusplus 135 } 136 #endif 137 138 #endif // AOM_AOM_DSP_PYRAMID_H_ 139