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

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 RECTstructure.

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 subareaparameter. If it does, the image sink must fill in the RECTstructure to tell the source which portion of the image to decode.

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

Remarks

The following table shows the values returned by IImageSink::BeginSink in the members of imageinfo.

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 Widthand Heightvalues 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 Xdpiand Ydpivalues accordingly.

  • If the source has set the SinkFlagsPartiallyScalable flag, the sink can modify the Widthand Heightvalues to tell the source the ideal width and height for the sink.

    The source then calls IImageSink::BeginSinkagain with the closest width and height the source can supply.

    When IImageSink::BeginSinkis called the second time, the SinkFlagsPartiallyScalable flag is clear.

If the sink doesn't want its BeginSinkcalled twice, it should leave the Widthand Heightvalues 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, TileWidthmust be the same as Width, and TileHeightis 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 SinkFlagsenumeration.

  • SinkFlagsScalable. This flag is left unchanged.

  • SinkFlagsPartiallyScalable. See the description for Widthand 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::BeginSinkmethod.

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
Windows Embedded CE Windows CE 5.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also