1 /* 2 * Copyright © 2018-2020, VideoLAN and dav1d authors 3 * Copyright © 2018, Two Orioles, LLC 4 * All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions are met: 8 * 9 * 1. Redistributions of source code must retain the above copyright notice, this 10 * list of conditions and the following disclaimer. 11 * 12 * 2. Redistributions in binary form must reproduce the above copyright notice, 13 * this list of conditions and the following disclaimer in the documentation 14 * and/or other materials provided with the distribution. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 17 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 18 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 19 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR 20 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 21 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 22 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 23 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 25 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 */ 27 28 #ifndef DAV1D_PICTURE_H 29 #define DAV1D_PICTURE_H 30 31 #include <stddef.h> 32 #include <stdint.h> 33 34 #include "common.h" 35 #include "headers.h" 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 /* Number of bytes to align AND pad picture memory buffers by, so that SIMD 42 * implementations can over-read by a few bytes, and use aligned read/write 43 * instructions. */ 44 #define DAV1D_PICTURE_ALIGNMENT 64 45 46 typedef struct Dav1dPictureParameters { 47 int w; ///< width (in pixels) 48 int h; ///< height (in pixels) 49 enum Dav1dPixelLayout layout; ///< format of the picture 50 int bpc; ///< bits per pixel component (8 or 10) 51 } Dav1dPictureParameters; 52 53 typedef struct Dav1dPicture { 54 Dav1dSequenceHeader *seq_hdr; 55 Dav1dFrameHeader *frame_hdr; 56 57 /** 58 * Pointers to planar image data (Y is [0], U is [1], V is [2]). The data 59 * should be bytes (for 8 bpc) or words (for 10 bpc). In case of words 60 * containing 10 bpc image data, the pixels should be located in the LSB 61 * bits, so that values range between [0, 1023]; the upper bits should be 62 * zero'ed out. 63 */ 64 void *data[3]; 65 66 /** 67 * Number of bytes between 2 lines in data[] for luma [0] or chroma [1]. 68 */ 69 ptrdiff_t stride[2]; 70 71 Dav1dPictureParameters p; 72 Dav1dDataProps m; 73 74 /** 75 * High Dynamic Range Content Light Level metadata applying to this picture, 76 * as defined in section 5.8.3 and 6.7.3 77 */ 78 Dav1dContentLightLevel *content_light; 79 /** 80 * High Dynamic Range Mastering Display Color Volume metadata applying to 81 * this picture, as defined in section 5.8.4 and 6.7.4 82 */ 83 Dav1dMasteringDisplay *mastering_display; 84 /** 85 * Array of ITU-T T.35 metadata as defined in section 5.8.2 and 6.7.2 86 */ 87 Dav1dITUTT35 *itut_t35; 88 89 /** 90 * Number of ITU-T T35 metadata entries in the array 91 */ 92 size_t n_itut_t35; 93 94 uintptr_t reserved[4]; ///< reserved for future use 95 96 struct Dav1dRef *frame_hdr_ref; ///< Dav1dFrameHeader allocation origin 97 struct Dav1dRef *seq_hdr_ref; ///< Dav1dSequenceHeader allocation origin 98 struct Dav1dRef *content_light_ref; ///< Dav1dContentLightLevel allocation origin 99 struct Dav1dRef *mastering_display_ref; ///< Dav1dMasteringDisplay allocation origin 100 struct Dav1dRef *itut_t35_ref; ///< Dav1dITUTT35 allocation origin 101 uintptr_t reserved_ref[4]; ///< reserved for future use 102 struct Dav1dRef *ref; ///< Frame data allocation origin 103 104 void *allocator_data; ///< pointer managed by the allocator 105 } Dav1dPicture; 106 107 typedef struct Dav1dPicAllocator { 108 void *cookie; ///< custom data to pass to the allocator callbacks. 109 /** 110 * Allocate the picture buffer based on the Dav1dPictureParameters. 111 * 112 * The data[0], data[1] and data[2] must be DAV1D_PICTURE_ALIGNMENT byte 113 * aligned and with a pixel width/height multiple of 128 pixels. Any 114 * allocated memory area should also be padded by DAV1D_PICTURE_ALIGNMENT 115 * bytes. 116 * data[1] and data[2] must share the same stride[1]. 117 * 118 * This function will be called on the main thread (the thread which calls 119 * dav1d_get_picture()). 120 * 121 * @param pic The picture to allocate the buffer for. The callback needs to 122 * fill the picture data[0], data[1], data[2], stride[0] and 123 * stride[1]. 124 * The allocator can fill the pic allocator_data pointer with 125 * a custom pointer that will be passed to 126 * release_picture_callback(). 127 * @param cookie Custom pointer passed to all calls. 128 * 129 * @note No fields other than data, stride and allocator_data must be filled 130 * by this callback. 131 * @return 0 on success. A negative DAV1D_ERR value on error. 132 */ 133 int (*alloc_picture_callback)(Dav1dPicture *pic, void *cookie); 134 /** 135 * Release the picture buffer. 136 * 137 * If frame threading is used, this function may be called by the main 138 * thread (the thread which calls dav1d_get_picture()) or any of the frame 139 * threads and thus must be thread-safe. If frame threading is not used, 140 * this function will only be called on the main thread. 141 * 142 * @param pic The picture that was filled by alloc_picture_callback(). 143 * @param cookie Custom pointer passed to all calls. 144 */ 145 void (*release_picture_callback)(Dav1dPicture *pic, void *cookie); 146 } Dav1dPicAllocator; 147 148 /** 149 * Release reference to a picture. 150 */ 151 DAV1D_API void dav1d_picture_unref(Dav1dPicture *p); 152 153 #ifdef __cplusplus 154 } /* extern "C" */ 155 #endif 156 157 #endif /* DAV1D_PICTURE_H */ 158