SunVideo Plus 1.3 使用者指南：SunVideo Plus 之 XIL 屬性

上一頁 | 下一頁 | 目錄
SunVideo Plus 1.3 使用者指南

# 5

# SunVideo Plus 之 XIL 屬性

本章說明專屬於 SunVideo Plus 的 XIL 屬性。本章節的資料假設您對於視訊壓縮和影像處理的觀念和在 XIL Programmer's Guide 中描述的 XIL 函數已經相當地熟悉。

XIL 透過一種延遲執行的方式作業。延遲執行會尋找特定的原子作業次序並將之組合成分子以降低執行時間。本章的〈分子〉一節會列示出經過加速的分子。若需其他關於一般的 XIL 程式設計的資訊，請參閱 Solaris XIL 1.0, Imaging Library Programmer's Guide。為開發人員提供的套件中，也有提供多種不同的 XIL 範例程式的原始程式碼，程式開發人員可以參考這些範例程式，來運用 XIL 和 SunVideo Plus 介面卡。

`MMACo1k` 是配合 SunVideo Plus 的 XIL 軟體驅動程式。透過下列 XIL 呼叫即可建立與 `MMACo1k` 之間的介面：

- `xil_device_create`(3)

- `xil_device_set_value`(3)

- `xil_create_from_device`(3)

- `xil_get_device_attribute`(3)

- `xil_set_device_attrribute`(3)

使用 `xil_device_create`(3) 時，device 參數應為 `MMACo1k`。使用 `xil_create_from_device`(3) 時，devicename 參數應為 `MMACo1k`，而 `deviceObj` 參數可設定為 NULL，此時會開啟 `/dev/o1k0`。若要開啟另一個裝置，例如：`/dev/o1k1`，請建立一個 `MMACo1k` 裝置，使用 `xil_device_set_value`(3) 設定這個裝置的 DEVICE_NAME 屬性。傳回的影像將會是一個 640x480 (NTSC) 或 768x576 (PAL) 3-色的 YUV 影像。

## 屬性概觀

為了維持二位元相容性，某些在 SunVideo Plus 上並無特殊用途的 SunVideo 屬性，在 SunVideo Plus 還是有限度的繼續支援其功能。

設定裝置屬性有兩種方法。第一種方法是在使用 `xil_create_from_device`(3) 函數之前，先呼叫 `xil_device_create`(3) 和 `xil_device_set_value`(3) 函數。第二種方式是在叫用 `xil_create_from_device`(3) 之後再叫用 `xil_device_set_value`(3)。某些屬性必須使用第一種方式設定 (例如：DEVICE_NAME 屬性)，本文稍後將列表註明哪些屬性必須採用第一種方式設定。若需其他資訊，請參閱「重要的屬性資訊」。

`MMACo1k` 裝置具有下列一般的裝置屬性，SunVideo 亦支援這些屬性：

- DEVICE_NAME

- FORMAT

- IMAGE_SKIP

- PORT_V

- MAX_BUFFERS

- PORT

- NUM_BUFFER

- FIRST_SCANLINE

- FULL_BUFFERS

- FLUSH_BUFFERS

- FORMAT_V

下列裝置屬性並無特殊作用，SunVideo Plus 會視情況忽視或處理這些裝置屬性，以維持跟 SunVideo 原始檔和執行檔的相容性。

- MPEG_RATE_CONTROL

- MPEG_FIXED_QUANT

- MPEG_WEIGHTS

- FILE DESCRIPTOR

- FRAME_NUMBER

- TIMESTAMP

以下為 SunVideo Plus 的視訊屬性：

- HUE

- H261_PIP

- CHROMA_GAIN_V

- CHROMA_GAIN_U

- BRIGHTNESS

- CONTRAST

- H261_BIT_RATE

- H261_MAX_QUANT

- H261_IBLOCK_REFRESH

- H261_FUR

以下各節將詳細為您說明這些屬性。請注意某些屬性是「只可設定」，而另有某些屬性則是 「只可擷取」 的。說明各種屬性時，在 「存取方式」 標題底下，會標明屬性的存取方式。部分屬性可以在 SunVideo Plus 控制台裡面設定。某些屬性雖然文中會列出屬性的預設值，實際上，這些屬性實際的設定值還是在控制台設定的數值或上次呼叫 XIL 函數設定屬性的時設定的數值。這些屬性在 「預設值」 欄位的資料前方會加上一個星號 (*)。若需其他資訊，請參閱「SunVideo Plus 控制台與 XIL 屬性」。

