基于DWC2的USB驱动开发-UVC的相机终端详解

本文转自公众号，欢迎关注
基于DWC2的USB驱动开发-UVC的相机终端详解 (qq.com)

一.前言

本篇来详细分析下UVC的相机终端相关的内容，同样的我们理论结合实践来进行。

二.相机单元简介

摄像机终端（CT）控制传输视频流的设备组件的机械（或等效数字）功能。因此，它仅适用于具有可控镜头或传感器特性的视频捕获设备。相机端子始终表示为具有单个输出引脚的输入端子。简单理解就是相机终端是是一个输入终端，他的前面没有其他单元和终端了，它只有一个输出引脚，后面一般接到处理单元。

它提供了对以下功能的支持:

• Scanning Mode (Progressive or Interlaced)扫描模式（逐行扫描或交错扫描）
• Auto-Exposure Mode 自动曝光模式
• Auto-Exposure Priority自动曝光优先级
• Exposure Time曝光时间
• Focus对焦
• Auto-Focus自动对焦
• Simple Focus简单对焦
• Iris光圈
• Zoom缩放
• Pan水平左右移动镜头 X轴旋转 横摇
• Roll滚角
• Tilt垂直上下移动镜头 Y轴旋转 竖摇
• Digital Windowing数字窗口
• Region of Interest 感兴趣区域

对上述功能的支持都是可选的。对焦控制等有些是支持自动控制开关的,如果支持自动控制的属性其为打开状态，则设备将自动调整，并且读取请求将反映自动调整的值。此时手动方式设置对应属性将导致STALL，即设备要返回STALL，错误代码为bRequestErrorCode=“错误状态”。

当退出自动模式时，相应属性保持在转换前的有效值。

相机终端是特殊的输入终端,符号和输入终端一致，注意其左边没有引脚，即他就是输入前面不再有输入了，右边输出只接一个引脚。

三.拓扑结构

以下从描述符来看处理单元的拓扑结构，如下图是一个实际的UVC产品的描述符，只截取了和UVC相关的IAD下的描述符。

可以看到处理单元的ID是 bTerminalID=1 ，它没有bSourceID了，他就是输入最源头了。其后面是bUnitID=2的处理单元，该单元的bSourceID=1表示其源头是本相机终端。

相机终端采集到数据，到后面进行处理，所以相机终端后面接处理单元，这也是好理解的。

其拓扑如下

顺便提一下:

这里为什么有些叫终端Terminal ，有些叫单元Unit呢，从名字就可以看出，终端就是首末，要么就是前面没有前导，要么就是后面没有后继所以叫终端，而单元是位于中间的前后都有。

四.相机终端描述符

处理终端的描述符应该位于UVC的控制接口描述符VideoControl Interface Descriptors的Class-specific VC Interface Header Descriptor的后面

如下所示红色线所指示

本实例终端描述符对应的具体内容如下

相机单元的描述详细内容见规格书P66

3.7.2.3 Camera Terminal Descriptor

偏移	区域	大小	值	说明
0	bLength	1	数字值,18	本描述符的字节数
1	bDescriptorType	1	常数CS_INTERFACE=0x24	描述符类型
2	bDescriptorSubtype	1	常数VC_INPUT_TERMINAL=0x02	描述符子类
3	bTerminalID	1	数字	终端ID
4	wTerminalType	2	常数ITT_CAMERA	终端类型
6	bAssocTerminal	1	常数	与此输入终端关联的输出终端ID
7	iTerminal	1	Index	描述本终端的字符串描述索引,填0则没有字符串描述符。
8	wObjectiveFocalLengthMin	2	数字	如果不支持光学变焦，则Lmin的值；该字段应设置为0
10	wObjectiveFocalLengthMax	2	数字	不支持光学变焦时的Lmax值；该字段应设置为0。
12	wOcularFocalLength	2	数字	如果不支持“光学缩放”Locular该字段应设置为0。
14	bControlSize	1	数字 3	bmControls域的字节数
15	bmControls	3	Bitmap

l其中bDescriptorType的定义参考规格书的P171 A.5. Video Class-Specific VC Interface Descriptor Subtypes

l其中bDescriptorSubtype的定义参考规格书的P172 A.4. Video Class-Specific Descriptor Types

l其中bTerminalID

摄像头终端由bTerminalID字段中的值唯一标识。 非零常数 ，同一功能接口内的任何其他单元或终端都不能具有相同的ID。

