Interface IWICBitmapFrameChainReader (wincodec.h)

Fornece acesso a quadros que estão vinculados ao quadro atual por meio de cadeias de diferentes tipos.

To provide access to subordinate frames, the frame object (which is represented by IWICBitmapFrameDecode), implements IWICBitmapFrameChainReader.

Inheritance

The IWICBitmapFrameChainReader interface inherits from the IUnknown interface.

Methods

The IWICBitmapFrameChainReader interface has these methods.

Remarks

IWICBitmapFrameChainReader represents one of a set of COM interfaces that allow WIC to expose chains of linked frames, of different types.

O decodificador de um arquivo de imagem pode fornecer vários quadros. Cada quadro representa uma imagem separada. Da mesma forma, o codificador pode aceitar vários quadros e codificá-los em um único arquivo. For example, when scanning a multi-page document into TIFF format, the IWICBitmapEncoder::CreateNewFrame method is used to create a frame for each scanned page, and the IWICBitmapDecoder::GetFrame method is used to retrieve each frame. Nesse cenário, não há hierarquia de quadros (cada quadro é tão importante quanto outro). Alguns formatos de imagem, como HEIF e JPEG XL, dão suporte a quadros secundários vinculados a um quadro primário. IWICBitmapFrameChainReader gives you a way to specify such relationships between frames in the WIC API. Exemplos de quadros secundários incluem imagens em miniatura, imagens de visualização e bitmaps de plano alfa.

HEIF supports layered images (also known as overlay images). An overlay image is composed of multiple layer images that are stacked on top of each other in a specified order. A imagem de sobreposição é a imagem primária e as imagens de camada são imagens secundárias (subordinadas) vinculadas à imagem primária. As imagens de camada normalmente não são exibidas, mas há casos em que um aplicativo de edição de imagem precisa ser capaz de ler e gravar cada imagem de camada individual.

Uma imagem de sobreposição requer metadados para descrever como compor as diferentes camadas em uma única imagem. You can work with that metadata with WIC metadata interfaces such as IWICMetadataReader and IWICMetadataWriter.

Uma imagem de sobreposição geralmente requer compactação sem perda, pois isso permite que aplicativos de edição de imagem abram e salvem um arquivo várias vezes sem degradar a qualidade da imagem. Os formatos de compactação HEVC e AV1 para arquivos de imagem HEIF são perdidos. Com as APIs de codificação wic, você pode usar HEIF com formatos não compactados, como RGBA.

Nesting

While IWICBitmapFrameDecode has a GetThumbnail method, and IWICBitmapDecoder has a GetPreview method—to return a thumbnail and a preview image, respectively—those methods return only a single image of each type. E esses métodos retornam as imagens como um bitmap em vez de como um quadro; o que significa que as informações de espaço de cores e metadados não estão disponíveis.

IWICBitmapFrameChainReader supports multiple frames of each type, and the frames can be nested. So, for example, a frame from an Alternate chain (see WICBitmapChainType) might itself have for example a Preview chain linked to it, or a Layer chain. Or a frame from a Thumbnail chain might have an AlphaMap chain or a GainMap chain.

O WIC permite aninhamento de quadros de até cinco níveis de profundidade.

É sua responsabilidade como chamador adicionar quadros na ordem correta e criar cadeias que atendam a uma finalidade útil. For example, adding frames to the Preview chain in the wrong order will still work, but it might not result in the optimal image-rendering experience in all cases. Similarly, it's possible to add multiple frames to the GainMap chain, but in practice only the first frame in that chain will be used.

Nesting

IWICBitmapFrameChainReader and IWICBitmapFrameChainWriter are supported by HEIF and JPEG XL. HEIF supports all chain types, but JPEG XL supports only Preview, Thumbnail and GainMap. Attempts to encode a JPEG XL image with an unsupported chain type will result in a WINCODEC_ERR_UNSUPPORTEDOPERATION error. You can use the IWICBitmapFrameChainWriter::DoesSupportChainType method to determine whether a given chain type is supported by the encoder.

Metadados para imagens em camadas

Layered images are specific to the HEIF format, defined in ISO/IEC 23008-12, where they're known as Overlay images. The WICHeifProperties enumeration has the relevant constants WICHeifLayeredImageCanvasColor and WICHeifLayeredImageLayerPositions.

Veja o exemplo 1 e o exemplo 2.

Codificação sem perdas para HEIF