## 一般屬性

### DEVICE_NAME

這項屬性設定 `o1k` (SunVideo Plus) 裝置的路徑名稱。您必須在建立裝置影像之前，使用 `xil_device_create`(3) 和 `xil_device_set_value`(3) 函數設定這項屬性。

存取方式：設定/擷取
類型：char *
預設值："/dev/o1k0"

### PORT_V

這項屬性定義由三個連接埠其中的哪一個連接埠擷取視訊信號。

0 | S 視訊端子連接埠
1 | 複合視訊訊號 #1 號連接埠
2 | 複合視訊訊號 #2 號連接埠

存取方式：設定/擷取
類型：int
預設值：1

### PORT

這項屬性是一個用來設定連接埠的字串介面。

S VIDEO | S 視訊端子連接埠
COMPOSITE VIDEO 1 | 複合視訊訊號 #1 號連接埠
COMPOSITE VIDEO 2 | 複合視訊訊號 #2 號連接埠

存取方式：設定/擷取
類型：char *
* 預設值："COMPOSITE VIDEO 1"

### FORMAT_V

這項屬性在格式不明的情況下傳回 0，如果正在擷取 PAL 訊號時傳回 1，如果正在擷取 NTSC 訊號則傳回 2。若需其他資訊請參閱「視訊埠、格式及自動格式偵測」 。

存取方式：擷取
類型：int

### FORMAT

這項屬性會傳回目前擷取的視訊格式 (NTSC、PAL、或 UNKNOWN)。若需其他資訊請參閱「視訊埠、格式及自動格式偵測」 。

存取方式：擷取
類型：char *

### IMAGE_SKIP

這項屬性設定及傳回兩次擷取之間略過的影像數目。您可以使用 IMAGE_SKIP 屬性設定影像變化的步調。例如：用於支援保全攝影機時，可以將設定每間隔 30 秒才擷取一張影像。

IMAGE_SKIP 的另一個用途是配合特定的網路頻寬限制圖框的更新速率。若要以大約 10 fps 的速率擷取 NTSC 圖框，您可以將 IMAGE_SKIP 屬性設定為 2，讓 SunVideo Plus 介面卡每三張圖框才擷取一張影像。

存取方式：設定/擷取
類型：int
預設值：0

### MAX_BUFFERS

這項屬性設定和回傳 XIL SunVideo Plus 驅動程式在等待應用程式透過壓縮呼叫擷取壓縮後的圖框時，可以在緩衝區類儲存圖框的最大數量。其設定值可以設定在從 1 到 10 之間的數值。請參閱下圖。這項數值會配合實際記憶體的可用容量大小被減小到合理的數字。

##### 圖 5-1 緩衝區的最大數量

存取方式：設定/擷取
類型：integer
預設值：2

### NUM_BUFFERS

這項屬性會傳回一個整數，指出實際可以用來保存壓縮後圖框的緩衝區數量。NUM_BUFFERS 的數值應小於或等於 MAX_BUFFERS 屬性的設定值。

NUM_BUFFERS 在完成第一次擷取 (或擷取/壓縮) 作業後開始傳回有效數值。

存取方式：設定
類型：integer

### FULL_BUFFERS

這項屬性會傳回一個整數，指出目前含有有效資料的緩衝器的數量。FULL_BUFFERS 屬性在完成第一次擷取 (或 擷取/壓縮) 作業之後開始傳回有效數值。

存取方式：擷取
類型：integer

### FLUSH_BUFFERS

設定 FLUSH_BUFFERS 屬性後，在擷取下一張影像之前，會清除所有儲存在緩衝區裡的資料。作業完成後，FULL_BUFFERS 的設定值會再度設定為零。設定屬性時使用的設定值會被忽略。

存取方式：設定
類型：void

## Video Attributes

下述屬性會影響不同的視訊特性。請注意這些屬性都可以透過 XIL 以程式設定控制，也可以依照「使用 SunVideo Plus 控制台」中說明的方式設定。雖然在這裡會列出屬性的預設值，不過實際上真正的數值則須視最後由控制台或 XIL 程式設定的數值為準。

### HUE

這項屬性會影響視訊輸入信號的色調。

存取方式：設定/擷取
類型：int (範圍從 -128 到 +127)
* 預設值：0

### CHROMA_GAIN_U

這項屬性會影響視訊輸入信號 U 成分的色彩增益。

