1 /* 2 * Copyright © 2018, 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 /* Number of bytes to align AND pad picture memory buffers by, so that SIMD 38 * implementations can over-read by a few bytes, and use aligned read/write 39 * instructions. */ 40 #define DAV1D_PICTURE_ALIGNMENT 64 41 42 typedef struct Dav1dPictureParameters { 43 int w; ///< width (in pixels) 44 int h; ///< height (in pixels) 45 enum Dav1dPixelLayout layout; ///< format of the picture 46 int bpc; ///< bits per pixel component (8 or 10) 47 } Dav1dPictureParameters; 48 49 typedef struct Dav1dPicture { 50 Dav1dSequenceHeader *seq_hdr; 51 Dav1dFrameHeader *frame_hdr; 52 53 /** 54 * Pointers to planar image data (Y is [0], U is [1], V is [2]). The data 55 * should be bytes (for 8 bpc) or words (for 10 bpc). In case of words 56 * containing 10 bpc image data, the pixels should be located in the LSB 57 * bits, so that values range between [0, 1023]; the upper bits should be 58 * zero'ed out. 59 */ 60 void *data[3]; 61 62 /** 63 * Number of bytes between 2 lines in data[] for luma [0] or chroma [1]. 64 */ 65 ptrdiff_t stride[2]; 66 67 Dav1dPictureParameters p; 68 Dav1dDataProps m; 69 70 /** 71 * High Dynamic Range Content Light Level metadata applying to this picture, 72 * as defined in section 5.8.3 and 6.7.3 73 */ 74 Dav1dContentLightLevel *content_light; 75 /** 76 * High Dynamic Range Mastering Display Color Volume metadata applying to 77 * this picture, as defined in section 5.8.4 and 6.7.4 78 */ 79 Dav1dMasteringDisplay *mastering_display; 80 /** 81 * ITU-T T.35 metadata as defined in section 5.8.2 and 6.7.2 82 */ 83 Dav1dITUTT35 *itut_t35; 84 85 uintptr_t reserved[4]; ///< reserved for future use 86 87 struct Dav1dRef *frame_hdr_ref, *seq_hdr_ref; ///< Frame parameter allocation origins 88 struct Dav1dRef *content_light_ref, *mastering_display_ref, *itut_t35_ref; ///< Metadata allocation origins 89 uintptr_t reserved_ref[4]; ///< reserved for future use 90 struct Dav1dRef *ref; ///< Frame data allocation origin 91 92 void *allocator_data; ///< pointer managed by the allocator 93 } Dav1dPicture; 94 95 typedef struct Dav1dPicAllocator { 96 void *cookie; ///< custom data to pass to the allocator callbacks. 97 /** 98 * Allocate the picture buffer based on the Dav1dPictureParameters. 99 * 100 * The data[0], data[1] and data[2] must be DAV1D_PICTURE_ALIGNMENT byte 101 * aligned and with a pixel width/height multiple of 128 pixels. Any 102 * allocated memory area should also be padded by DAV1D_PICTURE_ALIGNMENT 103 * bytes. 104 * data[1] and data[2] must share the same stride[1]. 105 * 106 * This function will be called on the main thread (the thread which calls 107 * dav1d_get_picture()). 108 * 109 * @param pic The picture to allocate the buffer for. The callback needs to 110 * fill the picture data[0], data[1], data[2], stride[0] and 111 * stride[1]. 112 * The allocator can fill the pic allocator_data pointer with 113 * a custom pointer that will be passed to 114 * release_picture_callback(). 115 * @param cookie Custom pointer passed to all calls. 116 * 117 * @note No fields other than data, stride and allocator_data must be filled 118 * by this callback. 119 * @return 0 on success. A negative DAV1D_ERR value on error. 120 */ 121 int (*alloc_picture_callback)(Dav1dPicture *pic, void *cookie); 122 /** 123 * Release the picture buffer. 124 * 125 * If frame threading is used, this function may be called by the main 126 * thread (the thread which calls dav1d_get_picture()) or any of the frame 127 * threads and thus must be thread-safe. If frame threading is not used, 128 * this function will only be called on the main thread. 129 * 130 * @param pic The picture that was filled by alloc_picture_callback(). 131 * @param cookie Custom pointer passed to all calls. 132 */ 133 void (*release_picture_callback)(Dav1dPicture *pic, void *cookie); 134 } Dav1dPicAllocator; 135 136 /** 137 * Release reference to a picture. 138 */ 139 DAV1D_API void dav1d_picture_unref(Dav1dPicture *p); 140 141 #endif /* DAV1D_PICTURE_H */ 142