Реализация 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. Этот параметр представляет параметры кодировщика и является тем же экземпляром IPropertyBag2 , который был создан в методе CreateNewFrame декодера уровня контейнера и передан обратно вызывающей стороне в параметре pIEncoderOptions этого метода. В это время вы заполнили структуру IPropertyBag2 свойствами, которые представляют параметры кодирования, поддерживаемые кодировщиком уровня кадра. Вызывающий объект теперь предоставил значения для этих свойств для указания определенных параметров кодирования и передает вам тот же объект для инициализации объекта IWICBitmapFrameEncode . При кодировании битов изображения следует применять указанные параметры.

SetSize и SetResolution

SetSize и SetResolution являются понятными. Вызывающий объект использует эти методы для указания размера и разрешения закодированного изображения.

SetPixelFormat

SetPixelFormat используется для запроса формата пикселей для кодирования изображения. Если запрошенный формат пикселей не поддерживается, следует вернуть GUID ближайшего формата пикселей, поддерживаемого в pPixelFormat, который является параметром in/out.

SetColorContexts

SetColorContexts используется для указания одного или нескольких допустимых контекстов цвета (также известных как цветовые профили) для этого изображения. Важно указать контексты цвета, чтобы приложение, которое позже декодирует изображение, ему хочет преобразовать исходный цветной профиль в профиль назначения устройства, используемого для отображения или печати изображения. Без цветового профиля невозможно получить согласованные цвета на разных устройствах. Это может быть неприятно для конечных пользователей, когда их фотографии выглядят по-разному на разных мониторах, и они не могут получить отпечатки, соответствующие тому, что они видят на экране.

GetMetadataQueryWriter

GetMetadataQueryWriter возвращает IWICMetadataQueryWriter , который приложение может использовать для вставки или изменения определенных свойств метаданных в блоке метаданных в кадре изображения.

Вы можете создать экземпляр IWICMetadataQueryWriter из IWICComponentFactory несколькими способами. Вы можете создать его из IWICMetadataBlockWriter так же, как IWICMetadataQueryReader был создан из IWICMetadataBlockReader в методе GetMetadataQueryReader в интерфейсе IWICBitmapFrameDecode .

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 являются необязательными на уровне контейнера, но если кодек возвращает WINCODEC_ERR_CODECNOTHUMBNAIL из метода GetThumbnail , компонент образов Windows (WIC) вызывает метод GetThumbnail для frame 0. Если эскиз не найден в любом месте, WIC должен декодировать полное изображение и масштабировать его до размера эскиза, что может привести к значительному уменьшению производительности для более крупных изображений.

Эскиз должен иметь размер и разрешение, что позволяет быстро декодировать и отображать его. По этой причине эскизы чаще всего представляют собой изображения JPEG. Обратите внимание, что если вы используете jpeg для эскизов, вам не нужно писать кодировщик JPEG для их кодирования или декодер JPEG для их декодирования. Всегда следует делегировать кодеку JPEG, который поставляется с платформой WIC для кодирования и декодирования эскизов.

WritePixels

WritePixels — это метод, используемый для передачи строк сканирования из растрового изображения в память для кодирования. Метод будет вызываться повторно, пока не будут переданы все строки сканирования. Параметр lineCount указывает, сколько строк сканирования необходимо записать в этом вызове. Параметр cbStride указывает количество байтов на строку сканирования. cbBufferSize указывает размер буфера, переданного в параметре pbPixels, который содержит фактические биты изображения для кодирования. Если совокупная высота строк сканирования из кумулятивных вызовов превышает высоту, указанную в методе SetSize , верните WINCODEC_ERR_TOOMANYSCANLINES.

Если wicBitmapEncoderCacheOption имеет значение WICBitmapEncoderCacheInMemory, строки сканирования должны кэшироваться в памяти до тех пор, пока не будут переданы все строки сканирования. Если параметр кэша кодировщика — WICBitmapEncoderCacheTempFile, строки сканирования должны кэшироваться во временном файле, созданном при инициализации объекта. В любом из этих случаев изображение не должно быть закодировано до тех пор, пока вызывающий объект не вызовет Commit. Если параметр кэша — WICBitmapEncoderNoCache, кодировщик должен кодировать строки сканирования по мере их получения, если это возможно. (В некоторых форматах это невозможно, и строки сканирования должны кэшироваться до вызова commit.)

Большинство необработанных кодеков не реализуют 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

Общие сведения о компоненте обработки образов Windows