7.7. ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD

7.7.1. 名稱

VIDIOC_DECODER_CMD - VIDIOC_TRY_DECODER_CMD - 執行解碼器命令

7.7.2. 概要

VIDIOC_DECODER_CMD

int ioctl(int fd, VIDIOC_DECODER_CMD, struct v4l2_decoder_cmd *argp)

VIDIOC_TRY_DECODER_CMD

int ioctl(int fd, VIDIOC_TRY_DECODER_CMD, struct v4l2_decoder_cmd *argp)

7.7.3. 引數

fd

由 open() 返回的檔案描述符。

argp

指向結構體 v4l2_decoder_cmd 的指標。

7.7.4. 描述

這些 ioctl 控制音訊/影片 (通常是 MPEG) 解碼器。 VIDIOC_DECODER_CMD 向解碼器傳送命令，VIDIOC_TRY_DECODER_CMD 可用於嘗試命令而無需實際執行它。 要傳送命令，應用程式必須初始化結構體 v4l2_decoder_cmd 的所有欄位，並呼叫帶有指向此結構的指標的 VIDIOC_DECODER_CMD 或 VIDIOC_TRY_DECODER_CMD。

cmd 欄位必須包含命令程式碼。 一些命令使用 flags 欄位獲取其他資訊。

如果尚未啟動解碼器，呼叫 write() 或 ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF 會向解碼器傳送一個隱式的 START 命令。 適用於 mem2mem 解碼器的兩個佇列。

呼叫 close() 或 VIDIOC_STREAMOFF 流式檔案描述符會向解碼器傳送隱式的立即 STOP 命令，並且所有緩衝資料都將被丟棄。 適用於 mem2mem 解碼器的兩個佇列。

原則上，這些 ioctl 是可選的，並非所有驅動程式都可能支援它們。 它們是在 Linux 3.3 中引入的。 但是，對於有狀態 mem2mem 解碼器來說，它們是強制性的（如 記憶體到記憶體狀態影片解碼器介面 中進一步記錄的那樣）。

型別 v4l2_decoder_cmd

結構體 v4l2_decoder_cmd

__u32	cmd		解碼器命令，參見 解碼器命令。
__u32	flags		與命令一起使用的標誌。 如果沒有為此命令定義標誌，則驅動程式和應用程式必須將此欄位設定為零。
union {	(anonymous)
struct	start		包含 V4L2_DEC_CMD_START 命令的附加資料的結構體。
	__s32	speed	播放速度和方向。 播放速度定義為正常速度的 speed/1000。 因此 1000 是正常播放。 負數表示反向播放，因此 -1000 以正常速度進行反向播放。 速度 -1、0 和 1 具有特殊含義：速度 0 是 1000（正常播放）的簡寫。 速度 1 僅前進一幀，速度 -1 僅後退一幀。
	__u32	format	格式限制。 此欄位由驅動程式設定，而不是應用程式設定。 可能的值為 V4L2_DEC_START_FMT_NONE（如果沒有格式限制）或 V4L2_DEC_START_FMT_GOP（如果解碼器對完整的 GOP（影像組）進行操作）。 這通常是反向播放的情況：解碼器需要完整的 GOP，然後可以按相反的順序播放。 因此，要實現反向播放，應用程式必須將影片檔案中的最後一個 GOP 提供給解碼器，然後是之前的 GOP，等等。
struct	stop		包含 V4L2_DEC_CMD_STOP 命令的附加資料的結構體。
	__u64	pts	在此 pts 處停止播放，如果播放已經超過該時間戳，則立即停止。 如果你想在解碼最後一幀後停止，則將其保留為 0。
struct	raw
	__u32	data[16]	保留供將來擴充套件。 驅動程式和應用程式必須將陣列設定為零。
}

解碼器命令

V4L2_DEC_CMD_START	0	啟動解碼器。 當解碼器已經在執行或暫停時，此命令只會更改播放速度。 這意味著當解碼器暫停時呼叫 V4L2_DEC_CMD_START 將不會恢復解碼器。 你必須顯式地呼叫 V4L2_DEC_CMD_RESUME。 此命令有一個標誌：V4L2_DEC_CMD_START_MUTE_AUDIO。 如果設定，則以非標準速度播放時，音訊將被靜音。 對於實現 記憶體到記憶體狀態影片解碼器介面 的裝置，一旦使用 V4L2_DEC_CMD_STOP 命令啟動了清空序列，則必須將其驅動到完成才能呼叫此命令。 在清空序列正在進行時嘗試呼叫該命令將觸發 EBUSY 錯誤程式碼。 在解碼器本身啟動的隱式停止的情況下，也可以使用該命令重新啟動解碼器，而無需顯式呼叫 V4L2_DEC_CMD_STOP。 有關更多詳細資訊，請參見 記憶體到記憶體狀態影片解碼器介面。
V4L2_DEC_CMD_STOP	1	停止解碼器。 當解碼器已經停止時，此命令不執行任何操作。 此命令有兩個標誌：如果設定了 V4L2_DEC_CMD_STOP_TO_BLACK，則解碼器將在停止解碼後將圖片設定為黑色。 否則，將重複最後一張影像。 如果設定了 V4L2_DEC_CMD_STOP_IMMEDIATELY，則解碼器會立即停止（忽略 pts 值），否則它將繼續解碼，直到時間戳 >= pts 或解碼來自其內部緩衝區中的待處理資料的最後一條資料。 對於實現 記憶體到記憶體狀態影片解碼器介面 的裝置，該命令將啟動 記憶體到記憶體狀態影片解碼器介面 中記錄的清空序列。 在這種情況下，不接受任何標誌或其他引數。 在序列完成之前再次嘗試呼叫該命令將觸發 EBUSY 錯誤程式碼。
V4L2_DEC_CMD_PAUSE	2	暫停解碼器。 當解碼器尚未啟動時，驅動程式將返回 EPERM 錯誤程式碼。 當解碼器已經暫停時，此命令不執行任何操作。 此命令有一個標誌：如果設定了 V4L2_DEC_CMD_PAUSE_TO_BLACK，則在暫停時將解碼器輸出設定為黑色。
V4L2_DEC_CMD_RESUME	3	在 PAUSE 命令後恢復解碼。 當解碼器尚未啟動時，驅動程式將返回 EPERM 錯誤程式碼。 當解碼器已經在執行時，此命令不執行任何操作。 沒有為此命令定義標誌。
V4L2_DEC_CMD_FLUSH	4	重新整理任何保持的捕獲緩衝區。 僅對無狀態解碼器有效。 當應用程式到達流的末尾並且最後一個輸出緩衝區設定了 V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF 標誌時，通常使用此命令。 這將阻止出隊包含最後一個解碼幀的捕獲緩衝區。 因此，可以使用此命令顯式重新整理該最終解碼幀。 如果沒有保持的捕獲緩衝區，則此命令不執行任何操作。

7.7.5. 返回值

成功時返回 0，出錯時返回 -1，並適當設定 errno 變數。 通用錯誤程式碼在 通用錯誤程式碼 章節中進行了描述。

EBUSY

實現 記憶體到記憶體狀態影片解碼器介面 的裝置的清空序列仍在進行中。 不允許發出另一個解碼器命令，直到它完成。

EINVAL

cmd 欄位無效。

EPERM

當解碼器未執行時，應用程式傳送了 PAUSE 或 RESUME 命令。