Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

The Imaging API is used to standardize and facilitate the communication between an image source and an image sink. To encode an image, you must implement an image encoder in the code for the image source.

An encoder object takes in raw image data, and uses a codec to encode that data into a specified graphic format. This encoded data is then stored by an image sink. The image data is pushed to the image sink by the image source.

Use the following sequence to implement an image encoder and use Imaging API calls to encode image data and push the data to your sink.

To implement an image encoder object

  1. Create an image encoder object by calling IImagingfactory::CreateImageEncoderToStreamwith a pointer to a new IStream object for streaming the image data.

    The constructor for this object should not perform any operations that must be performed before every image file is encoded. These operations should be implemented in the IImageEncoder::InitEncodermethod.

  2. Call QueryInterfaceon the newly created encoder object to receive the IImageEncoderinterface.

  3. Call the IImageEncoder::InitEncodermethod with the IStream interface created above to initialize the encoder object.

    All necessary operations to initialize writing a single image should be included in this method.

  4. If you need determine which encoder parameters are supported by the encoder object, you can optionally call IImageEncoder::SetEncoderParameters.

  5. If you need to set specific parameters in the encoder object, you can optionally call IImageEncoder::SetEncoderParameters.

  6. If the encoder supports multiframe images and the application is creating a multiframe image, call IImageEncoder::SetFrameDimension.

  7. Call IImageEncoder::GetEncodeSinkto retrieve an IImageSinkinterface. The IImageSinkinterface is implemented as follows:

    1. Call IImageSink::BeginSinkto negotiate the values contained in the ImageInfostructure for encoding the current frame.

    2. Call IImageSink::SetPaletteto pass color palette information about the current image frame to the image sink.

    3. If you need to pass property data to the image sink, you can optionally call IImageSink::GetPropertyBufferto obtain a buffer that will contain the property data.

    4. If GetPropertyBufferis called above, you must next call IImageSink::PushPropertyItemsto transfer the property data to the image sink.

      The buffer that was allocated by GetPropertyBuffermust be deallocated in the implementation for PushPropertyItems.

    5. Call IImageSink::PushPixelDataor IImageSink::GetPixelDataBufferto begin the data transfer, depending on how the image data is stored in the source:

    • If the image source has allocated memory for the image, use PushPixelData.

    • If the image source has not allocated memory for the image, use GetPixelDataBuffer. For each call to GetPixelDataBuffer, IImageSink::ReleasePixelDataBufferwce50lrfIImageSinkReleasePixelDataBuffer must also be called.

    1. Call ImageSink::EndSinkto complete the encoding process.

    2. Call ImageSink::Releaseto free the IImagesinkinterface.

  8. Once the image sink has been released, the call to IImageEncoder::GetEncodeSinkcan be repeated for each frame of the image.

  9. Call IImageEncoder::TerminateEncoderto break the association between the encoder object and the image data stream.

    After TerminateEncoderis called, the application can start a new encoding process by calling IImageEncoder::InitEncoderwith a new IStream interface.

  10. The destructor for the encoder object is called after the object's interface is released. In the destructor, the encoder object must verify that TerminateEncoderwas called. If not, the destructor should call TerminateEncoder.

See Also