實現 IWICDevelopRaw

IWICDevelopRaw

IWICDevelopRaw 介面會公開原始影像處理特有的處理選項。所有原始編解碼器都必須支援 IWICDevelopRaw 介面。某些原始編解碼器可能無法支援此介面公開的每個設定，但您應該支援編解碼器能夠執行的所有設定。每個原始編解碼器至少都必須實作 SetRotation，並 SetRenderMode 方法。

此外，一些對其他編解碼器可選的方法和介面對於原始編解碼器則被強烈推薦。其中包括容器層級譯碼器類別上 GetPreview 和 GetThumbnail 方法，以及框架層級譯碼類別上的 IWICBitmapSourceTransform 介面。

使用 IWICDevelopRaw 方法所設置的設定應該以與其他元數據保存一致的方式由編解碼器保存，但您絕對不應該覆寫原始的「原始拍攝」設定。藉由保存元數據並實作 LoadParameterSet 和 GetCurrentParameterSet，您就可以讓原始處理應用程式跨會話擷取和套用處理設定。

IWICDevelopRaw 介面的主要目的是讓應用程式開發人員建置使用者介面，以調整原始參數，以便盡可能跨不同編解碼器一致地運作。假設終端使用者會使用滑桿控件來調整參數，其最小值和最大值會對應至參數的最小值和最大值。若要支援此功能，您應該盡一切努力將所有參數範圍視為線性。為了確保滑桿控件不會過度敏感，您也應該針對每個參數支援盡可能廣泛的範圍，至少涵蓋最大可能範圍的 50%。例如，如果最大可能的對比範圍是從純灰色到純黑色和白色，且預設值對應到0.0，編解碼器所支援的最低範圍會從預設值與低端的純灰色（–1.0）之間至少介於預設值與純黑色和白色之間（+1.0）。

interface IWICDevelopRaw : IWICBitmapFrameDecode
{
   HRESULT QueryRawCapabilitiesInfo ( WICRawCapabilitiesInfo *pInfo );
   HRESULT LoadParameterSet ( WICRawParameterSet ParameterSet );
   HRESULT GetCurrentParameterSet ( IPropertyBag2 **ppCurrentParameterSet );
   HRESULT SetExposureCompensation ( double ev );
   HRESULT GetExposureCompensation ( double *pEV );
   HRESULT SetWhitePointRGB ( UINT Red, UINT Green, UINT Blue );
   HRESULT GetWhitePointRGB ( UINT *pRed, UINT *pGreen, UINT *pBlue );
   HRESULT SetNamedWhitePoint ( WICNamedWhitePoint WhitePoint );
   HRESULT GetNamedWhitePoint ( WICNamedWhitePoint *pWhitePoint );
   HRESULT SetWhitePointKelvin ( UINT WhitePointKelvin );
   HRESULT GetWhitePointKelvin ( UINT *pWhitePointKelvin );
   HRESULT GetKelvinRangeInfo ( UINT *pMinKelvinTemp,
               UINT *pMaxKelvinTemp,
               UINT *pKelvinTempStepValue );
   HRESULT SetContrast ( double Contrast );
   HRESULT GetContrast ( double *pContrast );
   HRESULT SetGamma ( double Gamma );
   HRESULT GetGamma ( double *pGamma );
   HRESULT SetSharpness ( double Sharpness );
   HRESULT GetSharpness ( double *pSharpness );
   HRESULT SetSaturation ( double Saturation );
   HRESULT GetSaturation ( double *pSaturation );
   HRESULT SetTint ( double Tint );
   HRESULT GetTint ( double *pTint );
   HRESULT SetNoiseReduction ( double NoiseReduction );
   HRESULT GetNoiseReduction ( double *pNoiseReduction );
   HRESULT SetDestinationColorContext (const IWICColorContext *pColorContext );
   HRESULT SetToneCurve ( UINT cbToneCurveSize,
               const WICRawToneCurve *pToneCurve );
   HRESULT GetToneCurve ( UINT cbToneCurveBufferSize,
               WICRawToneCurve *pToneCurve,
               UINT *pcbActualToneCurveBufferSize );
   HRESULT SetRotation ( double Rotation );
   HRESULT GetRotation ( double *pRotation );
   HRESULT SetRenderMode ( WICRawRenderMode RenderMode );
   HRESULT GetRenderMode ( WICRawRenderMode *pRenderMode ); 
   HRESULT SetNotificationCallback ( IWICDevelopRawNotificationCallback 
               *pCallback );
}

