مرجع HotPDF: THotPDFRegisterSampledFunctionMethod

يعرّف عنصر تدفق غير مباشر من نوع Function Type 0 (Sampled) الخاص بـ PDF 1.2+ وفق ISO 32000-1 7.10.2. وتصوغ الدالات المُعينة المدخلات إلى المخرجات تعبيرًا عشوائيًا في شكل شبكة منتظمة من N أبعاد إدخال تضم عينات مخرجات M-الأبعاد؛ ويسقط العارض بين نقاط الشبكة لتقييم المدخلات الوسيطة. استخدم هذا النوع حيث تكون آليات ملف تعريف ICC مبالغةً لكن يُراد جدول بحث مضبوط يدويًا: منحنيات نبرة لـ /TransferFunction في ExtGState عبر /TR، أو تحويلات تدرّج مُعينة للعينات لـ /Separation أو /DeviceN كبديل عن المسار الخطي Type 2 أو الحسابي Type 4، أو منحنيات عتبة halftone، أو أي بنية PDF أخرى تقبل قاموس 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);

تُصدر الدالة تدفقًا غير مباشر يحمل /FunctionType 0 وقيم /Domain و /Range و /Size و /BitsPerSample و /Order المزودة، إضافة إلى تدفق العينات المرمّز بالبتات خامًا. وتُترك /Encode و /Decode محذوفتين لتنطبق افتراضيات المواصفة: تُسقط /Encode كل طرف من أطراف Domain على مدى الشبكة [0..Size[i]-1]، وتطابق /Decode قيم /Range (تُفك العينات إلى أعداد صحيحة ثم يُعاد إسقاطها خطيًا على طرفي Range). وفي الدالات متعددة المدخلات يتبع ترتيب بايتات العينات قاعدة PDF 1.7 القائلة إن «إحداثيات المدخل تتزايد بأسرع وتيرة على طول بُعد المدخل الأول»، أي أن إزاحة البايت لنقطة الشبكة (i_0, i_1, ..., i_{N-1}) مع M مخرجات هي ((((i_{N-1} * Size[N-2] + i_{N-2}) * ...) * Size[0] + i_0) * M * BitsPerSample / 8

Order - اختياري، الافتراضي 1. يقبل 1 (استيفاء خطي، افتراضي PDF 1.7) أو 3 (استيفاء شرائح تكعيبي) وفق PDF 1.7 Table 38. ويمنح التكعيبي انتقالات أنعم عند كثافات شبكات عينات منخفضة (كتزدادات نبرة ICC ذات 17 نقطة مثلًا)، لكن بعض القراءات المحمولة الأقدم تعود صامتةً إلى الخطي عندما تقابل قيمة Order لا تنفذها. متاح منذ HotPDF v2.54.0

في حالات الاستخدام ذات المدخلات ASCII — وهي مسار التأليف النمطي — تمنح الدالة ذات المدخل الواحد و M مخرجات، مع BitsPerSample = 8 و Size = [256]، جدول بحث من 256 عينة يكون تدفقه بالضبط 256 * M بايتًا مرتبةً كـ (o0_0, o1_0, ..., oM-1_0, o0_1, ..., oM-1_255)

Domain - قيم Single عددها 2N بترتيب [in0Min in0Max in1Min in1Max ...]. تُربط القيم الداخلة بهذا المدى قبل الاستيفاء. ويُستدل على N من Length(Domain) div 2

Range - قيم Single عددها 2M بالشكل نفسه لأبعاد المخرجات M؛ وتُربط عينات المخرجات بهذا المدى بعد فك الترميز

Size - N عددًا صحيحًا تعطي عدد نقاط الشبكة على كل محور إدخال. ويجب أن يساوي Length(Size) قيمة N. وعدد نقاط الشبكة الكلي هو حاصل ضرب كل إدخالات Size

BitsPerSample - إحدى القيم 1 أو 2 أو 4 أو 8 أو 12 أو 16 أو 24 أو 32 وفق PDF 1.7 Table 38. والقيمة 8 هي الخيار المريح (تدفق بايتات خام)؛ والقيم من 16 إلى 32 عروض محاذاة للبايت بترتيب big-endian؛ وتتطلب القيم 1 / 2 / 4 / 12 ترميزًا بالبتات يبدأ بالبت الأعلى مع حشو البايت الأخير بالأصفار حتى حد البايت. وأي قيمة أخرى ترفع استثناء

Samples - تدفق العينات المرمّز بالبتات خامًا. ويجب أن يساوي طوله ceil(GridPoints * M * BitsPerSample / 8) بايتًا، لا يشمل سوى حشو البايت الأخير عند الحاجة. ويتحقق HotPDF من كل عمق ترميز مدعوم وينسخ البايتات المزودة حرفيًا إلى عنصر التدفق غير المباشر؛ وتبقى صحة ترميز البتات على عاتق المستدعي

يدعم تقييم الصفحات المحمّلة من مدخل إلى أربعة مدخلات ومخرجات، وقيم /Encode صريحة أمامية أو معكوسة، وقيم /Decode مستقلة، و /Order 1 متعدد الخطية، و /Order 3 التكعيبي متعدد الأبعاد، والشرائح التكعيبية الطبيعية أحادية البعد. وتُحفظ بايتات العينات المتحقق منها وبيانات الاستيفاء الوصفية في ذاكرة LRU من ثمانية إدخالات بسعة 64 MiB لاستدعاءات التدرج والتظليل وقناع الشفافية ودالة النقل المتكررة. متاح منذ HotPDF v2.544.0

القيمة المعادة: الكائن غير المباشر THPDFStreamObject ليتمكن المستدعي من إرفاقه أينما كان متوقعًا قاموس Function (عادةً بتمرير مرجعه غير المباشر إلى قاموس آخر عبر AddValue، أو إلى أداة إنشاء تدرّج/فصل لوني shading / separation). يملك هذا الكائن ضمن قائمة IndirectObjects الخاصة بالمستند ويُحرَّر عند انتهاء المستند. يُعيد nil عندما يكون StrictVersionLock مفعّلاً وتكون Version النشطة أقل من PDF 1.2 (وإلا فإن نسخة المستند تُرفع تلقائيًا إلى 1.2)

معلومات إضافية

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