1/*
2 * V4L2 context helper functions.
3 *
4 * Copyright (C) 2017 Alexis Ballier <aballier@gentoo.org>
5 * Copyright (C) 2017 Jorge Ramirez <jorge.ramirez-ortiz@linaro.org>
6 *
7 * This file is part of FFmpeg.
8 *
9 * FFmpeg is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public
11 * License as published by the Free Software Foundation; either
12 * version 2.1 of the License, or (at your option) any later version.
13 *
14 * FFmpeg is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with FFmpeg; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef AVCODEC_V4L2_CONTEXT_H
25#define AVCODEC_V4L2_CONTEXT_H
26
27#include <stdint.h>
28#include <linux/videodev2.h>
29
30#include "libavutil/pixfmt.h"
31#include "libavutil/frame.h"
32#include "libavutil/rational.h"
33#include "codec_id.h"
34#include "packet.h"
35#include "v4l2_buffers.h"
36
37typedef struct V4L2Context {
38    /**
39     * context name.
40     */
41    const char* name;
42
43    /**
44     * Type of this buffer context.
45     * See V4L2_BUF_TYPE_VIDEO_* in videodev2.h
46     * Readonly after init.
47     */
48    enum v4l2_buf_type type;
49
50    /**
51     * AVPixelFormat corresponding to this buffer context.
52     * AV_PIX_FMT_NONE means this is an encoded stream.
53     */
54    enum AVPixelFormat av_pix_fmt;
55
56    /**
57     * AVCodecID corresponding to this buffer context.
58     * AV_CODEC_ID_RAWVIDEO means this is a raw stream and av_pix_fmt must be set to a valid value.
59     */
60    enum AVCodecID av_codec_id;
61
62    /**
63     * Format returned by the driver after initializing the buffer context.
64     * Readonly after init.
65     */
66    struct v4l2_format format;
67
68    /**
69     * Width and height of the frames it produces (in case of a capture context, e.g. when decoding)
70     * or accepts (in case of an output context, e.g. when encoding).
71     */
72    int width, height;
73    AVRational sample_aspect_ratio;
74
75    /**
76     * Indexed array of V4L2Buffers
77     */
78    V4L2Buffer *buffers;
79
80    /**
81     * Readonly after init.
82     */
83    int num_buffers;
84
85    /**
86     * Whether the stream has been started (VIDIOC_STREAMON has been sent).
87     */
88    int streamon;
89
90    /**
91     *  Either no more buffers available or an unrecoverable error was notified
92     *  by the V4L2 kernel driver: once set the context has to be exited.
93     */
94    int done;
95
96} V4L2Context;
97
98/**
99 * Initializes a V4L2Context.
100 *
101 * @param[in] ctx A pointer to a V4L2Context. See V4L2Context description for required variables.
102 * @return 0 in case of success, a negative value representing the error otherwise.
103 */
104int ff_v4l2_context_init(V4L2Context* ctx);
105
106/**
107 * Sets the V4L2Context format in the v4l2 driver.
108 *
109 * @param[in] ctx A pointer to a V4L2Context. See V4L2Context description for required variables.
110 * @return 0 in case of success, a negative value representing the error otherwise.
111 */
112int ff_v4l2_context_set_format(V4L2Context* ctx);
113
114/**
115 * Queries the driver for a valid v4l2 format and copies it to the context.
116 *
117 * @param[in] ctx A pointer to a V4L2Context. See V4L2Context description for required variables.
118 * @param[in] probe Probe only and ignore changes to the format.
119 * @return 0 in case of success, a negative value representing the error otherwise.
120 */
121int ff_v4l2_context_get_format(V4L2Context* ctx, int probe);
122
123/**
124 * Releases a V4L2Context.
125 *
126 * @param[in] ctx A pointer to a V4L2Context.
127 *               The caller is reponsible for freeing it.
128 *               It must not be used after calling this function.
129 */
130void ff_v4l2_context_release(V4L2Context* ctx);
131
132/**
133 * Sets the status of a V4L2Context.
134 *
135 * @param[in] ctx A pointer to a V4L2Context.
136 * @param[in] cmd The status to set (VIDIOC_STREAMON or VIDIOC_STREAMOFF).
137 *                Warning: If VIDIOC_STREAMOFF is sent to a buffer context that still has some frames buffered,
138 *                those frames will be dropped.
139 * @return 0 in case of success, a negative value representing the error otherwise.
140 */
141int ff_v4l2_context_set_status(V4L2Context* ctx, uint32_t cmd);
142
143/**
144 * Dequeues a buffer from a V4L2Context to an AVPacket.
145 *
146 * The pkt must be non NULL.
147 * @param[in] ctx The V4L2Context to dequeue from.
148 * @param[inout] pkt The AVPacket to dequeue to.
149 * @return 0 in case of success, AVERROR(EAGAIN) if no buffer was ready, another negative error in case of error.
150 */
151int ff_v4l2_context_dequeue_packet(V4L2Context* ctx, AVPacket* pkt);
152
153/**
154 * Dequeues a buffer from a V4L2Context to an AVFrame.
155 *
156 * The frame must be non NULL.
157 * @param[in] ctx The V4L2Context to dequeue from.
158 * @param[inout] f The AVFrame to dequeue to.
159 * @param[in] timeout The timeout for dequeue (-1 to block, 0 to return immediately, or milliseconds)
160 * @return 0 in case of success, AVERROR(EAGAIN) if no buffer was ready, another negative error in case of error.
161 */
162int ff_v4l2_context_dequeue_frame(V4L2Context* ctx, AVFrame* f, int timeout);
163
164/**
165 * Enqueues a buffer to a V4L2Context from an AVPacket
166 *
167 * The packet must be non NULL.
168 * When the size of the pkt is null, the buffer is not queued but a V4L2_DEC_CMD_STOP command is sent instead to the driver.
169 *
170 * @param[in] ctx The V4L2Context to enqueue to.
171 * @param[in] pkt A pointer to an AVPacket.
172 * @return 0 in case of success, a negative error otherwise.
173 */
174int ff_v4l2_context_enqueue_packet(V4L2Context* ctx, const AVPacket* pkt);
175
176/**
177 * Enqueues a buffer to a V4L2Context from an AVFrame
178 *
179 * The frame must be non NULL.
180 *
181 * @param[in] ctx The V4L2Context to enqueue to.
182 * @param[in] f A pointer to an AVFrame to enqueue.
183 * @return 0 in case of success, a negative error otherwise.
184 */
185int ff_v4l2_context_enqueue_frame(V4L2Context* ctx, const AVFrame* f);
186
187#endif // AVCODEC_V4L2_CONTEXT_H
188