QueryRawCapabilitiesInfo
LoadParameterSet
GetCurrentParameterSet
設定/獲取曝光補償
Set/GetCurrentParameterRGB、Set/GetNamedWhitePoint、Set/GetwhitePointKelvin
Set/GetContrast
Set/GetGamma
設定/取得銳利度
設定/獲取飽和度
設置/取得色調
設定/取得降噪
SetDestinationColorContext
設定/取得色調曲線
設置/獲取旋轉
設定/取得渲染模式
SetNotificationCallback

QueryRawCapabilitiesInfo

QueryRawCapabilitiesInfo 會傳回此源檔支援的一組功能。 WICRawCapabilitiesInfo 結構的定義如下：

struct WICRawCapabilitiesInfo
{
   UINT cbSize;
   UINT CodecMajorVersion;
   UINT CodecMinorVersion;
   WICRawCapabilities ExposureCompensationSupport;
   WICRawCapabilities ContrastSupport;
   WICRawCapabilities RGBWhitePointSupport;
   WICRawCapabilities NamedWhitePointSupport;
   UINT NamedWhitePointSupportMask;
   WICRawCapabilities KelvinWhitePointSupport;
   WICRawCapabilities GammaSupport;
   WICRawCapabilities TintSupport;
   WICRawCapabilities SaturationSupport;
   WICRawCapabilities SharpnessSupport;
   WICRawCapabilities NoiseReductionSupport;
   WICRawCapabilities DestinationColorProfileSupport;
   WICRawCapabilities ToneCurveSupport;
   WICRawRotationCapabilities RotationSupport;              
}

此結構中使用的 WICRawCapabilities 列舉定義為：

enum WICRawCapabilities 
{   
   WICRawCapabilityNotSupported,
   WICRawCapabilityGetSupported,
   WICRawCapabilityFullySupported
}

最後一個字段是 WICRawRotationCapabilities 列舉，定義為：

enum WICRawRotationCapabilities                    
{
   WICRawRotationCapabilityNotSupported,
   WICRawRotationCapabilityGetSupported,
   WICRawRotationCapabilityNinetyDegreesSupported
   WICRawRotationCapabilityFullySupported
}

載入參數集

LoadParameterSet 可讓使用者指定要使用 As Shot 設定、使用使用者調整的設定，或要求譯碼器自動更正影像。

enum WICRawParameterSet
{
   WICAsShotParameterSet,
   WICUserAdjustedParameterSet,
   WICAutoAdjustedParameterSet
}

GetCurrentParameterSet

GetCurrentParameterSet 會傳回已設定目前參數的 IPropertyBag2。呼叫端接著可以將這組參數傳遞給編碼器，用作編碼器的選項。

設置/獲取曝光補償

GetExposureCompensation 和 SetExposureCompensation 表示要套用至最終輸出的曝光補償。 EV 的有效範圍是 –5.0 到 +5.0 檔位。

Set/GetCurrentParameterRGB、Set/GetNamedWhitePoint、Set/GetWhitePointKelvin

這些函式都提供取得和設定白點的方法，可以是 RGB 值、預設的具名值或 Kelvin 值。 Kelvin 可接受的範圍是 1,500 – 30,000。

提升/獲取對比度

GetContrast 和 SetContrast 表示要套用至輸出的對比量。要指定對比的有效範圍是 –1.0 到 +1.0，默認對比為 0.0。

Set/GetGamma

GetGamma 和 SetGamma 表示要套用的 Gamma。 Gamma 的有效範圍是 0.2 到 5.0，預設值為 1.0。 Gamma 通常是使用傳統的 Gamma 冪函數來實作（具有單一增益的線性冪函數）。增加伽瑪時，亮度會增加；當伽瑪接近零時，亮度會減少。（請注意，最小值為非零，因為零會導致傳統 Gamma 計算出現零除錯誤。邏輯最小值限制為 1/max，這就是為什麼最小值為 0.2。）

設置/獲取銳度

GetSharpness 和 SetSharpness 表示要套用的銳化量。有效範圍是 –1.0 到 +1.0,0.0 是預設的銳化量，而 –1.0 表示完全沒有銳化。