存取方式：設定/擷取
類型：int (範圍從 -128 到 +127)
* 預設值：0

### CHROMA_GAIN_V

這項屬性會影響視訊輸入信號 V 成分的色彩增益。

存取方式：設定/擷取
類型：int (範圍從 0 到 511)
* 預設值：180

### CONTRAST

這項屬性會影響視訊輸入信號 luma 部分的對比。

存取方式：設定/擷取
類型：int (範圍從 0 到 511)
* 預設值： 216

### LUMA_BRIGHTNESS

這項屬性會影響視訊輸入信號 luma 部分整體的亮度。

存取方式：設定/擷取
類型：int (範圍從 -128 到 +127)
* 預設值：0

## H.261 屬性

這些屬性專門適用於配合 H.261 壓縮或解壓縮時使用 SunVideo Plus。未以硬體進行壓縮或解壓縮作業時，這些屬性設定值均無效。

### H261_BIT_RATE

這項屬性設定所需之最大壓縮位元速率。這項速率的單位是每秒 1000 個位元。例如：預設值 256 就會設定最大位元速率是每秒 256000 位元 (32000 位元組/秒)。

存取方式：設定/擷取
類型：int (in kbits/sec)
預設值：256

### H261_MAX_QUANT

這項屬性設定所需之最大量子化。量子化因素愈低，壓縮後的影像品質就愈高。由於較低的量子化通常會導致每個影像所需的位元數增加，因而在位元速率相同的情況下，可能會降低圖框更新速率。相反的，增加量子化因數，則可以提高圖框更新速率，但是也會同時降低影像的品質。

存取方式：設定/擷取
類型：int (範圍：1 到 31)
預設值：10

### H261_IBLOCK_REFRESH

這項屬性會設定壓縮器在使用內部編碼區塊更新指定的 H261 巨集區塊以前，要等候的時間，以毫秒為單位設定。H261 要求每個巨集區塊必須以每 132 個圖框為單位編碼成為一組內部編碼區塊。如果以 10 fps 進行壓縮，代表一個區塊最多必須間隔 13 秒以後，才會做內部編碼。在容易漏失資料的網路環境中，漏掉一個圖框會導致影像解壓之後產生失真。如果必須等到 13 秒之後，才能更新不良區塊的資料應該是不能接受的。設定這項屬性的目的就是要在網路上 H261 資料流傳輸漏失資料時，加速更新巨集區塊。

存取方式：設定/擷取
類型：int
預設值：1500 (msec)

### H261_FUR

設定這個旗標會對 H.261 壓縮器發出一個快速更新請求。快速更新基本上就是要求一個內部/鍵值圖框。

存取方式：設定/擷取
類型：XIL_boolean
預設值：FALSE

### H261_PIP

這個旗標會告訴 H.261 解碼器在解碼影像的左上角嵌入本機所見的圖片。未進行硬體解碼時，嵌入影像的位置會呈現灰色的影像。

存取方式：設定/擷取
類型：XIL_boolean
預設值： FALSE

### HW_DECOMPRESS_CIS

這項屬性選取要執行哪一種 CIS 硬體加速解壓縮功能。預設值為 NULL 代表使用第一個被解壓縮分子碰到的 CIS 就會成為硬體加速解壓縮功能的目標。選取特定的 CIS 之後，硬體解壓縮分子碰到其他 CIS 時，就會拒絕進行解壓縮，並且將其他 CIS 轉由適當的 XIL 軟體解碼器解碼。將設定值設定為 -1 則完全取消硬體解壓縮功能。

由於 XIL 並沒有通知解壓縮器某個 CIS 已經損毀的功能，如果要為新的 CIS 進行硬體解壓縮時，一樣要設定這項屬性。

存取方式：設定/擷取
類型：XilCis
預設值：NULL

## 重要的屬性資訊

注意 - XIL 1.3 屬性此時不支援 擷取 屬性。

### 視訊埠、格式及自動格式偵測

XIL 驅動程式預設的工作方式是在裝置建立影像時，自動偵測選取的視訊連接埠上面的視訊格式。自動偵測的過程最多可能要 1.5 秒鐘才能完成。如果您事先就知道視訊信號的格式，可以使用 SunVideo Plus 控制台將設定值從 AUTO 改為視訊信號的格式 (NTSC 或 PAL)。這樣就不會自動偵測視訊格式。

