다음을 통해 공유

IWICBitmapFrameEncode 구현

  • 아티클

IWICBitmapFrameEncode

IWICBitmapFrameEncode 는 IWICBitmapFrameDecode 인터페이스에 대한 인코더의 대응입니다. 각 프레임에 대한 이미지 비트의 실제 인코딩을 수행하는 클래스인 프레임 수준 인코딩 클래스에서 이 인터페이스를 구현할 수 있습니다.

interface IWICBitmapFrameEncode : public IUnknown
{
   // Required methods
   HRESULT Initialize ( IPropertyBag2 *pIEncoderOptions );
   HRESULT SetSize ( UINT width,
               UINT height );
   HRESULT SetResolution ( double dpiX,
               double dpiY );
   HRESULT SetPixelFormat (WICPixelFormatGUID *pPixelFormat);
   HRESULT SetColorContexts ( UINT cCount,
               IWICColorContext **ppIColorContext );
   HRESULT GetMetadataQueryWriter ( IWICMetadataQueryWriter 
               **ppIMetadataQueryWriter );
   HRESULT SetThumbnail ( IWICBitmapSource *pIThumbnail );
   HRESULT WritePixels ( UINT lineCount,
               UINT cbStride,
               UINT cbBufferSize,
               BYTE *pbPixels );
   HRESULT WriteSource ( IWICBitmapSource *pIWICBitmapSource,
               WICRect *prc );
   HRESULT Commit ( void );

// Optional method
   HRESULT SetPalette ( IWICPalette *pIPalette );
};

Initialize

Initialize 는 인스턴스화된 후 IWICBitmapFrameEncode 개체에서 호출된 첫 번째 메서드입니다. 이 메서드에는 NULL로 설정할 수 있는 매개 변수가 하나 있습니다. 이 매개 변수는 인코더 옵션을 나타내며 컨테이너 수준 디코더의 CreateNewFrame 메서드에서 만든 것과 동일한 IPropertyBag2 instance 해당 메서드의 pIEncoderOptions 매개 변수에서 호출자에게 다시 전달됩니다. 이때 IPropertyBag2 구조체를 프레임 수준 인코더에서 지원하는 인코딩 옵션을 나타내는 속성으로 채웠습니다. 호출자는 이제 특정 인코딩 옵션 매개 변수를 나타내기 위해 해당 속성에 대한 값을 제공했으며 동일한 개체를 다시 전달하여 IWICBitmapFrameEncode 개체를 초기화합니다. 이미지 비트를 인코딩할 때 지정된 옵션을 적용해야 합니다.

SetSize 및 SetResolution

SetSize 및 SetResolution 은 설명이 필요 없습니다. 호출자는 이러한 메서드를 사용하여 인코딩된 이미지의 크기와 해상도를 지정합니다.

SetPixelFormat

SetPixelFormat 은 이미지를 인코딩할 픽셀 형식을 요청하는 데 사용됩니다. 요청된 픽셀 형식이 지원되지 않는 경우 in/out 매개 변수인 pPixelFormat에서 지원되는 가장 가까운 픽셀 형식의 GUID를 반환해야 합니다.

SetColorContexts

SetColorContexts 는 이 이미지에 대해 하나 이상의 유효한 색 컨텍스트(색 프로필이라고도 함)를 지정하는 데 사용됩니다. 나중에 이미지를 디코딩하는 애플리케이션이 원본 색 프로필에서 이미지를 표시하거나 인쇄하는 데 사용되는 디바이스의 대상 프로필로 변환할 수 있도록 색 컨텍스트를 지정하는 것이 중요합니다. 색 프로필이 없으면 여러 디바이스에서 일관된 색을 얻을 수 없습니다. 사진이 다른 모니터에서 다르게 보이고 화면에 표시되는 것과 일치하는 인쇄를 가져올 수 없는 경우 최종 사용자에게는 실망스러울 수 있습니다.

GetMetadataQueryWriter

GetMetadataQueryWriter는 애플리케이션이 이미지 프레임의 메타데이터 블록에 특정 메타데이터 속성을 삽입하거나 편집하는 데 사용할 수 있는 IWICMetadataQueryWriter 를 반환합니다.

