THotPDF.RegisterSampledFunction Method

Δηλώνει PDF 1.3+ Function Type 0 (Sampled) indirect stream object (ISO 32000-1 7.10.2). Οι Sampled functions εκφράζουν arbitrary input-to-output mapping ως regular N-dimensional grid από M-dimensional output samples· ο renderer παρεμβάλλει γραμμικά ανάμεσα σε grid points για να αξιολογήσει intermediate inputs. Χρησιμοποιήστε το όπου το ICC profile machinery είναι υπερβολικό αλλά χρειάζεται hand-tuned lookup table - tone curves για /TransferFunction (ExtGState /TR), sampled tint transforms για /Separation ή /DeviceN (εναλλακτική στις linear Type 2 / arithmetic Type 4 paths), halftone threshold curves ή οποιοδήποτε άλλο PDF construct που δέχεται Function dictionary

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);

The function is emitted as an indirect stream with /FunctionType 0, the supplied /Domain, /Range, /Size, /BitsPerSample and /Order entries, plus the raw bit-packed sample stream. /Encode and /Decode are omitted so the spec defaults apply: /Encode maps each Domain endpoint to grid extents [0..Size[i]-1], and /Decode matches /Range (samples are unpacked to integers and linearly remapped back to the Range endpoints). For multi-input functions the sample byte order follows the PDF 1.7 rule "input coordinates increase fastest along the first input dimension", i.e. the byte offset for grid point (i_0, i_1, ..., i_{N-1}) with M outputs is ((((i_{N-1} * Size[N-2] + i_{N-2}) * ...) * Size[0] + i_0) * M * BitsPerSample / 8.

Order - optional, default 1. Accepts 1 (linear interpolation, PDF 1.7 default) or 3 (cubic-spline interpolation) per PDF 1.7 Table 38. Cubic gives smoother transitions at low sample-grid densities (e.g. 17-point ICC tone curves) but some older mobile readers silently fall back to linear when they encounter an Order value they do not implement. Available since HotPDF v2.54.0.

For ASCII-input use cases - the typical authoring path - a single 1-input / M-output function with BitsPerSample = 8 and Size = [256] gives a 256-sample LUT whose stream is exactly 256 * M bytes laid out as (o0_0, o1_0, ..., oM-1_0, o0_1, ..., oM-1_255).

Domain - 2N Single values, ordered [in0Min in0Max in1Min in1Max ...]. The function clamps incoming values to this range before interpolation. N is determined from Length(Domain) div 2.

Range - 2M Single values με το ίδιο shape για τις M output dimensions· τα output samples γίνονται clamped σε αυτό το range μετά το decoding

Size - N integers που δίνουν το grid-point count κατά μήκος κάθε input axis. Το Length(Size) πρέπει να ισούται με N. Τα total grid points είναι το γινόμενο όλων των Size entries

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 - το raw bit-packed sample stream. Το Length πρέπει να είναι τουλάχιστον ceil(GridPoints * M * BitsPerSample / 8) bytes. Το HotPDF αντιγράφει τα supplied bytes verbatim στο indirect stream object· η bit-pack correctness είναι ευθύνη του καλούντος

Return value: το indirect THPDFStreamObject ώστε οι καλούντες να μπορούν να το προσαρτήσουν όπου αναμένεται Function dictionary (συνήθως περνώντας το indirect reference του σε άλλο dict μέσω AddValue ή σε shading / separation builder). Το object ανήκει στη IndirectObjects list του document και απελευθερώνεται στο τέλος του document. Επιστρέφει nil όταν το StrictVersionLock είναι on και το active Version είναι κάτω από PDF 1.3 (διαφορετικά το document version γίνεται auto-bump σε 1.3)

Code Example

// 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;