SunVideo Plus 目前尚不支援在不同視訊連接埠連接格式兩種不同的視訊信號 (例如：NTSC 或 PAL)，並且在兩者之間動態切換的功能。在某個 XIL 應用程式裡建立裝置影像時，SunVideo Plus 驅動程式可能就自動偵測出選取的視訊連接埠的視訊信號格式。因此，如果您有多種不同的視訊信號格式連接到不同的視訊信號輸入連接埠，最好是在建立裝置影像之前，使用 xil_device_set_value(3) 指定使用哪一個視訊信號輸入連接埠。如果您並未將視訊信號連接埠連接預設的視訊輸入連接埠 (port 1) 時，亦應在建立裝置影像之前指定使用的視訊連接埠。

### HW 解壓縮和 CIS 之選擇

HW_DECOMPRESS_CIS 屬性可以用來設定選取哪一種 CIS 進行硬體加速的解壓縮功能。要解壓縮多種 CIS 的應用程式應該在進行任何 XIL 解壓縮分子之前，將這個屬性設定為 -1。這樣可以避免任何在 CIS 上，而您不想利用硬體解碼的解壓縮分子進入硬體解壓縮的程序。您碰到真正要使用硬體解壓縮的 CIS 上的解壓縮分子時，再設定 HW_DECOMPRESS_CIS 屬性。

### HW 解壓縮和建立一個 XIL 裝置

在進行硬體解壓縮時，SunVideo Plus 的動作就像一個 XIL 運算裝置，在其中加速解算 XIL 分子。單只進行解壓縮的應用程式，可以不必按照「建立範例 MMACo1k 裝置影像」中說明的方式，建立 `xil` 裝置和裝置影像。但是要設定會影響解壓縮的裝置專屬屬性的應用程式則必須建立 xil 裝置和裝置影像。在 XIL 中並無直接設定 SunVideo Plus 這種運算裝置某些屬性的方法，不能直接開啟裝置並且設定其屬性。所以要利用這些屬性，就一定要建立一個 xil 裝置和影像。若需其他資訊，請參閱「XIL 原始程式檔範例」。

如果某個裝置和裝置影像並未直接由應用程式建立的，硬體的 SunVideo Plus XIL 解壓縮分子會自動建立所需的裝置和裝置影像。不過，這個分子目前不會搜尋可用的硬體裝置作為加速器。它們目前會嘗試使用系統中的第一個裝置 (`/dev/o1k0`)。因此，如果在您的系統上安裝了多片 SunVideo Plus 介面卡，目前要使用每一片介面卡作為一種硬體加速的解壓縮裝置，唯一的方法就是明確的在應用程式裡使用不同的名稱來建立裝置和裝置影像。請參閱「XIL 原始程式檔範例」。

### 同時使用 HW 壓縮和 HW 解壓縮

上一節解釋過使用 SunVideo Plus 的硬體解壓縮分子時，如果尚未建立裝置和裝置影像，會自動予以建立。因此，如果某個應用程式在執行解壓縮分子之後，又建立 MMACo1k 裝置和裝置影像的話，它會收到先前執行解壓縮分子時建立的裝置和影像。不過，在 XIL 中要刪除裝置影像的時候，會發生問題。如果在應用程式中，同時要用到硬體壓縮功能和硬體解壓縮功能的話，就必須在進行第一個硬體解壓縮分子之前，明確的建立一組裝置和裝置影像。

### SunVideo Plus 控制台與 XIL 屬性

所有在 SunVideo Plus 控制台裡面設定的參數，都具有功能相同的 XIL 屬性，讓應用程式的開發人員得以撰寫程式來設定變更這些參數。由於這些參數的數值都是目前在控制台裡面設定的數值，所以在 XIL 之中，這些參數都沒有特定的預設值。因此，除非應用程式有特別加以設定的視訊屬性以外，都會採用控制台裡面的設定值。

這是 SunVideo Plus 提供的功能。它免除了 XIL 應用程式設定視訊參數 (亮度、對比等等) 的責任。讓使用者只要配合它們使用的視訊信號源設定這些視訊參數一次，不必每次執行 XIL 應用程式時就得重複進行相同的設定。

請注意這些 XIL 屬性和控制台中的參數的設定值都來自相同的來源。因此，透過叫用 XIL 設定屬性的函數變更某個參數，也會在控制台中反映出來。例如：如果某個 XIL 應用程式將亮度設定到某個設定值，然後結束離開後，下一個啟動執行的 XIL 應用程式如果沒有變更設定，就會使用剛才變更後的亮度設定值。

