ImageAttributes：：ClearColorMatrices 方法 (gdiplusimageattributes.h)

發行項
08/24/2023

ImageAttributes：：ClearColorMatrices方法會清除指定類別的色彩調整矩陣和灰階調整矩陣。

語法

Status ClearColorMatrices(
  [in, optional] ColorAdjustType type
);

參數

[in, optional] type

類型： ColorAdjustType

ColorAdjustType列舉的元素，指定清除調整矩陣的類別。預設值為 ColorAdjustTypeDefault。

傳回值

類型：狀態

如果方法成功，它會傳回 Ok，這是 Status 列舉的元素。

如果方法失敗，它會傳回 Status 列舉的其中一個其他元素。

備註

ImageAttributes物件會維護五個調整類別的色彩和灰階設定：預設、點陣圖、筆刷、手寫筆和文字。例如，您可以指定一對 (色彩和灰階) 預設類別的調整矩陣、點陣圖類別的不同調整矩陣組，以及畫筆類別的調整矩陣組。

預設色彩和灰階調整設定會套用至沒有自己調整設定的所有類別。例如，如果您從未指定畫筆類別的任何調整設定，則預設設定會套用至畫筆類別。

一旦您指定特定類別的色彩或灰階調整設定，預設調整設定就不再套用至該類別。例如，假設您指定一對 (色彩和灰階) 調整矩陣，以及預設類別的 gamma 值。如果您藉由呼叫 ImageAttributes：：SetColorMatrices來設定手寫筆類別的一對調整矩陣，則預設調整矩陣將不會套用至畫筆。如果您稍後呼叫 ImageAttributes：：ClearColorMatrices來清除畫筆調整矩陣，則畫筆類別將不會還原為預設調整矩陣;相反地，畫筆類別不會有任何調整矩陣。同樣地，畫筆類別不會還原為預設的 gamma 值;相反地，畫筆類別不會有 gamma 值。

範例

下列範例會從 .emf 檔案建立 Image 物件。程式碼也會建立 ImageAttributes 物件。第一次呼叫 ImageAttributes：：SetColorMatrices 會設定預設色彩調整矩陣和 ImageAttributes 物件的預設灰階調整矩陣。第二次呼叫 ImageAttributes：：SetColorMatrices 會設定畫筆色彩調整矩陣和 ImageAttributes 物件的畫筆灰階調整矩陣。四個矩陣的執行方式如下：

預設色彩：將紅色元件乘以 1.5。
預設灰階：將綠色元件乘以 1.5。
手寫筆色彩：將藍色元件乘以 1.5。
手寫筆灰階：將紅色、綠色和藍色元件乘以 1.5。

程式碼會呼叫 DrawImage 一次，以繪製沒有色彩調整的影像。然後程式碼會多次呼叫DrawImage，每次傳遞 Image 物件的位址和ImageAttributes物件的位址。第二次在設定預設矩陣) 的呼叫之後繪製影像 (，所有色彩都會增加 50% 的紅色元件，而所有灰色的綠色元件都會增加 50%。第三次 (在設定畫筆矩陣) 的呼叫之後繪製影像時，畫筆繪製的所有色彩都會增加 50%，而畫筆所繪製的所有灰色都會增加 50%，而畫筆所繪製的所有灰色都會增加 50%。第四次 (在呼叫 ImageAttributes：：ClearColorMatrices) 之後繪製影像時，不會對畫筆繪製的色彩和灰色套用任何調整。


VOID Example_SetClearColorMatrices(HDC hdc)
{
   Graphics graphics(hdc);

   Image            image(L"TestMetafile6.emf");
   ImageAttributes  imAtt;
   RectF            rect;
   Unit             unit;

   image.GetBounds(&rect, &unit);

   ColorMatrix defaultColorMatrix = {  // Multiply red component by 1.5.
      1.5f,  0.0f,  0.0f,  0.0f,  0.0f,
      0.0f,  1.0f,  0.0f,  0.0f,  0.0f,
      0.0f,  0.0f,  1.0f,  0.0f,  0.0f,
      0.0f,  0.0f,  0.0f,  1.0f,  0.0f,
      0.0f,  0.0f,  0.0f,  0.0f,  1.0f};

   ColorMatrix defaultGrayMatrix = {  // Multiply green component by 1.5.
      1.0f,  0.0f,  0.0f,  0.0f,  0.0f,
      0.0f,  1.5f,  0.0f,  0.0f,  0.0f,
      0.0f,  0.0f,  1.0f,  0.0f,  0.0f,
      0.0f,  0.0f,  0.0f,  1.0f,  0.0f,
      0.0f,  0.0f,  0.0f,  0.0f,  1.0f};

   ColorMatrix penColorMatrix = {     // Multiply blue component by 1.5.
      1.0f,  0.0f,  0.0f,  0.0f,  0.0f,
      0.0f,  1.0f,  0.0f,  0.0f,  0.0f,
      0.0f,  0.0f,  1.5f,  0.0f,  0.0f,
      0.0f,  0.0f,  0.0f,  1.0f,  0.0f,
      0.0f,  0.0f,  0.0f,  0.0f,  1.0f};

   ColorMatrix penGrayMatrix = {      // Multiply all components by 1.5.
      1.5f,  0.0f,  0.0f,  0.0f,  0.0f,
      0.0f,  1.5f,  0.0f,  0.0f,  0.0f,
      0.0f,  0.0f,  1.5f,  0.0f,  0.0f,
      0.0f,  0.0f,  0.0f,  1.0f,  0.0f,
      0.0f,  0.0f,  0.0f,  0.0f,  1.0f};

   // Set the default color- and grayscale-adjustment matrices.
   imAtt.SetColorMatrices(
      &defaultColorMatrix,
      &defaultGrayMatrix, 
      ColorMatrixFlagsAltGray,
      ColorAdjustTypeDefault); 

   graphics.DrawImage(&image, 10.0f, 10.0f, rect.Width, rect.Height);

   graphics.DrawImage(
      &image, 
      RectF(10.0f, 50.0f, rect.Width, rect.Height),  // destination rectangle 
      rect.X, rect.Y,                // upper-left corner of source rectangle 
      rect.Width,                    // width of source rectangle
      rect.Height,                   // height of source rectangle
      UnitPixel,
      &imAtt);

   // Set the pen color- and grayscale-adjustment matrices.
   imAtt.SetColorMatrices(
      &penColorMatrix,
      &penGrayMatrix, 
      ColorMatrixFlagsAltGray,
      ColorAdjustTypePen); 

   graphics.DrawImage(
      &image, 
      RectF(10.0f, 90.0f, rect.Width, rect.Height),  // destination rectangle 
      rect.X, rect.Y,                // upper-left corner of source rectangle 
      rect.Width,                    // width of source rectangle
      rect.Height,                   // height of source rectangle
      UnitPixel,
      &imAtt);

   imAtt.ClearColorMatrices(ColorAdjustTypePen);

   graphics.DrawImage(
      &image, 
      RectF(10.0f, 130.0f, rect.Width, rect.Height),  // destination rectangle 
      rect.X, rect.Y,                // upper-left corner of source rectangle 
      rect.Width,                    // width of source rectangle
      rect.Height,                   // height of source rectangle
      UnitPixel,
      &imAtt); 
}

下圖顯示上述程式碼的輸出。

需求


最低支援的用戶端	Windows XP、Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	gdiplusimageattributes.h (include Gdiplus.h)
程式庫	Gdiplus.lib
Dll	Gdiplus.dll