# Copyright (c) 2025-2026 Gigasoft, Inc. All rights reserved.
=== ProEssentials Null Data (knowledge rev 4.1) & Missing Data Patterns ===
All 2D null data features apply to Direct2D/GdiPlus rendering only.

CRITICAL DEFAULT: NullDataValue defaults to 0.0 for ALL chart objects.
  This means ZEROS ARE NOT PLOTTED by default -- they are treated as null.
  If your data contains legitimate zeros, you MUST change NullDataValue:
    Pego1.PeData.NullDataValue = -9999;   // Pego: Y only
    Pesgo1.PeData.NullDataValue = -9999;   // Pesgo: Y
    Pesgo1.PeData.NullDataValueX = -9999;  // Pesgo: X (also Pepso, Pe3do)
    Pesgo1.PeData.NullDataValueZ = -9999;  // Pesgo/Pe3do: Z (contour/bubble/3D)
  Common sentinel values: -9999, -99999, -999.  Avoid >7 digits with single-precision data.

CREATING NULL DATA: Set data points equal to your NullDataValue sentinel:
    Pego1.PeData.NullDataValue = -9999.0;
    Pego1.PeData.Y[0, 3] = -9999;  // this point is now null

NULLDATAGAPS -- LINE BEHAVIOR (PePlot.Option.NullDataGaps):
  false (DEFAULT): Lines BRIDGE over null data -- line extends from last valid
    point to next valid point, skipping nulls. No visual gap.
  true: Lines BREAK at null data -- line stops before null, resumes after.
    Most developers want true as it is the more logical rendering.
  Applies to: Pego, Pesgo, Pepso.

NULLDATAGAPSAREA -- AREA BEHAVIOR (PePlot.Option.NullDataGapsArea):
  false (DEFAULT): Area plotting BRIDGES across null data regions.
  true: Area stops and restarts around null data, forming gaps.
    Isolated valid points between nulls render as vertical lines.
  Applies to: Pego, Pesgo.
  Separate from NullDataGaps because area fill behavior differs from line.

ISOLATED VALID POINTS BETWEEN NULLS:
  When NullDataGaps=true, a valid point surrounded by nulls on both sides
  renders as a point symbol only (no line connects to it).
  The symbol used is the SubsetPointType for that subset -- MarkDataPoints
  does NOT need to be enabled.  This catches developers off-guard when
  they see unexpected symbols and don't realize a valid point sits between
  two null values.

LINEGAPTHRESHOLD -- DISTANCE-BASED GAPS (PePlot.Option.LineGapThreshold):
  Alternative to NullDataGaps. Instead of marking individual points null,
  gaps form when the distance between consecutive non-null points exceeds
  the threshold.  For Pesgo: distance = X-axis difference. For Pego:
  distance = point-index difference.
  USE ONE OR THE OTHER -- do not combine NullDataGaps and LineGapThreshold.
  Only applies when PlottingMethod = Line.

FILTER2D AND NULL DATA INTERACTION (PeData.Filter2D):
  Filter2D is a Direct2D/GdiPlus data-reduction optimization.
  IMPORTANT: When data contains many scattered null values, set
    Filter2D = Filter2D.Disable
  Aggressive filtering with scattered nulls can produce rendering artifacts.
  Filter2D has no relationship to Direct3D rendering.

PE3DO (3D SURFACES) -- SURFACENULLDATAGAPS:
  PeData.SurfaceNullDataGaps (Pe3do only, under PeData not PePlot.Option):
    false (DEFAULT): Quads with null vertices are PEGGED to the bottom of
      the Y axis (not removed -- they render flat at Y minimum).
    true: Quads with a null vertex are REMOVED, forming holes in the surface.
  Direct3D surfaces do NOT bridge null data (unlike 2D line/area).
  SurfaceNullDataGaps=true is a PREREQUISITE for ManualScaleCullMaxY and
  related cull features to affect surface charts.

PE3DO (3D SCATTER/LINE/AREA via Direct3D):
  Scatter points: NullDataValue Y/X/Z supported -- null points not rendered.
  Line topology: Null vertices cause line segments to be removed (lines
    have 2 vertices, so segments touching a null vertex disappear).
  Area/Waterfall: Null Y data causes area portions to not render, forming
    gaps in the area fill.
  Alternative for scatter: Use PointColors with alpha=0 to make individual
  points invisible (Color.FromArgb(0, r, g, b)).

TABLE DISPLAY: Null data values appear as blank cells in data tables
  below the chart (visible in Example 006 -- table shows gaps where
  data is null).