1.11. 攝像頭控制參考¶
攝像頭類別包含用於裝置機械（或等效數字）功能的控制，例如可控鏡頭或感測器。
1.11.1. 攝像頭控制ID¶
V4L2_CID_CAMERA_CLASS (類)攝像頭類描述符。為此控制呼叫 ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL 和 VIDIOC_QUERYMENU 將返回此控制類的描述。
V4L2_CID_EXPOSURE_AUTO(列舉)
- enum v4l2_exposure_auto_type -
啟用曝光時間及/或光圈的自動調整。當這些功能啟用時，手動更改曝光時間或光圈的效果是未定義的，驅動應忽略此類請求。可能的值有：
|
自動曝光時間，自動光圈。 |
|
手動曝光時間，手動光圈。 |
|
手動曝光時間，自動光圈。 |
|
自動曝光時間，手動光圈。 |
V4L2_CID_EXPOSURE_ABSOLUTE (整數)確定攝像頭感測器的曝光時間。曝光時間受幀間隔限制。驅動應將值解釋為 100 微秒單位，其中值 1 代表 1/10000 秒，10000 代表 1 秒，100000 代表 10 秒。
V4L2_CID_EXPOSURE_AUTO_PRIORITY (布林)當
V4L2_CID_EXPOSURE_AUTO設定為AUTO或APERTURE_PRIORITY時，此控制決定裝置是否可以動態改變幀率。預設情況下，此功能是停用 (0) 的，幀率必須保持恆定。V4L2_CID_AUTO_EXPOSURE_BIAS (整數 選單)確定自動曝光補償，僅當
V4L2_CID_EXPOSURE_AUTO控制設定為AUTO、SHUTTER_PRIORITY或APERTURE_PRIORITY時才有效。它以 EV 表示，驅動應將值解釋為 0.001 EV 單位，其中值 1000 代表 +1 EV。增加曝光補償值等同於減少曝光值 (EV)，並將增加影像感測器接收到的光量。攝像頭透過調整絕對曝光時間及/或光圈來執行曝光補償。
V4L2_CID_EXPOSURE_METERING(列舉)
- enum v4l2_exposure_metering -
確定攝像頭如何測量幀曝光可用光量。可能的值有：
|
使用來自整個幀的光資訊並平均，不給計量區域的任何特定部分加權。 |
|
平均來自整個幀的光資訊，優先考慮計量區域的中心。 |
|
僅測量幀中心非常小的區域。 |
|
多區域測光。在幀的多個點測量光強度並組合結果。區域選擇及其在計算最終值中的重要性演算法取決於裝置。 |
V4L2_CID_PAN_RELATIVE (整數)此控制將攝像頭水平轉動指定量。單位未定義。正值使攝像頭向右移動（從上方看是順時針），負值向左移動。值為零不引起運動。這是一個只寫控制。
V4L2_CID_TILT_RELATIVE (整數)此控制將攝像頭垂直轉動指定量。單位未定義。正值使攝像頭向上移動，負值向下移動。值為零不引起運動。這是一個只寫控制。
V4L2_CID_PAN_RESET (按鈕)當此控制設定時，攝像頭水平移動到預設位置。
V4L2_CID_TILT_RESET (按鈕)當此控制設定時，攝像頭垂直移動到預設位置。
V4L2_CID_PAN_ABSOLUTE (整數)此控制將攝像頭水平轉動到指定位置。正值使攝像頭向右移動（從上方看是順時針），負值向左移動。驅動應將值解釋為弧秒，有效值介於 -180 * 3600 和 +180 * 3600（含）之間。
V4L2_CID_TILT_ABSOLUTE (整數)此控制將攝像頭垂直轉動到指定位置。正值使攝像頭向上移動，負值向下移動。驅動應將值解釋為弧秒，有效值介於 -180 * 3600 和 +180 * 3600（含）之間。
V4L2_CID_FOCUS_ABSOLUTE (整數)此控制將攝像頭的焦點設定為指定位置。單位未定義。正值使焦點更靠近攝像頭，負值使焦點移向無窮遠。
V4L2_CID_FOCUS_RELATIVE (整數)此控制將攝像頭的焦點移動指定量。單位未定義。正值使焦點更靠近攝像頭，負值使焦點移向無窮遠。這是一個只寫控制。
V4L2_CID_FOCUS_AUTO (布林)啟用連續自動對焦調整。當此功能啟用時，手動對焦調整的效果是未定義的，驅動應忽略此類請求。
V4L2_CID_AUTO_FOCUS_START (按鈕)啟動單次自動對焦過程。當
V4L2_CID_FOCUS_AUTO設定為TRUE(1) 時設定此控制的效果是未定義的，驅動應忽略此類請求。V4L2_CID_AUTO_FOCUS_STOP (按鈕)中止由
V4L2_CID_AUTO_FOCUS_START控制啟動的自動對焦。僅當連續自動對焦被停用時才有效，即當V4L2_CID_FOCUS_AUTO控制設定為FALSE(0) 時。
V4L2_CID_AUTO_FOCUS_STATUS (位掩碼)自動對焦狀態。這是一個只讀控制。
設定
V4L2_CID_3A_LOCK控制的V4L2_LOCK_FOCUS鎖定位可能會停止V4L2_CID_AUTO_FOCUS_STATUS控制值的更新。
|
自動對焦未啟用。 |
|
自動對焦正在進行中。 |
|
已達到焦點。 |
|
自動對焦失敗，驅動將不會從此狀態轉換，直到應用程式執行另一個操作。 |
V4L2_CID_AUTO_FOCUS_RANGE(列舉)
- enum v4l2_auto_focus_range -
確定鏡頭可以調整的自動對焦距離範圍。
|
攝像頭自動選擇對焦範圍。 |
|
正常距離範圍，為獲得最佳自動對焦效能而受限。 |
|
微距（特寫）自動對焦。攝像頭將使用其可能的最小距離進行自動對焦。 |
|
鏡頭設定為對焦無限遠處的物體。 |
V4L2_CID_ZOOM_ABSOLUTE (整數)將物鏡焦距指定為絕對值。變焦單位是驅動特定的，其值應為正整數。
V4L2_CID_ZOOM_RELATIVE (整數)相對於當前值指定物鏡焦距。正值使變焦鏡頭組向長焦方向移動，負值向廣角方向移動。變焦單位是驅動特定的。這是一個只寫控制。
V4L2_CID_ZOOM_CONTINUOUS (整數)以指定速度移動物鏡組，直到達到物理裝置限制或直到有明確請求停止移動。正值使變焦鏡頭組向長焦方向移動。零值停止變焦鏡頭組的移動。負值使變焦鏡頭組向廣角方向移動。變焦速度單位是驅動特定的。
V4L2_CID_IRIS_ABSOLUTE (整數)此控制將攝像頭的孔徑設定為指定值。單位未定義。值越大光圈開得越寬，值越小光圈關得越小。
V4L2_CID_IRIS_RELATIVE (整數)此控制按指定量修改攝像頭的孔徑。單位未定義。正值使光圈再開一步，負值使光圈再關一步。這是一個只寫控制。
V4L2_CID_PRIVACY (布林)阻止攝像頭獲取影片。當此控制設定為
TRUE(1) 時，攝像頭無法捕獲任何影像。實現隱私的常見手段是感測器的機械遮擋和韌體影像處理，但裝置不限於這些方法。實現隱私控制的裝置必須支援讀訪問，並可能支援寫訪問。V4L2_CID_BAND_STOP_FILTER (整數)開啟或關閉攝像頭感測器的帶阻濾波器，或指定其強度。例如，此類帶阻濾波器可用於濾除熒光燈分量。
V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE(列舉)
- enum v4l2_auto_n_preset_white_balance -
將白平衡設定為自動、手動或預設。預設確定光的色溫，作為攝像頭調整白平衡的提示，以實現最準確的色彩表示。以下白平衡預設按色溫遞增順序列出。
|
手動白平衡。 |
|
自動白平衡調整。 |
|
用於白熾燈（鎢絲燈）照明的白平衡設定。它通常會使顏色變冷，大致對應 2500...3500 K 的色溫範圍。 |
|
用於熒光燈照明的白平衡預設。它大致對應 4000...5000 K 的色溫。 |
|
透過此設定，攝像頭將補償熒光 H 照明。 |
|
用於地平線日光照明的白平衡設定。它大致對應 5000 K 的色溫。 |
|
用於日光（晴空）的白平衡預設。它大致對應 5000...6500 K 的色溫。 |
|
透過此設定，攝像頭將補償閃光燈。它會使顏色略微變暖，大致對應 5000...5500 K 的色溫。 |
|
用於中度陰天的白平衡預設。此選項大致對應 6500...8000 K 的色溫範圍。 |
|
用於陰影或重度陰天的白平衡預設。它大致對應 9000...10000 K 的色溫。 |
V4L2_CID_WIDE_DYNAMIC_RANGE (布林)啟用或停用攝像頭的寬動態範圍功能。此功能允許在場景中光照強度顯著變化的場景中獲得清晰影像，即同時存在非常暗和非常亮的區域。它在攝像頭中最常見的實現方式是結合兩個具有不同曝光時間的連續幀。[1]
V4L2_CID_IMAGE_STABILIZATION (布林)啟用或停用影像穩定功能。
V4L2_CID_ISO_SENSITIVITY (整數 選單)確定影像感測器的 ISO 等效值，表示感測器對光的敏感度。這些數字以算術刻度表示，符合 ISO 12232:2006 標準，其中感測器靈敏度加倍表示為 ISO 數值加倍。應用程式應將這些值解釋為標準 ISO 值乘以 1000，例如控制值 800 代表 ISO 0.8。驅動通常只支援標準 ISO 值的一個子集。當
V4L2_CID_ISO_SENSITIVITY_AUTO控制設定為非V4L2_CID_ISO_SENSITIVITY_MANUAL值時，設定此控制的效果是未定義的，驅動應忽略此類請求。
V4L2_CID_ISO_SENSITIVITY_AUTO(列舉)
- enum v4l2_iso_sensitivity_type -
啟用或停用自動 ISO 敏感度調整。
|
手動 ISO 敏感度。 |
|
自動 ISO 敏感度調整。 |
V4L2_CID_SCENE_MODE(列舉)
- enum v4l2_scene_mode -
此控制允許選擇場景程式作為針對常見拍攝場景最佳化的攝像頭自動模式。在這些模式下，攝像頭會確定最佳曝光、光圈、對焦、測光、白平衡和等效敏感度。這些引數的控制受場景模式控制的影響。每種模式下的確切行為取決於攝像頭規格。
當不使用場景模式功能時，此控制應設定為
V4L2_SCENE_MODE_NONE，以確保其他可能相關的控制可訪問。定義了以下場景程式：
|
場景模式功能已停用。 |
|
逆光。當光線從主體後方射來時，補償暗影，也會自動開啟閃光燈。 |
|
沙灘和雪景。當攝像頭的自動曝光基於平均場景亮度時，此模式補償全白或明亮場景（這些場景往往看起來灰色且對比度低）。為補償這一點，此模式會自動輕微過度曝光幀。白平衡也可能被調整，以補償反光雪景看起來偏藍而不是白色的事實。 |
|
燭光。攝像頭通常會提高 ISO 敏感度並降低快門速度。此模式補償場景中相對較近的主體。為保持光線氛圍，閃光燈被停用。 |
|
黎明和黃昏。保留黃昏前和黎明後低自然光下看到的顏色。攝像頭可能會關閉閃光燈，並自動對焦無限遠。它通常會提高飽和度並降低快門速度。 |
|
秋色。增加飽和度並調整白平衡以增強色彩。秋葉照片會獲得飽和的紅色和黃色。 |
|
煙花。使用長曝光時間捕獲煙花擴散的光爆。攝像頭可能會啟用影像穩定。 |
|
風景。攝像頭可能會選擇小光圈以提供深景深和長曝光時間，以幫助在昏暗光線條件下捕捉細節。焦點固定在無限遠。適用於遠距離和廣闊的風景。 |
|
夜晚，也稱為夜景。專為低光條件設計，可在不使亮物體曝光過度的情況下保留暗區細節。攝像頭通常會設定為中高 ISO 敏感度，曝光時間相對較長，並關閉閃光燈。因此，影像噪點會增加，並可能出現影像模糊。 |
|
派對和室內。旨在捕捉室內背景光和閃光燈照明的室內場景。攝像頭通常會提高 ISO 敏感度，並調整曝光以適應低光條件。 |
|
肖像。攝像頭調整光圈，以減少景深，這有助於將主體從平滑背景中分離出來。大多數攝像頭會識別場景中人臉的存在並對其對焦。調整色調以增強膚色。閃光燈的強度通常會降低。 |
|
運動。顯著提高 ISO 並使用高速快門以凍結快速移動主體的運動。在此模式下可能會看到增加的影像噪點。 |
|
日落。保留日落和日出中看到的深色調。它會提高飽和度。 |
|
文字。它應用額外的對比度和銳度，通常是為可讀性最佳化的黑白模式。自動對焦可能會切換到特寫模式，此設定也可能涉及一些鏡頭畸變校正。 |
V4L2_CID_3A_LOCK (位掩碼)此控制鎖定或解鎖自動對焦、曝光和白平衡。透過將相應的鎖定位設定為 1，可以獨立暫停自動調整。然後，攝像頭會保留這些設定，直到鎖定位被清除。定義了以下鎖定位：
當給定演算法未啟用時，驅動應忽略鎖定它的請求，並且不應返回錯誤。例如，當
V4L2_CID_AUTO_WHITE_BALANCE控制設定為FALSE時，應用程式設定V4L2_LOCK_WHITE_BALANCE位。此控制的值可能會被曝光、白平衡或對焦控制更改。
|
自動曝光調整鎖定。 |
|
自動白平衡調整鎖定。 |
|
自動對焦鎖定。 |
V4L2_CID_PAN_SPEED (整數)此控制以特定速度水平轉動攝像頭。單位未定義。正值使攝像頭向右移動（從上方看是順時針），負值向左移動。值為零停止正在進行的運動，否則無效果。
V4L2_CID_TILT_SPEED (整數)此控制以指定速度垂直轉動攝像頭。單位未定義。正值使攝像頭向上移動，負值向下移動。值為零停止正在進行的運動，否則無效果。
V4L2_CID_CAMERA_ORIENTATION (選單)此只讀控制透過報告攝像頭在安裝裝置上的安裝位置來描述攝像頭方向。控制值是常量，不能由軟體修改。此控制對於具有明確方向的裝置（例如手機、筆記型電腦和行動式裝置）特別有意義，因為該控制表示為相對於裝置預期使用方向的位置。例如，安裝在手機、平板電腦或筆記型電腦裝置使用者側的攝像頭被認為是
V4L2_CAMERA_ORIENTATION_FRONT方向，而安裝在正面相反側的攝像頭被認為是V4L2_CAMERA_ORIENTATION_BACK方向。未直接連線到裝置或以允許其自由移動的方式連線的攝像頭感測器（例如網路攝像頭和數碼相機）被認為是V4L2_CAMERA_ORIENTATION_EXTERNAL方向。
|
攝像頭朝向裝置的使用者側。 |
|
攝像頭朝向裝置的背面。 |
|
攝像頭未直接連線到裝置，可自由移動。 |
V4L2_CID_CAMERA_SENSOR_ROTATION (整數)此只讀控制描述了為補償攝像頭感測器安裝旋轉，在捕獲影像到記憶體後需要對捕獲影像應用的逆時針方向的旋轉校正度數。
有關感測器安裝旋轉的精確定義，請參閱裝置樹繫結檔案“video-interfaces.txt”中對“rotation”屬性的詳細描述。
下面報告了一些示例，使用一條鯊魚在使用者面前從左向右遊動作為要捕獲的示例場景。
0 X-axis 0 +-------------------------------------> ! ! ! ! |\____)\___ ! ) _____ __`< ! |/ )/ ! ! ! V Y-axis
示例一 - 網路攝像頭
假設您可以帶著筆記型電腦與鯊魚一起游泳，筆記型電腦的攝像頭模組安裝在筆記型電腦螢幕外殼的使用者側部分，通常用於視訊通話。捕獲的影像旨在以橫向模式（寬度 > 高度）在筆記型電腦螢幕上顯示。
攝像頭通常倒置安裝，以補償鏡頭光學反轉效應。在這種情況下，V4L2_CID_CAMERA_SENSOR_ROTATION 控制的值為 0，不需要旋轉即可向使用者正確顯示影像。
如果攝像頭感測器未倒置安裝，則需要補償鏡頭光學反轉效應，並且 V4L2_CID_CAMERA_SENSOR_ROTATION 控制的值為 180 度，因為影像在捕獲到記憶體時會旋轉。
+--------------------------------------+ ! ! ! ! ! ! ! __/(_____/| ! ! >.___ ____ ( ! ! \( \| ! ! ! ! ! ! ! +--------------------------------------+
必須應用 180 度的軟體旋轉校正才能在使用者螢幕上正確顯示影像。
+--------------------------------------+ ! ! ! ! ! ! ! |\____)\___ ! ! ) _____ __`< ! ! |/ )/ ! ! ! ! ! ! ! +--------------------------------------+
示例二 - 手機攝像頭
隨身攜帶手機與鯊魚一起游泳並使用安裝在裝置背面、遠離使用者的攝像頭拍照會更方便。捕獲的影像旨在以縱向模式（高度 > 寬度）顯示，以匹配裝置螢幕方向和拍照時使用的裝置使用方向。
攝像頭感測器通常以其畫素陣列長邊與裝置長邊對齊的方式安裝，並倒置安裝以補償鏡頭光學反轉效應。
影像一旦捕獲到記憶體，將發生旋轉，並且 V4L2_CID_CAMERA_SENSOR_ROTATION 的值將報告 90 度旋轉。
+-------------------------------------+ | _ _ | | \ / | | | | | | | | | | | > | | < | | | | | | | . | | V | +-------------------------------------+
必須應用 90 度逆時針方向的校正才能在裝置螢幕上正確顯示縱向模式的影像。
+--------------------+ | | | | | | | | | | | | | |\____)\___ | | ) _____ __`< | | |/ )/ | | | | | | | | | | | +--------------------+
V4L2_CID_HDR_SENSOR_MODE (選單)更改感測器 HDR 模式。HDR 影像是透過合併同一場景的兩次不同曝光時間的捕獲獲得的。HDR 模式描述了這兩種捕獲在感測器中合併的方式。
由於模式因每個感測器而異，此控制不標準化選單項，並留給程式設計師自行決定。