THotPDF.RegisterSampledFunction Method

Declara um objeto de stream indireto Function Type 0 (Sampled) do PDF 1.2+ (ISO 32000-1 7.10.2). Funções sampled expressam um mapeamento arbitrário de entrada para saída como uma grade regular N-dimensional de amostras de saída M-dimensionais; o renderizador interpola entre os pontos de grade para avaliar entradas intermediárias. Use isto onde a maquinaria de perfil ICC é exagero mas se deseja uma tabela de consulta ajustada à mão — curvas de tom para /TransferFunction (ExtGState /TR), transformações de tint sampled para /Separation ou /DeviceN (alternativa aos caminhos linear Type 2 / aritmético Type 4), curvas de limiar de halftone, ou qualquer outro construto PDF que aceite um dicionário de Function.

function RegisterSampledFunction( const Domain: array of Single; const Range: array of Single; const Size: array of Integer; BitsPerSample: Integer; const Samples: array of byte; Order: Integer = 1): THPDFStreamObject;

THPDFStreamObject* RegisterSampledFunction(const float* Domain, int DomainCount, const float* Range, int RangeCount, const int* Size, int SizeCount, int BitsPerSample, const unsigned char* Samples, int SamplesCount, int Order = 1);

A função é emitida como um stream indireto com /FunctionType 0, as entradas fornecidas /Domain, /Range, /Size, /BitsPerSample e /Order, mais o stream bruto de amostras empacotadas em bits. /Encode e /Decode são omitidos para que os padrões da spec se apliquem: /Encode mapeia cada ponto final de Domain às extensões da grade [0..Size[i]-1], e /Decode corresponde a /Range (as amostras são desempacotadas em inteiros e remapeadas linearmente de volta aos pontos finais de Range). Para funções de múltiplas entradas, a ordem de bytes das amostras segue a regra do PDF 1.7 de que "as coordenadas de entrada crescem mais rápido ao longo da primeira dimensão de entrada", ou seja, o offset de bytes para o ponto de grade (i_0, i_1, ..., i_{N-1}) com M saídas é ((((i_{N-1} * Size[N-2] + i_{N-2}) * ...) * Size[0] + i_0) * M * BitsPerSample / 8.

Order - opcional, padrão 1. Aceita 1 (interpolação linear, padrão do PDF 1.7) ou 3 (interpolação cubic-spline) conforme PDF 1.7 Table 38. Cúbica dá transições mais suaves em densidades baixas de grade de amostras (ex.: curvas de tom ICC de 17 pontos), mas alguns leitores móveis mais antigos recaem silenciosamente para linear quando encontram um valor de Order que não implementam. Disponível desde o HotPDF v2.54.0.

Para casos de uso com entrada ASCII — o caminho típico de criação — uma única função de 1 entrada / M saídas com BitsPerSample = 8 e Size = [256] dá uma LUT de 256 amostras cujo stream é exatamente 256 * M bytes dispostos como (o0_0, o1_0, ..., oM-1_0, o0_1, ..., oM-1_255).

Domain - 2N valores Single, ordenados [in0Min in0Max in1Min in1Max ...]. A função limita os valores de entrada a esta faixa antes da interpolação. N é determinado a partir de Length(Domain) div 2.

Range - 2M valores Single com a mesma forma para as M dimensões de saída; as amostras de saída são limitadas a esta faixa após a decodificação.

Size - N inteiros dando a contagem de pontos de grade ao longo de cada eixo de entrada. Length(Size) deve ser igual a N. O total de pontos de grade é o produto de todas as entradas Size.

BitsPerSample - one of 1, 2, 4, 8, 12, 16, 24, or 32 per PDF 1.7 Table 38. 8 is the ergonomic choice (raw byte stream); 16 through 32 are byte-aligned big-endian widths; 1 / 2 / 4 / 12 require MSB-first bit packing with the final byte zero-padded to a byte boundary. Any other value raises an exception.

Samples - o stream bruto de amostras empacotadas em bits. O comprimento deve ser igual a ceil(GridPoints * M * BitsPerSample / 8) bytes, incluindo apenas padding do byte final quando necessário. O HotPDF valida cada profundidade empacotada suportada e copia os bytes fornecidos verbatim para o objeto de stream indireto; a correção do empacotamento de bits é responsabilidade do chamador.

A avaliação de páginas carregadas suporta de uma a quatro entradas e saídas, /Encode explícito para frente ou reverso, /Decode independente, /Order 1 multilinear, /Order 3 cúbico multidimensional e splines cúbicas naturais unidimensionais. Os bytes de amostras validados e os metadados de interpolação são retidos em uma LRU de oito entradas e 64 MiB para chamadas repetidas de tint, shading, soft mask e funções de transferência. Disponível desde o HotPDF v2.544.0.

Return value: o THPDFStreamObject indireto, de modo que chamadores possam anexá-lo ondequer que um dicionário de Function seja esperado (tipicamente passando a referência indireta dele para outro dict via AddValue, ou para um construtor de shading / separation). O objeto é de posse da lista IndirectObjects do documento e liberado no fim do documento. Retorna nil quando StrictVersionLock está ligado e o Version ativo está abaixo do PDF 1.2 (caso contrário a versão do documento é promovida automaticamente para 1.2).

Exemplo de código

// 256-sample 1-input / 3-output (RGB) heatmap LUT. The LUT maps a
// scalar t in [0..1] to a blue -> green -> red gradient through the
// midpoint
uses
  HPDFObjs;

var
  Func: THPDFStreamObject;
  Domain: array[0..1] of Single;
  Range: array[0..5] of Single;
  Size: array[0..0] of Integer;
  Samples: array[0..767] of byte;   // 256 grid points * 3 outputs
  I: Integer;
  T: Single;
begin
  HPDF.BeginDoc;
  // 1 input dim: t in [0..1]
  Domain[0] := 0; Domain[1] := 1;
  // 3 output dims: each in [0..1]
  Range[0] := 0; Range[1] := 1;
  Range[2] := 0; Range[3] := 1;
  Range[4] := 0; Range[5] := 1;
  // 256 sample points along the single input axis
  Size[0] := 256;

  for I := 0 to 255 do
  begin
    T := I / 255.0;
    if T < 0.5 then
    begin
      Samples[I*3 + 0] := 0;
      Samples[I*3 + 1] := byte(Round(2.0 * T * 255.0));
      Samples[I*3 + 2] := byte(Round((1.0 - 2.0*T) * 255.0));
    end
    else
    begin
      Samples[I*3 + 0] := byte(Round(2.0 * (T - 0.5) * 255.0));
      Samples[I*3 + 1] := byte(Round((1.0 - 2.0*(T - 0.5)) * 255.0));
      Samples[I*3 + 2] := 0;
    end;
  end;
  Func := HPDF.RegisterSampledFunction(Domain, Range, Size, 8, Samples);
  // Func is now an indirect THPDFStreamObject the caller can attach
  // to any PDF dict slot that accepts a Function reference
  HPDF.EndDoc;
end;