Implementowanie IWICBitmapEncoder
IWICBitmapEncoder
Ten interfejs jest odpowiednikiem interfejsu IWICBitmapDecoder i jest punktem wyjścia do kodowania pliku obrazu. Podobnie jak IWICBitmapDecoder służy do pobierania właściwości na poziomie kontenera i pojedynczych ramek z kontenera obrazu, IWICBitmapEncoder służy do ustawiania właściwości na poziomie kontenera i serializacji pojedynczych ramek obrazów w kontenerze. Ten interfejs należy zaimplementować w klasie kodera na poziomie kontenera.
interface IWICBitmapEncoder : public IUnknown
{
// Required methods
HRESULT Initialize ( IStream *pIStream,
WICBitmapEncoderCacheOption cacheOption );
HRESULT GetContainerFormat ( GUID *pguidContainerFormat );
HRESULT GetEncoderInfo ( IWICBitmapEncoderInfo **pIEncoderInfo );
HRESULT CreateNewFrame ( IWICBitmapFrameEncode **ppIFrameEncode,
IPropertyBag2 **ppIEncoderOptions );
HRESULT Commit ( void );
// Optional methods
HRESULT SetPreview ( IWICBitmapSource *pIPreview );
HRESULT SetThumbnail ( IWICBitmapSource *pIThumbnail );
HRESULT SetColorContexts ( UINT cCount,
IWICColorContext **ppIColorContext );
HRESULT GetMetadataQueryWriter ( IWICMetadataQueryWriter
**ppIMetadataQueryWriter );
HRESULT SetPalette ( IWICPalette *pIPalette);
};
Zgodnie z opisem w sekcjach idotyczących Implementowania IWICBitmapDecoder, niektóre formaty obrazów mają globalne miniatury, konteksty kolorów lub metadane, podczas gdy wiele formatów obrazów dostępnych jest jedynie dla poszczególnych ramek. Dlatego metody ustawiania tych metod są opcjonalne w IWICBitmapEncoder, ale są wymagane w IWICBitmapFrameEncode. Omówimy metody opcjonalne w IWICBitmapEncoder w sekcji IWICBitmapFrameEncode, gdzie są one najczęściej implementowane.
Jeśli nie obsługujesz globalnych miniatur, zwróć WINCODEC_ERR_CODECNOTHUMBNAIL z metody SetThumbnail w IWICBitmapEncoder. Jeśli nie obsługujesz palety na poziomie kontenera lub jeśli kodowany obraz nie ma indeksowanego formatu, zwróć WINCODEC_ERR_PALETTEUNAVAILABLE z metody SetPalette. W przypadku innych nieobsługiwanych metod należy zwrócić WINCODEC_ERR_UNSUPPORTEDOPERATION.
Zainicjuj
Initialize jest pierwszą metodą wywoływaną na IWICBitmapEncoder po jego zainicjowaniu. Strumień obrazu jest przekazywany do kodera, a użytkownik może opcjonalnie określić opcję pamięci podręcznej. W przypadku dekodera strumień jest tylko do odczytu, ale strumień przekazywany do kodera jest strumieniem zapisywalnym, w którym koder będzie serializować wszystkie dane obrazu i metadane. Opcje pamięci podręcznej w koderze również są różne.
enum WICBitmapEncoderCacheOption
{
WICBitmapEncoderCacheInMemory,
WICBitmapEncoderCacheTempFile,
WICBitmapEncoderNoCache
}
Aplikacja może wybrać między żądaniem od kodera buforowania danych obrazu w pamięci, buforowaniem w pliku tymczasowym, a zapisem danych bezpośrednio do pliku na dysku bez buforowania. Po wyświetleniu monitu o buforowanie danych w pliku tymczasowym koder powinien utworzyć plik tymczasowy na dysku i zapisać bezpośrednio do tego pliku bez buforowania w pamięci. Gdy obiekt wywołujący wybierze opcję braku pamięci podręcznej, każda ramka musi zostać zatwierdzona, aby można było utworzyć następną ramkę.
GetContainerFormat
GetContainerFormat jest zaimplementowany w taki sam sposób, jak metoda GetContainerFormat w Implementowaniu IWICBitmapDecoder.
PobierzInformacjeOEnkoderze
GetEncoderInfo zwraca obiekt IWICBitmapEncoderInfo. Aby uzyskać obiekt IWICBitmapEncoderInfo, wystarczy przekazać identyfikator GUID swojego kodera do metody CreateComponentInfo w IWICImagingFactory, a następnie zażądać interfejsu IWICBitmapEncoderInfo.
Zobacz przykład w Implementowanie IWICBitmapDecoder w obszarze GetDecoderInfo.
CreateNewFrame
CreateNewFrame jest odpowiednikiem kodera GetFrame w IWICBitmapDecoder. Ta metoda zwraca obiekt IWICBitmapFrameEncode, który jest obiektem, który faktycznie serializuje dane obrazu dla określonej ramki w kontenerze.
Jedną z zalet składnika Windows Imaging Component (WIC) jest to, że zapewnia warstwę abstrakcji dla aplikacji, które umożliwiają im pracę ze wszystkimi formatami obrazów w ten sam sposób. Jednak nie wszystkie formaty obrazów są dokładnie takie same. Niektóre formaty obrazów mają możliwości, których inni nie mają. Aby aplikacje mogły korzystać z tych unikatowych możliwości, należy zapewnić koderowi możliwość ich uwidocznienia. Jest to cel opcji kodera. Jeśli kodek obsługuje jakiekolwiek opcje kodera, należy utworzyć obiekt IPropertyBag2, który zawiera obsługiwane opcje kodera i zwrócić go jako parametr ppIEncoderOptions tej metody. Obiekt wywołujący może następnie użyć tego obiektu IPropertyBag2, aby określić, jakie opcje kodera obsługuje Twój kodek. Jeśli obiekt wywołujący chce określić wartości dla dowolnej z obsługiwanych opcji kodera, przypisuje wartość do odpowiedniej właściwości w obiekcie IPropertyBag2 i przekazuje ją do nowo utworzonego obiektu IWICBitmapFrameEncode w jego metodzie Initialize.
Aby utworzyć wystąpienie obiektu IPropertyBag2, najpierw należy utworzyć strukturę PROPBAG2, aby określić każdą opcję kodera obsługiwaną przez koder i typ danych dla każdej właściwości. Następnie należy zaimplementować obiekt IPropertyBag2, który wymusza zakresy wartości przy zapisie każdej właściwości oraz uzgadnia wszelkie wartości powodujące konflikt lub nakładanie się. W przypadku prostych zestawów opcji kodera bez konfliktu można wywołać metodę CreateEncoderPropertyBag, która utworzy prosty obiekt IPropertyBag2 przy użyciu właściwości określonych w strukturze PROPBAG2. Nadal musisz pilnować przestrzegania zakresów wartości. Aby uzyskać bardziej zaawansowane opcje kodera lub jeśli musisz uzgodnić wartości powodujące konflikt, należy napisać własną implementację IPropertyBag2.
UINT cuiPropertyCount = 0;
IPropertyBag2* pPropertyBag = NULL;
PROPBAG2* pPropBagOptions;
HRESULT hr;
// Insert code here to initialize piPropertyBag with the
// supported options for your encoder, and to initialize
// cuiPropertyCount to the number of encoder option properties
// you are exposing.
...
hr = pComponentFactory->CreateEncoderPropertyBag(
pPropBagOptions, cuiPropertyCount, &pPropertyBag);
Funkcja WIC udostępnia niewielki zestaw opcji kodera kanonicznego, które są używane przez niektóre typowe formaty obrazów. Wszystkie opcje kodera kanonicznego są opcjonalne, a kodery nie są wymagane do obsługi żadnego z nich. Powodem ich udostępnienia jako opcji kanonicznych jest to, że wiele aplikacji uwidacznia interfejs użytkownika dla użytkowników w celu określenia tych opcji podczas zapisywania pliku obrazu w formacie, który je obsługuje. Udostępnienie kanonicznego sposobu określania tych opcji ułatwia aplikacjom komunikowanie ich z koderami w spójny sposób. Opcje kodera kanonicznego są wymienione w poniższej tabeli.
| Opcja kodera | VARTYPE | Zakres wartości |
|---|---|---|
| Bezstratny | VT_BOOL | Prawda/fałsz |
| ImageQuality | VT_R4 | 0.0-1.0 |
| JakośćKompresji | VT_R4 | 0.0-1.0 |
| BitmapTransform | VT_UI1 | WICBitmapTransformOptions |
Jeśli Twój koder obsługuje kodowanie bezstratne, należy udostępnić opcję kodera bezstratnego w celu umożliwienia aplikacjom zażądania bezstratnego kodowania obrazu. Jeśli obiekt wywołujący ustawia tę właściwość na true, należy zignorować opcję ImageQuality i zakodować obraz bez utraty.
Opcja ImageQuality umożliwia aplikacji określenie stopnia wierności, za pomocą którego ma być zakodowany obraz. Ta opcja umożliwia użytkownikowi dokonanie kompromisu między jakością obrazu a szybkością i/lub rozmiarem pliku. JPEG to przykład formatu obrazu, który obsługuje ten kompromis. Wartość 0,0 wskazuje, że wierność ma niską ważność, a koder powinien używać najbardziej stratnego algorytmu. Wartość 1.0 wskazuje, że wierność jest najważniejsza, a koder powinien zachować najwyższą dokładność. (W zależności od kodu kodera może to być synonimem opcji Bezstratne. Jeśli jednak koder kodujący obsługuje kodowanie bezstratne, a opcja Bezstratna jest ustawiona na Wartość True, opcja ImageQuality powinna być ignorowana.
Opcja CompressionQuality umożliwia aplikacji określenie wydajności kompresji do użycia podczas kodowania obrazu. Bardzo wydajny algorytm może utworzyć mniejszy plik obrazu o tej samej jakości co mniej wydajny algorytm kompresji, ale może potrwać dłużej, aby kodować. Ta opcja umożliwia użytkownikowi określenie kompromisu między rozmiarem pliku a szybkością kodowania przy zachowaniu tego samego poziomu jakości. TIFF to przykład formatu obrazu, który obsługuje ten kompromis. (Należy pamiętać, że format taki jak JPEG obsługuje różne poziomy kompresji, ale wyższa szybkość kompresji skutkuje niższą jakością obrazu. W związku z tym format obrazu JPEG uwidacznia opcję ImageQuality, a nie opcję CompressionQuality. Wartość 0,0 dla tej opcji wskazuje, że należy skompresować obraz tak szybko, jak to możliwe, bez zmniejszenia wierności kosztem większego rozmiaru pliku. Wartość 1.0 wskazuje, że należy utworzyć najmniejszy możliwy rozmiar pliku (na tym samym poziomie jakości), niezależnie od tego, jak długo może to potrwać, aby go zakodować. Koder koderowy może obsługiwać zarówno opcję ImageQuality, jak i opcję CompressionQuality, gdzie opcja ImageQuality określa akceptowalny stopień straty, a opcja CompressionQuality oferuje kompromis rozmiaru/szybkości na określonym poziomie jakości.
Opcja BitmapTransform umożliwia obiektowi wywołującym określenie kąta obrotu, orientacji pionowej lub poziomej podczas kodowania. Wyliczenie WICBitmapTransformOptions użyte do określenia żądanego przekształcenia to samo wyliczenie używane przy żądaniu przekształcenia podczas dekodowania za pośrednictwem interfejsu IWICBitmapSourceTransform.
Należy pamiętać, że kodery nie są ograniczone do opcji kodera kanonicznego. Celem opcji kodera jest umożliwienie koderom uwidocznienia ich możliwości i nie ma żadnych ograniczeń dla typów możliwości, które można uwidocznić. Upewnij się, że opcje kodera są dobrze udokumentowane. Mimo że aplikacja może użyć zbioru właściwości zwracanej z tej metody, aby odnaleźć nazwy, typy i zakresy wartości dla opcji, które obsługujesz, jedynym sposobem na poznanie ich znaczenia lub na sposób zaprezentowania ich w interfejsie użytkownika jest dokumentacja.
Zobowiązać się
Commit to metoda, którą należy wywołać po tym, jak wszystkie dane obrazu i metadane zostały zserializowane do strumienia. Ta metoda służy do serializacji danych obrazu podglądu do strumienia oraz wszelkich globalnych miniatur, metadanych, palety lub innych elementów, jeśli ma to zastosowanie. Ta metoda nie powinna zamykać strumienia plików, ponieważ aplikacja, która otworzyła strumień, powinna ją zamknąć.
Sekcja dotycząca metody IWICBitmapFrameEncode:Commit zawiera szczegółowe informacje na temat wpływu opcji IWICBitmapEncoderCacheOptions na zachowanie tej metody.
UstawPodgląd
SetPreview służy do tworzenia podglądu obrazu. Chociaż nie jest wymagane, aby każdy obraz miał podgląd, jest to zdecydowanie zalecane. Nowoczesne aparaty cyfrowe i skanery generują bardzo duże obrazy o wysokiej rozdzielczości, które zwykle są bardzo duże, a w związku z tym dekodowanie zajmuje dużo czasu przetwarzania. Obrazy z następnej generacji aparatów będą jeszcze większe. Dobrym pomysłem jest zapewnienie mniejszej, niższej rozdzielczości obrazu, zazwyczaj w formacie JPEG, który może być szybko zdekodowany i wyświetlany "natychmiast", gdy użytkownik zażąda go. Aplikacja może zażądać podglądu przed żądaniem dekodowania rzeczywistego obrazu, aby zapewnić lepsze wrażenia użytkownikom, i pokazać im obraz dopasowany do rozmiaru ekranu podczas oczekiwania na dekodowanie rzeczywistego obrazu. Chociaż kodeki powinny udostępniać wersje zapoznawcze, te, które nie obsługują IWICBitmapSourceTransform, z pewnością powinny to robić.
Jeśli podasz podgląd JPEG, nie musisz pisać kodera JPEG, aby go zakodować. Należy delegować koder JPEG dostarczany z platformą WIC na potrzeby kodowania podglądów i miniatur.
Tematy pokrewne
-
Referencja
-
Koncepcyjne
-
implementowanie IWICBitmapCodecProgressNotification (Encoder)
-
Jak napisać WIC-Enabled CODEC