path: root/include/media/v4l2-ctrls.h

/*
 *  V4L2 controls support header.
 *
 *  Copyright (C) 2010  Hans Verkuil <hverkuil@xs4all.nl>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 */

#ifndef _V4L2_CTRLS_H
#define _V4L2_CTRLS_H

#include <linux/list.h>
#include <linux/mutex.h>
#include <linux/videodev2.h>
#include <media/media-request.h>

/*
 * Include the mpeg2 and fwht stateless codec compound control definitions.
 * This will move to the public headers once this API is fully stable.
 */
#include <media/mpeg2-ctrls.h>
#include <media/fwht-ctrls.h>

/* forward references */
struct file;
struct v4l2_ctrl_handler;
struct v4l2_ctrl_helper;
struct v4l2_ctrl;
struct video_device;
struct v4l2_subdev;
struct v4l2_subscribed_event;
struct v4l2_fh;
struct poll_table_struct;

/**
 * union v4l2_ctrl_ptr - A pointer to a control value.
 * @p_s32:			Pointer to a 32-bit signed value.
 * @p_s64:			Pointer to a 64-bit signed value.
 * @p_u8:			Pointer to a 8-bit unsigned value.
 * @p_u16:			Pointer to a 16-bit unsigned value.
 * @p_u32:			Pointer to a 32-bit unsigned value.
 * @p_char:			Pointer to a string.
 * @p_mpeg2_slice_params:	Pointer to a MPEG2 slice parameters structure.
 * @p_mpeg2_quantization:	Pointer to a MPEG2 quantization data structure.
 * @p_fwht_params:		Pointer to a FWHT stateless parameters structure.
 * @p:				Pointer to a compound value.
 */
union v4l2_ctrl_ptr {
	s32 *p_s32;
	s64 *p_s64;
	u8 *p_u8;
	u16 *p_u16;
	u32 *p_u32;
	char *p_char;
	struct v4l2_ctrl_mpeg2_slice_params *p_mpeg2_slice_params;
	struct v4l2_ctrl_mpeg2_quantization *p_mpeg2_quantization;
	struct v4l2_ctrl_fwht_params *p_fwht_params;
	void *p;
};

/**
 * struct v4l2_ctrl_ops - The control operations that the driver has to provide.
 *
 * @g_volatile_ctrl: Get a new value for this control. Generally only relevant
 *		for volatile (and usually read-only) controls such as a control
 *		that returns the current signal strength which changes
 *		continuously.
 *		If not set, then the currently cached value will be returned.
 * @try_ctrl:	Test whether the control's value is valid. Only relevant when
 *		the usual min/max/step checks are not sufficient.
 * @s_ctrl:	Actually set the new control value. s_ctrl is compulsory. The
 *		ctrl->handler->lock is held when these ops are called, so no
 *		one else can access controls owned by that handler.
 */
struct v4l2_ctrl_ops {
	int (*g_volatile_ctrl)(struct v4l2_ctrl *ctrl);
	int (*try_ctrl)(struct v4l2_ctrl *ctrl);
	int (*s_ctrl)(struct v4l2_ctrl *ctrl);
};

/**
 * struct v4l2_ctrl_type_ops - The control type operations that the driver
 *			       has to provide.
 *
 * @equal: return true if both values are equal.
 * @init: initialize the value.
 * @log: log the value.
 * @validate: validate the value. Return 0 on success and a negative value
 *	otherwise.
 */
struct v4l2_ctrl_type_ops {
	bool (*equal)(const struct v4l2_ctrl *ctrl, u32 idx,
		      union v4l2_ctrl_ptr ptr1,
		      union v4l2_ctrl_ptr ptr2);
	void (*init)(const struct v4l2_ctrl *ctrl, u32 idx,
		     union v4l2_ctrl_ptr ptr);
	void (*log)(const struct v4l2_ctrl *ctrl);
	int (*validate)(const struct v4l2_ctrl *ctrl, u32 idx,
			union v4l2_ctrl_ptr ptr);
};

/**
 * typedef v4l2_ctrl_notify_fnc - typedef for a notify argument with a function
 *	that should be called when a control value has changed.
 *
 * @ctrl: pointer to struct &v4l2_ctrl
 * @priv: control private data
 *
 * This typedef definition is used as an argument to v4l2_ctrl_notify()
 * and as an argument at struct &v4l2_ctrl_handler.
 */
typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);

/**
 * struct v4l2_ctrl - The control structure.
 *