这里为什么要是非零常数呢？为什么从0开始编号呢，因为在请求中wIndex的高8位为0用于区分是接口请求，其他非0值为对应终端和单元ID，所以不能从0开始编号了。

在本功能对应的接口内该值和其他单元和终端的ID不能重复。

lwTerminalType字段用于说明是什么类型的终端。对于摄像机终端，该字段应设置为ITT_Camera，见规格书P177 Table B- 2 Input Terminal Types

lbAssociateTerminal字段用于将输出端子与该输入端子相关联，从而有效地实现双向端子对。

为0则是单向端子。

l其中bmControls，表示支持的处理类型

某一位置位则对应的处理支持,小端模式

D0: Scanning Mode

D1: Auto-Exposure Mode

D2: Auto-Exposure Priority

D3: Exposure Time (Absolute)

D4: Exposure Time (Relative)

D5: Focus (Absolute)

D6 : Focus (Relative)

D7: Iris (Absolute)

D8 : Iris (Relative)

D9: Zoom (Absolute)

D10: Zoom (Relative)

D11: PanTilt (Absolute)

D12: PanTilt (Relative)

D13: Roll (Absolute)

D14: Roll (Relative)

D15: Reserved

D16: Reserved

D17: Focus, Auto

D18: Privacy

D19: Focus, Simple

D20: Window

D21: Region of Interest

D22 – D23: Reserved, set to zero

以下是对应一个实例，

-------- Video Control Input Terminal Descriptor ------

bLength : 0x12 (18 bytes)

bDescriptorType : 0x24 (Video Control Interface)

bDescriptorSubtype : 0x02 (Input Terminal)

bTerminalID : 0x01 (1)

wTerminalType : 0x0201 (ITT_CAMERA)

bAssocTerminal : 0x00 (Not associated with an Output Terminal)

iTerminal : 0x00 (No String Descriptor)

Camera Input Terminal Data:

wObjectiveFocalLengthMin : 0x0000

wObjectiveFocalLengthMax : 0x0000

wOcularFocalLength : 0x0000

bControlSize : 0x03 (3 bytes)

bmControls : 0xFF, 0xFF, 0x1F

D0 : 1 yes - Scanning Mode

D1 : 1 yes - Auto-Exposure Mode

D2 : 1 yes - Auto-Exposure Priority

D3 : 1 yes - Exposure Time (Absolute)

D4 : 1 yes - Exposure Time (Relative)

D5 : 1 yes - Focus (Absolute)

D6 : 1 yes - Focus (Relative)

D7 : 1 yes - Iris (Absolute)

D8 : 1 yes - Iris (Relative)

D9 : 1 yes - Zoom (Absolute)

D10 : 1 yes - Zoom (Relative)

D11 : 1 yes - Pan (Absolute)

D12 : 1 yes - Pan (Relative)

D13 : 1 yes - Roll (Absolute)

D14 : 1 yes - Roll (Relative)

D15 : 1 yes - Tilt (Absolute)

D16 : 1 yes - Tilt (Relative)

D17 : 1 yes - Focus Auto

D18 : 1 yes - Reserved

D19 : 1 yes - Reserved

D20 : 1 yes - Reserved

D21 : 0 no - Reserved

D22 : 0 no - Reserved

D23 : 0 no - Reserved

Data (HexDump) : 12 24 02 01 01 02 00 00 00 00 00 00 00 00 03 FF .$..............

FF 1F ..

五. 相机终端相关的请求

参考规格书P97 4.2.2.1 Camera Terminal Control Requests

相机终端控制请求用于读或者设置相关属性，所以包括SET_xx 和GET_xx。

一共支持如下20种属性的请求

对应的CS编码见P174 A.9.4. Camera Terminal Control Selectors

以下做了一个总结

除非另有规定，否则所有值都被解释为绝对值（固定原点），而不是相对值。除非另有规定，否则它们也被认为是无符号的。