For lossless encoding in the HEIF format, you can use the enum constant WICHeifCompressionNone. For example, an encoding app can specify the WICHeifCompressionNone option, and invoke IWICBitmapFrameEncode::WritePixels or WriteSource with a bitmap in the GUID_WICPixelFormat32bppRGBA format.

The WICHeifCompressionOption enumeration has the relevant constants WICHeifCompressionJpegXL, WICHeifCompressionBrotli, and WICHeifCompressionDeflate.

Examples

Exemplo 1: Decodificar uma imagem em camadas

This example shows how to determine whether an image is a layered image (known as an overlay image in the HEIF file format). O exemplo mostra como consultar os metadados e como localizar cada quadro de camada, que é necessário para compor a imagem em camadas.

The example uses the IWICMetadataReader interface, which will work on all versions of Windows 11 where HEIF is supported.

#include <wil/com.h>
#include <wincodec.h>

// This function finds the IWICMetadataReader for HEIF-specific metadata.
HRESULT GetHeifMetadataReader(
    _In_ IWICBitmapFrameDecode* frame,
    _COM_Outptr_ IWICMetadataReader** reader)
{
    *reader = nullptr;

    wil::com_ptr_nothrow<IWICMetadataBlockReader> blockReader;
    RETURN_IF_FAILED(wil::com_query_to_nothrow(frame, &blockReader));

    UINT numberOfReaders;
    RETURN_IF_FAILED(blockReader->GetCount(&numberOfReaders));

    for (UINT index = 0; index < numberOfReaders; index++)
    {
        wil::com_ptr_nothrow<IWICMetadataReader> metadataReader;
        RETURN_IF_FAILED(blockReader->GetReaderByIndex(index, &metadataReader));

        GUID metadataFormat;
        RETURN_IF_FAILED(metadataReader->GetMetadataFormat(&metadataFormat));
        if (metadataFormat == GUID_MetadataFormatHeif)
        {
            *reader = metadataReader.detach();
            return S_OK;
        }
    }

    return E_NOT_SET;
}

HRESULT DisplayFrame(_In_ IWICBitmapFrameDecode* primaryFrame)
{
    // To determine whether this is a layered image, we need to find the
    // HEIF-specific metadata.
    wil::com_ptr_nothrow<IWICMetadataReader> metadataReader;
    if (SUCCEEDED(GetHeifMetadataReader(primaryFrame, &metadataReader)))
    {
        PROPVARIANT propertyId{};
        propertyId.vt = VT_UI2;

        propertyId.uiVal = WICHeifLayeredImageCanvasColor;
        wil::unique_prop_variant propvariant;
        (void)metadataReader->GetValue(nullptr, &propertyId, &propvariant);

        if (propvariant.vt == VT_UI4)
        {
            // We got the color of the canvas.
            WICColor canvasColor = propvariant.ulVal;

            // Get the size of the canvas.
            UINT canvasWidth;
            UINT canvasHeight;
            RETURN_IF_FAILED(primaryFrame->GetSize(&canvasWidth, &canvasHeight));

            // Draw an empty canvas (not shown.)
            RETURN_IF_FAILED(RenderEmptyCanvas(canvasWidth, canvasHeight, canvasColor));

            // Get the position on the canvas of each layer image.
            propertyId.uiVal = WICHeifLayeredImageLayerPositions;
            propvariant.reset();
            (void)metadataReader->GetValue(nullptr, &propertyId, &propvariant);

            UINT layerPositionCount = 0;
            POINT* layerPositions = nullptr;

            if (propvariant.vt == (VT_VECTOR | VT_UI8))
            {
                layerPositionCount = propvariant.cauh.cElems;
                layerPositions = reinterpret_cast<POINT*>(propvariant.cauh.pElems);
            }

            // Check whether there are any layer frames chained to the primary frame.
            // If there are none, then we have just a blank canvas.
            wil::com_ptr_nothrow<IWICBitmapFrameChainReader> chainReader;
            if (SUCCEEDED(wil::com_query_to_nothrow(primaryFrame, &chainReader)))
            {
                UINT layerCount = 0;
                (void)chainReader->GetChainedFrameCount(WICBitmapChainType_Layer, &layerCount);

                // Render each layer.
                for (UINT layerIndex = 0; layerIndex < layerCount; ++layerIndex)
                {
                    wil::com_ptr_nothrow<IWICBitmapFrameDecode> layerFrame;
                    RETURN_IF_FAILED(chainReader->GetChainedFrame(WICBitmapChainType_Layer, layerIndex,
                        &layerFrame));

                    // If we don't have layer positions for some layers, then the default position
                    // is [0,0].
                    POINT layerPosition = (layerIndex < layerPositionCount) ? 
                        layerPositions[layerIndex] : POINT{ 0, 0 };

                    // The "DisplayLayerFrame" function is omitted for brevity.
                    RETURN_IF_FAILED(DisplayLayerFrame(layerFrame.get(), canvasWidth, canvasHeight, 
                        layerPosition.x, layerPosition.y));
                }
            }
        }
        else
        {
            // If we get here, then the WICHeifLayeredImageCanvasColor property is not present.
            // That property is required for layered frames. That means that the primary frame is not a
            // layered frame, and we should render it as a normal frame.
            // (Function not shown for brevity.)
            RETURN_IF_FAILED(DisplayNormalFrame(primaryFrame));
        }
    }
    else
    {
        // If we get here, then the IWICMetadataReader for HEIF is not available.
        // This means that the frame is not from a HEIF file, and it is definitely not a layered frame.
        RETURN_IF_FAILED(DisplayNormalFrame(primaryFrame));
    }
    return S_OK;
}