여러 가지 방법으로 IWICComponentFactory에서 IWICMetadataQueryWriter를 인스턴스화할 수 있습니다. IWICMetadataBlockWriter에서 IWICMetadataQueryReader가 IWICBitmapFrameDecode 인터페이스의 GetMetadataQueryReader 메서드에 있는 IWICMetadataBlockReader에서 만든 것과 동일한 방식으로 만들 수 있습니다.

IWICMetadataQueryWriter* piMetadataQueryWriter = NULL;
HRESULT hr;

hr = m_piComponentFactory->CreateQueryWriterFromBlockWriter( 
      static_cast<IWICMetadataBlockWriter*>(this), 
      &piMetadataQueryWriter);

이전 메서드를 사용하여 가져온 것과 같은 기존 IWICMetadataQueryReader에서 만들 수도 있습니다.

hr = m_piComponentFactory->CreateQueryWriterFromReader( 
      piMetadataQueryReader, pguidVendor, &piMetadataQueryWriter);

pguidVendor 매개 변수를 사용하면 메타데이터 작성기를 인스턴스화할 때 사용할 쿼리 작성기에 대한 특정 공급업체를 지정할 수 있습니다. 예를 들어 고유한 메타데이터 작성기를 제공하는 경우 고유한 공급업체 GUID를 지정할 수 있습니다. 기본 설정이 없는 경우 이 매개 변수에 NULL 을 전달할 수 있습니다.

SetThumbnail

SetThumbnail 은 썸네일을 제공하는 데 사용됩니다. 모든 이미지는 전역적으로, 각 프레임 또는 둘 다에 썸네일을 제공해야 합니다. GetThumbnail 및 SetThumbnail 메서드는 컨테이너 수준에서 선택 사항이지만 코덱이 GetThumbnail 메서드에서 WINCODEC_ERR_CODECNOTHUMBNAIL 반환하는 경우 WIC(Windows 이미징 구성 요소)는 프레임 0에 대한 GetThumbnail 메서드를 호출합니다. 두 위치에서 썸네일을 찾을 수 없는 경우 WIC는 전체 이미지를 디코딩하고 축소판 그림 크기로 확장해야 하므로 더 큰 이미지에 대한 성능 저하가 발생할 수 있습니다.

썸네일은 디코딩 및 표시를 빠르게 할 수 있는 크기와 해상도여야 합니다. 이러한 이유로 썸네일은 가장 일반적으로 JPEG 이미지입니다. 축소판 그림에 JPEG를 사용하는 경우 인코딩할 JPEG 인코더나 디코딩할 JPEG 디코더를 작성할 필요가 없습니다. 미리 보기 인코딩 및 디코딩을 위해 WIC 플랫폼과 함께 제공되는 JPEG 코덱에 항상 위임해야 합니다.

Writepixels

WritePixels 는 인코딩을 위해 메모리의 비트맵에서 스캔 줄을 전달하는 데 사용되는 메서드입니다. 메서드는 모든 검사 줄이 전달될 때까지 반복적으로 호출됩니다. lineCount 매개 변수는 이 호출에서 작성할 검사 줄 수를 나타냅니다. cbStride 매개 변수는 검사 줄당 바이트 수를 나타냅니다. cbBufferSize 는 인코딩할 실제 이미지 비트를 포함하는 pbPixels 매개 변수에 전달된 버퍼의 크기를 나타냅니다. 누적 호출에서 검색 줄의 결합된 높이가 SetSize 메서드에 지정된 높이보다 크면 WINCODEC_ERR_TOOMANYSCANLINES 반환합니다.

WICBitmapEncoderCacheOption이 WICBitmapEncoderCacheInMemory이면 모든 검사 줄이 전달될 때까지 검색 줄을 메모리에 캐시해야 합니다. 인코더 캐시 옵션이 WICBitmapEncoderCacheTempFile인 경우 검색 줄은 개체를 초기화할 때 만든 임시 파일에 캐시되어야 합니다. 이러한 경우 중 하나에서 호출자가 Commit을 호출할 때까지 이미지를 인코딩하면 안 됩니다. 캐시 옵션이 WICBitmapEncoderNoCache인 경우 인코더는 가능한 경우 수신되는 검사 줄을 인코딩해야 합니다. 일부 형식에서는 이 작업을 수행할 수 없으며 커밋이 호출될 때까지 검사 줄을 캐시해야 합니다.

