IImageSink::BeginSink (Compact 2013)

  • Article

3/26/2014

This feature is being deprecated for this release. Refer to this component: Windows Imaging Component.

This method is used to establish a connection between the image source and the sink.

During the call to this method, the source and the sink negotiate the data transfer parameters of their connection.

Syntax

HRESULT BeginSink(
  ImageInfo* imageInfo,
  OPTIONAL RECT* subarea
);

Parameters

  • imageInfo
    [in, out] A pointer to an ImageInfo (Imaging API) structure used to pass information about the data connection between the source and the sink.

    When calling the function, set the values in the structure to describe the image data produced by the source.

    When the method returns successfully, this structure contains values describing the resulting negotiated image parameters for the connection between the source and the sink.

  • subarea
    [out] A pointer to a RECT structure.

    This parameter is used for partial decoding if the image source and sink can support it.

    If the image source can support partial image decoding, it should pass a non-NULL subarea parameter. If it does, the image sink must fill in the RECT structure to tell the source which portion of the image to decode.

    If the sink does not want a partial image, it fills in the RECT structure to include the entire source image.

Remarks

The following table shows the values returned by IImageSink::BeginSink in the members of ImageInfo (Imaging API).

imageInfo Member

Contents

RawDataFormat

This member contains one of the following:

PixelFormatID

This member contains the pixel format preferred by the sink. This might or might not be the same format as what was requested by the source.

The source can supply pixel data in the format requested by the sink, or it can supply pixel data in one of the canonical pixel formats, which all sinks must support.

Width, Height, Xdpi, Ydpi

The contents of these members are normally left unchanged by the sink. However, consider the following:

  • If the source has set the SinkFlagsScalable flag, the sink can modify Width and Height values to request the source to scale the source image to a new dimension.
    For more information about SinkFlagsScalable, see SinkFlags.
    If the sink changes width and height values, it should change Xdpi and Ydpi values accordingly.
  • If the source has set the SinkFlagsPartiallyScalable flag, the sink can modify the Width and Height values to tell the source the ideal width and height for the sink.
    The source then calls IImageSink::BeginSink again with the closest width and height the source can supply.
    When IImageSink::BeginSink is called the second time, the SinkFlagsPartiallyScalable flag is clear.

If the sink doesn't want its BeginSink called twice, it should leave the Width and Height values unchanged and also clear the SinkFlagsPartiallyScalable flag.

TileWidth, TileHeight

These members contain the tile dimensions preferred by the sink.

If the SinkFlagsFullWidth flag is set, TileWidth must be the same as Width, and TileHeight is the preferred band height.

Tile size information is used as a hint for potential performance gains.

The source is not required to use the exact tile size requested by the sink.

Flags

This member contains one or more of the following flags from the SinkFlags enumeration.

  • SinkFlagsScalable. This flag is left unchanged.
  • SinkFlagsPartiallyScalable. See the description for Width and Height.
  • SinkFlagsHasAlpha. If this flag is set by the source, the sink can clear this flag to indicate that the sink cannot support alpha values.
    Even in that case, the source can still supply alpha to the sink.
    The sink can do whatever it chooses with the alpha information, which includes discarding it.
  • SinkFlagsTopDown. Set to reflect the sink's preference.
  • SinkFlagsFullWidth. Set by the sink to describe whether the sink wants data in bands.
    All sources must support data transfer in top-down banding order, even if that is not their preferred order.
  • SinkFlagsBottomUp. This flag is left unchanged.
  • SinkFlagsMultipass. If this flag is set by the source, the sink can clear this flag to indicate that it does not support multipass.
    In that case, the source is required to handle multipass on its own and give image data to the sink in a single pass.
    If the sink indicates it can support multipass but also requires top-down order, the source must supply data one entire pass after another. In addition, for each pass it must supply one band after another, with no gaps in between.
  • SinkFlagsComposite. This flag is left unchanged. If this flag is set by the source and the sink cannot support compositing behavior, the sink should return a failure from the IImageSink::BeginSink method.

SinkFlagsWantProps. The sink can set this flag to indicate to the source that it is interested in getting image metadata properties through a call to IImageSink::PushPropertyItems.

This method negotiates the parameters for sending image data from an image source to an image sink.

Prior to sending data to the sink, you must call IImageSink::SetPalette.

Return Values

The following table shows the return values for this method.

Value

Description

S_OK

The method was successful.

E_NOTIMPL

The method failed.

Requirements

Header

imaging.h

Library

Imaging.lib

See Also

Reference

IImageSink
IImageSink::PushRawData
IImageSink::PushPixelData
IImageSink::GetPixelDataBuffer
IImageSink::ReleasePixelDataBuffer
SinkFlags
IImageSink::PushPropertyItems
IImageSink::SetPalette