类型	CS	大小B	支持的操作[]表示可选	最少支持操作	说明
扫描模式	CT_SCANNING_MODE_CONTROL	1	SET_CURGET_CURGET_INFO		0:交错扫描1:非交错模式
自动曝光模式	CT_AE_MODE_CONTROL	1	SET_CURGET_CURGET_RESGET_INFOGET_DEF	GET_DEF	D0: 手动改模式D1: 自动模式D2: 快门优先模式-手动曝光时间，自动光圈D3: 光圈优先模式-自动曝光时间，手动光圈D4..D7: 保留设置为0.使能自动模式时再配置相关属性将导致STALL和bRequestErrorCode=“错误状态”的错误代码。向该控件发出的GET_RES请求将返回该控件支持的模式的bitmap。对该控件的有效请求将仅设置一个位（选择单个模式）。
自动曝光优先级控制	CT_AE_PRIORITY_CONTROL	1	SET_CURGET_CURGET_INFO		0表示帧率固定，默认值1表示帧率可动态变化用于快门优先模式和自动模式时约束曝光时间控制。
曝光绝对时间控制	CT_EXPOSURE_TIME_ABSOLUTE_CONTROL	4	GET_CUR GET_MIN GET_MAXGET_RESGET_INFOGET_DEF[SET_CUR]	GET_DEF	指定曝光时间,单位为100µs,值设置为0未定义。手动曝光控制受到帧间隔的进一步限制，帧间隔总是具有更高的优先级，如果帧间隔更改为低于“曝光控制”当前值的值，“曝光控制值”将自动更改，默认的“曝光控制”值将是当前帧间隔，直到选择了明确的曝光值为止。当处于自动模式或光圈优先模式时，设置该值导致STALL和bRequestErrorCode=“错误状态”的错误代码。
曝光相对时间控制	CT_EXPOSURE_TIME_RELATIVE_CONTROL	1	SET_CURGET_CURGET_INFO		有符号数带包步进数0表示设置曝光时间为默认值，当处于自动模式或光圈优先模式时，设置该值导致STALL和bRequestErrorCode=“错误状态”的错误代码。如果同时支持相对控制和绝对控制，则具有0x00以外值的相对控制的SET_CUR应导致绝对控制的控制更改中断
对焦绝对值控制	CT_FOCUS_ABSOLUTE_CONTROL	2	GET_CUR GET_MIN GET_MAXGET_RESGET_INFOGET_DEF[SET_CUR]	GET_DEF	单位毫米,启用自动对焦模式时，设置此值将导致STALL和bRequestErrorCode=“错误状态”的错误代码。
对焦相对值控制	CT_FOCUS_RELATIVE_CONTROL	2	SET_CURGET_CURGET_INFOGET_DEFGET_MINGET_MAXGET_RES	GET_DEF	第一个字节bFocusRelative1表示聚焦透镜组向近方向移动为0表示聚焦透镜组停止0xFF表示透镜组向无穷远方向移动。GET_MIN、GET_MAX、GET_RES和GET_DEF请求时此字段段返回零。第二个字节bSpeed表示移动速度，不支持则设置为1，如果同时支持相对控制和绝对控制，则具有0x00以外值的相对控制的SET_CUR将导致绝对控制在移动结束时的控制更改中断启用自动对焦时，设置此值导致STALL和bRequestErrorCode=“错误状态”的错误代码。
对焦简单范围	CT_FOCUS_SIMPLE_CONTROL	1	SET_CURGET_CURGET_INFO GET_DEF	GET_DEF	只能在相机处于手动或自动对焦模式时使用。启用自动对焦时，设置此值导致STALL和bRequestErrorCode=“错误状态”的错误代码。0x00 – full range0x01 – macro. Less than 0.3meters.0x02 – people. 0.3m to 3m0x03 – scene. 3m to infinity0x04 to 0xFF - reserved
自动对焦控制	CT_FOCUS_AUTO_CONTROL	1	SET_CUR GET_CUR GET_INFGET_DEF	GET_DEF	1使能自动对焦
光圈绝对控制	PU_SHARPNESS_CONTROL	2	GET_CURGET_MIN GET_MAXGET_RES GET_INFOGET_DEF[SET_CUR]	GET_DEF	单位为fstop * 100 当“自动曝光模式”控件处于“自动”模式或“快门优先级”模式时，不接受SET请求，设备返回STALL。
光圈相对控制	CT_IRIS_RELATIVE_CONTROL	1	SET_CUR GET_CURGET_INFO		有符号数当“自动曝光模式”控件处于“自动”模式或“快门优先级”模式时，不接受SET请求，设备返回STALL。0: Default1: Iris is opened by 1 step.0xFF: Iris is closed by 1 step
缩放绝对控制	CT_ZOOM_ABSOLUTE_CONTROL	2	GET_CURGET_MIN GET_MAXGET_RESGET_INFOGET_DEF[SET_CUR]	GET_DEF	RES必须为1Zcur的值用于指定或确定物镜焦距。与相机终端描述符中的wObjectiveFocalLengthMin和wObjectiveForcalLengthMax字段结合使用，以描述和控制设备的物镜焦距。
缩放相对控制	CT_ZOOM_RELATIVE_CONTROL	3	SET_CUR GET_CUR GET_INFOGET_DEFGET_MINGET_MAXGET_RES		第一个字节bZoom字段1表示变焦镜头向远摄方向移动。0表示变焦镜头停止，0xFF表示变焦镜头向广角方向移动。GET_MIN、GET_MAX、GET_RES和GET_DEF请求将为此字段返回零第二个字节bDigitalZoom指定是启用还是禁用数字缩放。如果设备仅支持数字变焦，则此字段将被忽略。GET_DEF请求将返回此字段的默认值。GET_MIN、GET_MAX和GET_RES请求将为此字段返回零。第三个字节bSpeedGET_MIN、GET_MAX和GET_RES请求用于检索此字段的范围和分辨率。GET_DEF请求用于检索此字段的默认值。如果控件不支持速度控制，它将针对所有这些请求在该字段中返回值1如果同时支持相对控制和绝对控制，则具有0x00以外值的相对控制的SET_CUR应在移动结束时导致绝对控制的控制更改中断，如果移动结束是由于物理设备限制（如移动范围限制），则应为该相对控制生成控制更改中断。
全景倾斜（绝对）控制	CT_PANTILT_ABSOLUTE_CONTROL	8	GET_CUR GET_MIN GET_MAXGET_RES GET_INFOGET_DEF[SET_CUR]	GET_DEF	低4字节，有符号 32位小端Pan绝对值高4字节，有符号 32位小端Tilt绝对值单位arc 弧秒范围–1803600 arc second ~+1803600 arc second 默认值为0
全景倾斜（相对）控制	CT_PANTILT_RELATIVE_CONTROL	4	SET_CURGET_CURGET_INFOGET_DEF GET_MINGET_MAXGET_RES	GET_DEF	第一个字节bPanRelative有符号 Pan控制0: Stop1: moving to clockwise direction0xFF: moving to counter clockwise Direction第二个字节 bPanSpeed Pan移动速度第三个字节bTiltRelative 有符号0: Stop1: point the imaging plane up0xFF: point the imaging plane down第四个字节 bTiltSpeed Tilt速度
滚转（绝对）控制	CT_ROLL_ABSOLUTE_CONTROL	2	GET_CURGET_MIN GET_MAX GET_RESGET_INFOGET_DEF[SET_CUR]		有符号16位小端范围–180~+180
滚转（相对）控制	CT_ROLL_RELATIVE_CONTROL	2	SET_CURGET_CURGET_MINGET_MAX GET_RESGET_INFOGET_DEF		第一个字节0: Stop1: moving clockwise rotation0xFF: moving counter clockwise rotation第二个字节速度
隐私控制	CT_PRIVACY_CONTROL	1	GET_CUR GET_INFO[SET_CUR]		隐私控制设置用于防止摄像机传感器获取视频。值0表示摄像机传感器能够捕获视频图像，值1表示摄像机传感器被阻止捕获视频图像。该控件应报告为自动更新控件。0: Open1: Close
数字窗口控制	CT_DIGITAL_WINDOW_CONTROL	12	SET_CURGET_CURGET_MIN GET_MAXGET_DEF		坐标从0开始wWindow_Top:2 字节 上坐标wWindow_Left:2字节 左坐标wWindow_Bottom：2 字节 下坐标wWindow_Right:2 字节 右坐标wNumSteps:2字节 从本窗口移动到指定矩形的步数bmNumStepsUnits:2字节 上述步数的单位D0: video framesD1: millisecondsD2-D15: Reserved
数字感兴趣区域（ROI）控制	CT_REGION_OF_INTEREST_CONTROL	10	SET_CUR GET_CURGET_MIN, GET_MAXGET_DEF		ROI必须在CT_Window控件指定的当前数字窗口内。wROI_Top 2字节 上坐标wROI_Left 2字节 左坐标wROI_Bottom2字节 下坐标wROI_Right2字节 右坐标bmAutoControls2字节D0: Auto ExposureD1: Auto IrisD2: Auto White BalanceD3: Auto FocusD4: Auto Face DetectD5: Auto Detect and TrackD6: Image StabilizationD7: Higher QualityD8 – D15: Reserved, set to zero

六. 相机终端请求驱动代码

和其他终端和单元请求处理一样

参考https://mp.weixin.qq.com/s/4CTR1yjUmBsHqZPLEC7BhA

七. 总结

以上详细介绍了相机终端，包括描述符和其拓扑结构，请求等。

审核编辑：汤梓红