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