設定/取得飽和度

GetSaturation 和 SetSaturation 表示要套用的飽和度量。指定飽和度的有效範圍是 –1.0 到 +1.0,0.0 是正常飽和度，–1.0 代表完整還原飽和度，+1.0 代表完整飽和度。

色彩設定/取得

GetTint 和 SetTint 表示要套用的色調，以綠色/洋紅色偏向。有效範圍是 –1.0 到 +1.0，綠色位於負數的一側，而洋紅位於正數的一側。色調比例被定義為與色溫正交。

設定/取得降噪

GetNoiseReduction 和 SetNoiseReduction 表示要套用的雜訊減少量。的有效範圍是 –1.0 到 +1.0,0.0 表示預設降雜訊量，–1.0 表示無雜訊降低，+1.0 表示最大雜訊降低。

設定目標顏色環境

SetDestinationColorContext 指定要套用至影像的色彩配置檔。您可以呼叫 getColorContexts 來擷取目前的色彩配置檔。

設置/獲取色調曲線

GetToneCurve 和 SetToneCurve 指定要套用的音調曲線。假設點之間的線性插補。 pToneCurve 是 WICRawToneCurve 結構，其中包含一個由 WICRawToneCurvePoint 結構組成的陣列，以及此陣列中的點數計數。

struct WICRawToneCurve 
{
   UINT cPoints;
   WICRawToneCurvePoint aPoints[];
}

WICRawToneCurvePoint 包含輸入值和輸出值。

struct WICRawToneCurvePoint 
{
   double Input;
   double Output;
}

當呼叫端在 pToneCurve 參數中傳遞 NULL 時，您應該在 pcbActualToneCurveBufferSize 參數中傳回 WICRawToneCurve 所需的大小。

設定/取得旋轉

GetRotation 和 SetRotation 表示要套用的旋轉程度。指定 90.0 的旋轉表示順時針旋轉 90 度。（使用 SetRotation，並使用 CopyPixels 方法來設定旋轉角度的差異在於，使用 setRotation 設定的旋轉角度應該由編解碼器保存，同時設定旋轉 CopyPixels 只會旋轉記憶體中的影像。

設置/獲取渲染模式

GetRenderMode 和 SetRenderMode 表示呼叫端所需的輸出品質層級。當使用者調整參數時，應用程式應該會顯示套用變更時實際影像外觀的非常快速近似值。為了達到此目的，影像通常會以螢幕解析度或更低解析度顯示，而不是實際的圖像解析度，以便能立即提供反饋給使用者。這是當應用程式要求草稿模式品質時，因此應該非常快速。當使用者完成所有變更、在草稿模式中預覽，並決定以目前設定解碼完整影像時，應用程式會要求進行最佳品質解碼。這通常也會要求列印。在需要對速度和品質進行合理取捨時，應用程式會要求標準品質。

enum WICRawRenderMode
{
   WICRawRenderModeDraftMode,
   WICRawRenderModeNormalQuality ,
   WICRawRenderModeBestQuality
}

SetNotificationCallback

SetNotificationCallback 註冊了一個用於當任何原始處理參數變更時通知譯碼器的回呼函數。 IWICDevelopRawNotificationCallback 的簽章只有一個方法，稱為 Notify。 Notify 具有單一參數，這是一個遮罩，指出哪些原始處理參數已變更。

HRESULT Notify ( UINT NotificationMask );

OR 作業會在 NotificationMask 的下列值上執行。

WICRawChangeNotification_ExposureCompensation
WICRawChangeNotification_NamedWhitePoint
WICRawChangeNotification_KelvinWhitePoint
WICRawChangeNotification_RGBWhitePoint
WICRawChangeNotification_Contrast
WICRawChangeNotification_Gamma
WICRawChangeNotification_Sharpness
WICRawChangeNotification_Saturation
WICRawChangeNotification_Tint
WICRawChangeNotification_NoiseReduction
WICRawChangeNotification_DestinationColorContext
WICRawChangeNotification_ToneCurve
WICRawChangeNotification_Rotation
WICRawChangeNotification_RenderMode

參考
IWICDevelopRaw
概念
實作 IWICBitmapSourceTransform
實作 WIC-Enabled 編碼器
如何撰寫 WIC-Enabled CODEC
Windows 映射元件概觀

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-03-21