V4L2命令之 User Controls

大家好，欢迎来到IT知识分享网。

http://linuxtv.org/downloads/v4l-dvb-apis/control.html

User Controls

Devices typically have a number of user-settable controls such asbrightness, saturation and so on, which would be presented to the user on a graphical user interface. But, different devices will have different controls available, and further more, the range of possible values, and the default value will vary from device to device. The control ioctls provide the information and a mechanism to create a nice user interface for these controls that will work correctly with any device.

All controls are accessed using an ID value. V4L2 defines several IDs for specific purposes. Drivers can also implement their own custom controls usingV4L2_CID_PRIVATE_BASE and higher values. The pre-defined control IDs have the prefixV4L2_CID_ , and are listed in Table 1.1, “Control IDs”. The ID is used when querying the attributes of a control, and when getting or setting the current value.

Generally applications should present controls to the user without assumptions假想 about their purpose. Each control comes with a name string the user is supposed to understand. When the purpose is non-intuitive不直观 the driver writer should provide a user manual, a user interface plug-in插件 or a driver specific panel application. Predefined IDs were introduced to change a few controls programmatically方式, for example to mute静音 a device during a channel switch.

Drivers may enumerate different controls after switching the current video input or output, tuner or modulator, or audio inputor output. Different in the sense of other bounds, another default and current value, step size or other menu items. A control with a certain custom ID can also change name and type.^[9] Control values are stored globally, they do not change when switching except to stay within the reported bounds. They also do not change e. g. when the device is opened or closed, when the tuner radio frequency is changed or generally never without application request. Since V4L2 specifies no event mechanism, panel applications intended to cooperate with other panel applications (be they built into a larger application, as a TV viewer) may need to regularly poll control values to update their user interface.^[10]

All controls use machine endianness.

Applications can enumerate the available controls with theVIDIOC_QUERYCTRL and VIDIOC_QUERYMENU ioctls, get and set a control value with theVIDIOC_G_CTRL andVIDIOC_S_CTRL ioctls.Drivers must implementVIDIOC_QUERYCTRL,VIDIOC_G_CTRL and VIDIOC_S_CTRL when the device has one or more controls,VIDIOC_QUERYMENU when it has one or more menu type controls.

struct v4l2_queryctrl queryctrl;
struct v4l2_querymenu querymenu;

static void
enumerate_menu (void)
{
	printf ("  Menu items:\n");

	memset (&querymenu, 0, sizeof (querymenu));
	querymenu.id = queryctrl.id;

	for (querymenu.index = queryctrl.minimum;
	     querymenu.index <= queryctrl.maximum;
	      querymenu.index++) {
		if (0 == ioctl (fd, VIDIOC_QUERYMENU, &querymenu)) {
			printf ("  %s\n", querymenu.name);
		}
	}
}

memset (&queryctrl, 0, sizeof (queryctrl));

for (queryctrl.id = V4L2_CID_BASE;
     queryctrl.id < V4L2_CID_LASTP1;
     queryctrl.id++) {
	if (0 == ioctl (fd, VIDIOC_QUERYCTRL, &queryctrl)) {
		if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) //该命令已被禁止，无效命令
			continue;

		printf ("Control %s\n", queryctrl.name);

		if (queryctrl.type == V4L2_CTRL_TYPE_MENU) //如果命令式菜单型的则调用枚举菜单的子函数
			enumerate_menu ();
	} else {
		if (errno == EINVAL)
			continue;

		perror ("VIDIOC_QUERYCTRL");
		exit (EXIT_FAILURE);
	}
}

for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
     queryctrl.id++) {
	if (0 == ioctl (fd, VIDIOC_QUERYCTRL, &queryctrl)) {
		if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
			continue;

		printf ("Control %s\n", queryctrl.name);

		if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
			enumerate_menu ();
	} else {
		if (errno == EINVAL)
			break;

		perror ("VIDIOC_QUERYCTRL");
		exit (EXIT_FAILURE);
	}
}

struct v4l2_queryctrl queryctrl;
struct v4l2_control control;

memset (&queryctrl, 0, sizeof (queryctrl));
queryctrl.id = V4L2_CID_BRIGHTNESS;

if (-1 == ioctl (fd, VIDIOC_QUERYCTRL, &queryctrl)) {
	if (errno != EINVAL) {
		perror ("VIDIOC_QUERYCTRL");
		exit (EXIT_FAILURE);
	} else {
		printf ("V4L2_CID_BRIGHTNESS is not supported\n");
	}
} else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
	printf ("V4L2_CID_BRIGHTNESS is not supported\n");
} else {
	memset (&control, 0, sizeof (control));
	control.id = V4L2_CID_BRIGHTNESS;
	control.value = queryctrl.default_value;

	if (-1 == ioctl (fd, VIDIOC_S_CTRL, &control)) {
		perror ("VIDIOC_S_CTRL");
		exit (EXIT_FAILURE);
	}
}

memset (&control, 0, sizeof (control));
control.id = V4L2_CID_CONTRAST;

if (0 == ioctl (fd, VIDIOC_G_CTRL, &control)) {
	control.value += 1;

	/* The driver may clamp the value or return ERANGE, ignored here */

	if (-1 == ioctl (fd, VIDIOC_S_CTRL, &control)
	    && errno != ERANGE) {
		perror ("VIDIOC_S_CTRL");
		exit (EXIT_FAILURE);
	}
/* Ignore if V4L2_CID_CONTRAST is unsupported */
} else if (errno != EINVAL) {
	perror ("VIDIOC_G_CTRL");
	exit (EXIT_FAILURE);
}

control.id = V4L2_CID_AUDIO_MUTE;
control.value = TRUE; /* silence */

/* Errors ignored */
ioctl (fd, VIDIOC_S_CTRL, &control);