Exemplo 2: Decodificar uma imagem em camadas

This example shows how to decode a layered image using the IWICMetadataQueryReader. O exemplo é funcionalmente equivalente ao exemplo anterior. Algumas partes que seriam iguais ao exemplo anterior foram omitidas para evitar repetição. The main difference is the use of IWICMetadataQueryReader instead of IWICMetadataReader. While IWICMetadataQueryReader is easier to use, the disadvantage is that the IWICMetadataQueryReader supports querying for only layered image metadata on Windows 11 version 25H2, and later. So using IWICMetadataQueryReader on older versions of Windows than that will result in the GetMetadataByName method returning an error.

#include <wil/com.h>
#include <wincodec.h>

HRESULT DisplayFrame(_In_ IWICBitmapFrameDecode* primaryFrame)
{
    wil::com_ptr_nothrow<IWICMetadataQueryReader> metadataQueryReader;
    RETURN_IF_FAILED(primaryFrame->GetMetadataQueryReader(&metadataQueryReader));

    wil::unique_prop_variant propvariant;
    (void)metadataQueryReader->GetMetadataByName(L"/heifProps/LayeredImageCanvasColor", &propvariant);

    if (propvariant.vt == VT_UI4)
    {
        // We got the color of the canvas.
        WICColor canvasColor = propvariant.ulVal;

        // Get the position on the canvas of each layer image.
        propvariant.reset();
        (void)metadataQueryReader->GetMetadataByName(L"/heifProps/LayeredImageLayerPositions", &propvariant);

        UINT layerPositionCount = 0;
        POINT* layerPositions = nullptr;

        if (propvariant.vt == (VT_VECTOR | VT_UI8))
        {
            layerPositionCount = propvariant.cauh.cElems;
            layerPositions = reinterpret_cast<POINT*>(propvariant.cauh.pElems);
        }

        // Draw the canvas, and display each layer image (if any).
        // Function not shown for brevity.
        RETURN_IF_FAILED(DisplayCanvasAndAllLayers(primaryFrame, canvasColor, layerPositionCount, 
            layerPositions));
    }
    else
    {
        // If we get here, then we were unable to find the "/heifProps/LayeredImageCanvasColor" property,
        // probably because it's not present in the file.
        // That property is required for layered frames. That suggests that the primary frame is not a
        // layered frame. We will render it as a normal frame.
        // (Function not shown for brevity.)
        RETURN_IF_FAILED(DisplayNormalFrame(primaryFrame));
    }
    return S_OK;
}

Exemplo 3: codificar uma imagem em camadas

This example shows how to encode a layered image using the IWICMetadataQueryWriter and IWICBitmapFrameChainWriter.

#include <wil/com.h>
#include <wincodec.h>

