Método IXpsRasterizer::RasterizeRect (xpsrassvc.h)

Artigo
02/27/2024

O método RasterizeRect rasteriza uma região retangular alinhada ao eixo de uma página fixa XPS.

Sintaxe

HRESULT RasterizeRect(
  [in]            INT                                x,
  [in]            INT                                y,
  [in]            INT                                width,
  [in]            INT                                height,
  [in, optional]  IXpsRasterizerNotificationCallback *notificationCallback,
  [out, optional] IWICBitmap                         **bitmap
);

Parâmetros

[in] x

A coordenada x, em pixels, na borda esquerda do bitmap de saída.

[in] y

A coordenada y, em pixels, na borda superior do bitmap de saída.

[in] width

A largura, em pixels, do bitmap de saída.

[in] height

A altura, em pixels, do bitmap de saída.

[in, optional] notificationCallback

Ponteiro para a interface IXpsRasterizerNotificationCallback de um objeto de notificação implementado pelo chamador. Esse parâmetro é opcional e pode ser NULL se o chamador não exigir retornos de chamada de notificação.

[out, optional] bitmap

Ponteiro para um local no qual o método grava um ponteiro para a interface IWICBitmap do objeto bitmap recém-criado. Se o método falhar, ele gravará NULL nesse local e retornará um código de erro.

Retornar valor

RasterizeRect retornará S_OK se a chamada tiver sido bem-sucedida. Caso contrário, o método retorna um código de erro. Os possíveis valores retornados por erro incluem:

Código de retorno	Descrição
E_POINTER	O bitmap do parâmetro é NULL.
E_INVALIDARG	A largura ou altura do parâmetro é menor ou igual a 0.

Comentários

Esse método tem suporte no Windows 7 e posterior. Não há suporte para ele em versões do sistema operacional Windows antes do Windows 7.

Se tiver êxito, esse método criará um objeto de bitmap wic (componente de imagem do Windows) e passará ao chamador uma referência contada à interface IWICBitmap do objeto. Quando o objeto não é mais necessário, o chamador é responsável por liberar o objeto chamando o método Release na interface IWICBitmap do objeto.

O bitmap wic criado por esse método tem um formato de pixel de 32 bits que contém canais vermelhos, verdes e azuis de 8 bits e usa o espaço de cor RGB padrão (sRGB). Além disso, o formato contém um componente alfa de 8 bits. Os componentes de cor em cada valor de pixel são pré-multiplicados pelo componente alfa. O formato de pixel é especificado pelo valor guid GUID_WICPixelFormat32bppPBGRA, que é definido no arquivo de cabeçalho Wincodec.h. Para obter mais informações sobre esse formato, consulte Visão geral dos formatos de pixel nativos.

O parâmetro DPI do método IXpsRasterizationFactory::CreateRasterizer especifica a resolução, em pontos por polegada, na qual o bitmap deve ser renderizado. Conforme descrito na especificação XPS, a largura e a altura de uma página fixa em um documento XPS são especificadas em unidades de 1/96 polegadas. Para determinar as dimensões (em pixels) do bitmap necessário para representar toda a página fixa, multiplique a largura e a altura por DPI/96.

Para acomodar impressoras que exigem que uma página fixa seja rasterizada como uma série de faixas horizontais ou verticais, os parâmetros x, y, largura e altura especificam uma região retangular da página fixa que deve ser rasterizada. Todos os quatro valores de parâmetro são especificados em pixels. Os parâmetros x e y são as coordenadas do canto superior esquerdo da região retangular; eles são especificados como deslocamentos de pixel da origem da coordenada (0, 0). Largura ealtura dos parâmetros são as dimensões da região retangular.

Por exemplo, se wXPS e hXPS forem a largura e a altura de uma página fixa XPS em unidades de 1/96 polegadas, RasterizeRect gerará uma representação de bitmap da metade inferior da página fixa se os parâmetros x, y, width e height forem definidos com os seguintes valores:

xyh Largura doDPIwDPIheighthDPI

Se o parâmetro notificationCallback não for NULL, o método RasterizeRect usará uma referência contada à interface IXpsRasterizerNotificationCallback do objeto de notificação. Ele faz isso chamando o método AddRef na interface antes de fazer chamadas para o método IXpsRasterizerNotificationCallback::Continue . Antes que RasterizeRect retorne, ele libera o objeto de notificação chamando o método Release na interface *IXpsRasterizerNotificationCallback .

Conforme explicado na especificação XPS, o atributo BleedBox opcional pode especificar uma caixa de sangramento que se estende fora dos limites de uma página fixa. Para acomodar caixas de sangramento, o retângulo definido pelos parâmetros x, y, largura e altura também pode se estender além dos limites da página fixa. O método aceita todos os valores, positivos ou negativos, para x e y, e aceita valores positivos e não zero para largura e altura. O retângulo especificado por esses parâmetros define a região de recorte para a operação de rasterização. Se o retângulo se estender além dos limites da página fixa, a região de recorte também se estenderá além desses limites.

Se o método falhar e o bitmap não for NULL, o método definirá *bitmap = NULL.

Para obter um exemplo de código que chama o método RasterizeRect , consulte o exemplo XPSRasFilter no WDK. Este exemplo está localizado na pasta Src\Print\Xpsrasfilter na instalação do WDK.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows 7 e versões posteriores do sistema operacional Windows.
Plataforma de Destino	Área de Trabalho
Cabeçalho	xpsrassvc.h