대부분의 원시 코덱은 원시 파일의 이미지 비트 변경을 지원하지 않으므로 WritePixels를 구현하지 않습니다. 원시 코덱은 여전히 WritePixels를 구현해야 하지만 메타데이터가 추가될 때 파일 크기가 증가하여 디스크에서 파일을 다시 작성해야 하기 때문입니다. 이 경우 WritePixels 메서드가 수행하는 기존 이미지 비트를 복사할 수 있어야 합니다.

WriteSource

WriteSource 는 IWICBitmapSource 개체를 인코딩하는 데 사용됩니다. 첫 번째 매개 변수는 IWICBitmapSource 개체에 대한 포인터입니다. 두 번째 매개 변수는 인코딩할 관심 영역을 지정하는 WICRect입니다. 각 사각형의 너비가 인코딩할 최종 이미지의 너비와 같은 경우 이 메서드를 연속해서 여러 번 호출할 수 있습니다. prc 매개 변수에 전달된 사각형의 너비가 SetSize 메서드에 지정된 너비와 다른 경우 WINCODEC_ERR_SOURCERECTDOESNOTMATCHDIMENSIONS 반환합니다. 누적 호출에서 검사 줄의 결합된 높이가 SetSize 메서드에 지정된 높이보다 크면 WINCODEC_ERR_TOOMANYSCANLINES 반환합니다.

캐시 옵션은 앞에서 설명한 WritePixels 메서드와 마찬가지로 이 메서드와 동일한 방식으로 작동합니다.

Commit

Commit 은 인코딩된 이미지 비트를 파일 스트림으로 직렬화하고 해당 메타데이터를 스트림으로 직렬화하도록 요청하는 프레임에 대한 모든 메타데이터 작성기를 반복하는 메서드입니다. 인코더 캐시 옵션이 WICBitmapEncoderCacheInMemory 또는 WICBitmapEncoderCacheTempFile인 경우 이 메서드는 이미지 인코딩을 담당하며 캐시 옵션이 WICBitmapEncoderCacheTempFile인 경우 Commit 메서드는 인코딩하기 전에 이미지 데이터를 캐시하는 데 사용되는 임시 파일도 삭제해야 합니다.

이 메서드는 이미지를 구성하는 모든 검사 줄 또는 사각형이 Commit 또는 WriteSource 메서드를 사용하여 전달된 후에 항상 호출됩니다. WritePixels 또는 WriteSource에 대한 누적 호출을 통해 구성된 최종 사각형의 크기는 SetSize 메서드에 지정된 크기와 동일해야 합니다. 크기가 예상 크기와 일치하지 않으면 이 메서드는 WINCODECERROR_UNEXPECTEDSIZE 반환해야 합니다.

메타데이터 작성기를 반복하고 각 메타데이터 기록기에 해당 메타데이터를 직렬화하도록 스트림으로 이동하도록 지시하려면 GetWriterByIndex를 호출하여 각 블록에 대한 기록기를 반복하고 각 메타데이터 작성기에서 IWICPersistStream.Save를 호출합니다.

IWICMetadataWriter* piMetadataWRiter = NULL;
IWICPersistStream* piPersistStream = NULL;
HRESULT hr;

for (UINT x=0; x < m_blockCount; x++) 
{
    hr = GetWriterByIndex(x, & piMetadataWriter);
hr = piMetadataWriter->QueryInterface(
IID_IWICPersistStream,(void**)&piPersistStream);

hr = piPersistStream->Save(m_piStream, 
WICPersistOptions.WicPersistOptionDefault, 
true);
...
}

SetPalette

인덱싱된 형식을 가진 코덱만 SetPalette 메서드를 구현해야 합니다. 이미지에서 인덱싱된 형식을 사용하는 경우 이 메서드를 사용하여 이미지에 사용되는 색 팔레트를 지정합니다. 코덱에 인덱싱된 형식이 없으면 이 메서드에서 WINCODEC_ERR_PALETTEUNAVAILABLE 반환합니다.

개념

IWICBitmapCodecProgressNotification 구현(인코더)

IWICMetadataBlockWriter 구현

WIC-Enabled CODEC를 작성하는 방법

Windows 이미징 구성 요소 개요