HRESULT CreateLayerImage(
    _In_ IWICImagingFactory* factory,
    _In_ IWICStream* outputStream,
    const SIZE& canvasSize,
    WICColor canvasColor,
    UINT numLayers,
    _In_reads_(numLayers) const POINT* layerPositions,
    _In_reads_(numLayers) IWICBitmapSource* layerBitmaps[])
{
    wil::com_ptr_nothrow<IWICBitmapEncoder> heifEncoder;
    RETURN_IF_FAILED(factory->CreateEncoder(GUID_ContainerFormatHeif, nullptr, &heifEncoder));

    RETURN_IF_FAILED(heifEncoder->Initialize(outputStream, WICBitmapEncoderCacheInMemory));

    wil::com_ptr_nothrow<IWICBitmapFrameEncode> layeredFrame;
    RETURN_IF_FAILED(heifEncoder->CreateNewFrame(&layeredFrame, nullptr));
    RETURN_IF_FAILED(layeredFrame->Initialize(nullptr));

    RETURN_IF_FAILED(layeredFrame->SetSize(canvasSize.cx, canvasSize.cy));

    // Create a chain of layer images, chained to the layered image.
    wil::com_ptr_nothrow<IWICBitmapFrameChainWriter> chainWriter;
    RETURN_IF_FAILED(wil::com_query_to_nothrow(layeredFrame, &chainWriter));

    for (ULONG layerIndex = 0; layerIndex < numLayers; ++layerIndex)
    {
        wil::com_ptr_nothrow<IWICBitmapFrameEncode> layerFrame;

        RETURN_IF_FAILED(chainWriter->AppendFrameToChain(WICBitmapChainType_Layer, layerFrame.get()));
        RETURN_IF_FAILED(layerFrame->Initialize(nullptr));

        RETURN_IF_FAILED(layerFrame->WriteSource(layerBitmaps[layerIndex], nullptr));
        RETURN_IF_FAILED(layerFrame->Commit());
    }

    // Write the background color and the position of each layer as metadata on the layered image.
    // (The chain and the metadata can also be added in opposite order to that shown here).
    wil::com_ptr_nothrow<IWICMetadataQueryWriter> queryWriter;
    RETURN_IF_FAILED(layeredFrame->GetMetadataQueryWriter(&queryWriter));

    PROPVARIANT propvariant{};
    propvariant.vt = VT_UI4;
    propvariant.ulVal = canvasColor;

    if (SUCCEEDED(queryWriter->SetMetadataByName(L"/heifProps/LayeredImageCanvasColor", &propvariant)))
    {
        propvariant.vt = VT_VECTOR | VT_UI8;
        propvariant.cauh.cElems = numLayers;
        propvariant.cauh.pElems = reinterpret_cast<ULARGE_INTEGER*>(layerPositions);  

        RETURN_IF_FAILED(queryWriter->SetMetadataByName(L"/heifProps/LayeredImageLayerPositions", 
            &propvariant));

        // Set the type to VT_EMPTY to avoid accidentally clearing the PROPVARIANT,
        // because cauh.pElems is pointing to memory not allocated with CoTaskMemAlloc.
        propvariant.vt = VT_EMPTY;
    }

    // Finalize the layered frame and the HEIF file.
    RETURN_IF_FAILED(layeredFrame->Commit());
    RETURN_IF_FAILED(heifEncoder->Commit());
    return S_OK;
}

Exemplo 4: codificar um quadro alternativo

Este exemplo mostra como seu aplicativo pode salvar um quadro descompactado usando a compactação Deflate sem perdas, ao mesmo tempo em que fornece uma codificação alternativa de menor qualidade usando HEVC. Imagens não compactadas no HEIF são definidas em um novo padrão que pode não ter suporte fora do Windows. Isso significa que há uma possibilidade de que um aplicativo de exibição de fotos, especialmente um não em execução no Windows, não seja capaz de decodificar quadros descompactados. Ao fornecer um quadro alternativo codificado em HEVC, os aplicativos que não dão suporte a quadros não compactados ainda poderão exibir a imagem, embora com uma qualidade mais baixa.

#include <wil/com.h>
#include <wincodec.h>