## 分子

下表列出 MMACo1k 目前支援的彩色和灰階分子。表 5-1 列出了彩色的分子。

- 彩色分子

  - capture > scale8nearest

  - capture > [scale8nearest >] colorconvert

  - capture > [rescale8>][scale8nearest>] ordereddither8_8

  - capture > scale8nearest > rescale8 > orderedditther8_8

- 壓縮分子

  - capture > [scale8nearest] compress_CellB

  - capture > [scale8nearest] compress_Jpeg

  - capture > [scale8nearest] compress_Mpeg1

  - capture > [scale8nearest] compress_H261

  - capture > [scale8nearest] compress_UYVY

- 灰階分子

  - capture > scale8nearest

  - capture > [scale8nearest >[[addconst8 >] addconst8 >] addconst8

  - capture > [scale8nearest][threshold8 >] threshold8

  - capture > [scal8nearest][threshold8 >] threshold8 > addconst8

- 解壓縮分子

  - decompress_H261

  - decompress_H261 > [rescale8 >] ordereddither8_8

  - decompress_H261 > colorconvert

  - decompress_H261 > [rescale8 >] ordereddither8_8 > display_ioSUNWgx

## 錯誤

下表列出了 `MMACo1k` 裝置驅動程式的錯誤訊息。

#### 表 5-1 `MMACo1k` 錯誤訊息

錯誤訊息 | 說明
`MMACo1k`-1 | `MMACo1k`：錯誤的 PORT 規格
`MMACo1k`-4 | `MMACo1k`：無法開啟 `MMACo1k` 裝置。發生這項錯誤的原因會列示到預設的錯誤處理器中。可能的原因有： - 指定的裝置目前正由其他程式使用當中。 - 系統未安裝指定的裝置。 - 程式指定錯誤的裝置編號。
`MMACo1k`-5 | `MMACo1k`：無法設定視訊特性。程式無法設定連接埠特性值。
其他 XIL 錯誤訊息的清單請參閱《XIL Programmer's Guide》的附錄 B。

## 建立範例 `MMACo1k` 裝置影像

建立一組裝置影像設定連接到 SunVideo Plus 介面卡，再設定視訊連接埠使用 COMPOSITE VIDEO 2。請鍵入：

    # XilImage 影像
    # XilDevice 影像

where image = `xil_create_from_device`(state, "`MMACo1k`", device);
device = `xil_device_create`(state, "`MMACo1k`")
`xil_device_set_value`(device, "`DEVICE_NAME`", (void *) "`/dev/o1k0`");
`xil_device_set_value`(device, "PORT", (void *) "COMPOSITE VIDEO 2")

## XIL 原始程式檔範例

有關使用 XIL 程式介面的資訊最好的來源就在開發工具組提供的 XIL 範例程式裡面。下表列出了這些範例程式的名稱及說明。

#### 表 5-2 XIL 原始程式範例

XIL 原始程式範例 | 說明
`xil_display` | 視訊擷取與顯示範例程式。這個範例可以輕易的修改成為視訊錄影器或放影器。
`xil_compress` | 視訊壓縮範例程式。這個範例顯示出如何以不同的格式壓縮影像並且儲存到硬碟上。它同時也顯示出設定裝置專屬屬性的方法，例如設定 H.261 壓縮格式的位元速率的方法。
`xil_decompress` | 示範進行視訊解壓縮方法的範例程式。因為 XIL 軟體解碼器可以自動進行所需的作業，這個範例程式的大部分內容都不需要用到硬體解壓縮的裝置。不過，範例當中還是介紹了使用 SunVideo Plus 硬體解壓縮裝置進行 H261 解壓縮的方法。
`xil_broadcast` | 這個範例示範了如何擷取和壓縮視訊的方法，以及同時壓縮後的視訊信號透過網路使用 UDP 廣播的方法。
`xil_receive` | 這個範例示範了如何從 `xil_broadcast` 接收視訊信號的方法，以及如何加以解壓縮並且顯示出來的方法。
`xilh_broadcast` | 跟 `xil_broadcast` 相同，不過增加了 H261。
`xilh_receive` | 跟 `xil_receive` 相同，不過增加了 H261。
`o1k_conf` | 使用 XIL 和 `libotiadudio` 的 GUI 點對點視訊會議應用程式。

上一頁 | 下一頁 | 目錄