HRESULT AddUncompressedFrameWithHevcAlternate(
    _In_ IWICBitmapEncoder* heifEncoder,
    _In_ IWICBitmapSource* sourceBitmap)
{
    wil::com_ptr_nothrow<IWICBitmapFrameEncode> primaryFrame;
    wil::com_ptr_nothrow<IPropertyBag2> encoderOptions;
    RETURN_IF_FAILED(heifEncoder->CreateNewFrame(&primaryFrame, &encoderOptions));

    // Specify that the primary frame should be saved in uncompressed format with lossless Deflate compression applied to it.
    PROPBAG2 option{};
    option.pstrName = L"HeifCompressionMethod";

    wil::unique_variant prop;
    prop.vt = VT_UI1;
    prop.bVal = (BYTE)WICHeifCompressionDeflate;

    RETURN_IF_FAILED(primaryFrame->Initialize(encoderOptions.get()));
    RETURN_IF_FAILED(primaryFrame->WriteSource(sourceBitmap, nullptr));

    // Now create a chain of alternate frames, chained to the primary image.
    wil::com_ptr_nothrow<IWICBitmapFrameChainWriter> chainWriter;
    RETURN_IF_FAILED(wil::com_query_to_nothrow(primaryFrame, &chainWriter));

    // Create an alternate frame that is encoded using HEVC. This frame will be displayed by
    // photo viewing apps when uncompressed images aren't supported.
    // HEVC is the default, so we don't need to specify any encoding options for this frame.
    wil::com_ptr_nothrow<IWICBitmapFrameEncode> alternateFrame;
    RETURN_IF_FAILED(chainWriter->AppendFrameToChain(WICBitmapChainType_Alternate, &alternateFrame,
        nullptr));
    RETURN_IF_FAILED(alternateFrame->Initialize(nullptr));
    RETURN_IF_FAILED(alternateFrame->WriteSource(sourceBitmap, nullptr));
    RETURN_IF_FAILED(alternateFrame->Commit());

    RETURN_IF_FAILED(primaryFrame->Commit());
    RETURN_IF_FAILED(heifEncoder->Commit());
    return S_OK;
}

Exemplo 5: Verificando se há suporte para cadeias de mapa de ganho

Este exemplo mostra como seu aplicativo pode verificar se o codificador dá suporte ao armazenamento de um mapa de ganho com a imagem primária. Se a imagem primária estiver no formato SDR (intervalo dinâmico padrão), um mapa de ganho poderá ser usado para aprimorar a imagem primária para HDR (alto intervalo dinâmico). Mas nem todos os formatos de arquivo dão suporte a mapas de ganho, portanto, seu aplicativo pode primeiro querer verificar se há suporte para mapas de ganho antes de gastar recursos na geração do mapa de ganhos. This example shows how you can do that by using the IWICBitmapFrameChainWriter::DoesSupportChainType method.

#include <wil/com.h>
#include <wincodec.h>

HRESULT EncodeHdrBitmap(
    _In_ IWICBitmapEncoder* encoder,
    _In_ IWICBitmapSource* hdrBitmap)
{
    wil::com_ptr_nothrow<IWICBitmapFrameEncode> primaryFrame;
    wil::com_ptr_nothrow<IWICBitmapFrameEncode> gainMapFrame;
    wil::com_ptr_nothrow<IWICBitmapFrameChainWriter> chainWriter;

    RETURN_IF_FAILED(encoder->CreateNewFrame(&primaryFrame, nullptr));

    if (SUCCEEDED(wil::com_query_to_nothrow(primaryFrame, &chainWriter)))
    {
        // Check whether this encoder supports adding a gain map.
        BOOL isSupported;
        if (SUCCEEDED(chainWriter->DoesSupportChainType(WICBitmapChainType_GainMap, &isSupported)) &&
            isSupported)
        {
            RETURN_IF_FAILED(chainWriter->AppendFrameToChain(WICBitmapChainType_GainMap, &gainMapFrame,
                nullptr));
            RETURN_IF_FAILED(gainMapFrame->Initialize(nullptr));

            // Split the HDR frame into a base image (written to primaryFrame) and a gain map.
            // (This function is not shown, for brevity).
            RETURN_IF_FAILED(SplitHdrBitmapIntoSdrAndGainMap(hdrBitmap, primaryFrame.get(), 
                gainMapFrame.get()));
        }
    }

    if (gainMapFrame != nullptr)
    {
        // We successfully created a separate frame for the gain map. Commit the changes to the file.
        RETURN_IF_FAILED(gainMapFrame->Commit());
    }
    else
    {
        // The encoder doesn't support gain maps, so we write the full HDR image as a single frame. 
        RETURN_IF_FAILED(primaryFrame->WriteSource(hdrBitmap, nullptr));
    }

    RETURN_IF_FAILED(primaryFrame->Commit());
    RETURN_IF_FAILED(encoder->Commit());
    return S_OK;
}

Requirements

See also

• IWICBitmapFrameChainWriter