------------------------------------------------------------------
--
--  NAME: NDC_POINT_OPS
--  DISCREPANCY REPORTS:
--
------------------------------------------------------------------
-- File: NDC_POINT_OPS.ADA
-- Level: all

with GKS_TYPES;

use GKS_TYPES;

package NDC_POINT_OPS is

-- Package NDC_POINT_OPS provides extended functionality to the POINT
-- and VECTOR types defined in package NDC, an instance of
-- GKS_COORDINATE_SYSTEM.  The extensions are functions which perform
-- commonly desired operations on points and vectors.
--
-- The functions are grouped by the argument and result types, and
-- perform well-known mathematical functions:
--      DOT             vector dot product
--      NORM            the norm or length of a vector
--      DIST            Euclidean distance between points
--      "*"             Multiply VECTOR or POINT by a NDC_TYPE or
--                      NDC . MAGNITUDE and vice versa
--      "/"             Divide VECTOR or POINT by a NDC_TYPE or
--                      NDC . MAGNITUDE
--      "-"             Negative of a VECTOR or a POINT
--      "+","-"         Sum or difference of a VECTOR or a POINT
--      "+","-"         Mixed sums of VECTORs and POINTs with POINTs
--                      regarded as absolute positions and VECTORs as
--                      relative displacements.
--
-- One set of functions is somewhat unconventional:
--      "*","/"         Coordinate-wise multiply or divide of a VECTOR
--                      or a POINT
--
-- Because POINT and VECTOR are record types, not array types, it is
-- clumsy to use them as generic parameters, but see packages DC_OPS and
-- NDC_OPS for an instance of this technique. Instead of a generic
-- extension to GKS_COORDINATE_SYSTEM, this package directly implements
-- extensions to package NDC.
--
-- IMPORTANT, IMPLEMENTATION RESTRICTION:
-- A sister package, DC_POINT_OPS was generated from this one by
-- swapping all occurrences of the strings "DC" and "NDC".  By avoiding
-- any other use of these strings, an easy pseudo-generic instantiation
-- is made. Even comments should follow this rule.

   use NDC;

   subtype COORD is NDC_TYPE;
   subtype MAGNITUDE is NDC . MAGNITUDE;

-- DOT(V, V) => S  DOT PRODUCT
-- NORM(V)   => S  [S := SQRT( DOT(V,V) );]

   function DOT
      (A : in     VECTOR;
       B : in     VECTOR) return COORD;

   function NORM
      (A : in     VECTOR) return COORD;

   function NORM
      (A : in     VECTOR) return MAGNITUDE;

   function DIST
      (A : in     POINT;
       B : in     POINT) return COORD;

   function DIST
      (A : in     POINT;
       B : in     POINT) return MAGNITUDE;

-- Scalar operations

   function "*"
      (V : in     VECTOR;
       S : in     COORD) return VECTOR;

   function "*"
      (S : in     COORD;
       V : in     VECTOR) return VECTOR;

   function "/"
      (V : in     VECTOR;
       S : in     COORD) return VECTOR;

   function "*"
      (V : in     VECTOR;
       S : in     MAGNITUDE) return VECTOR;

   function "*"
      (S : in     MAGNITUDE;
       V : in     VECTOR) return VECTOR;

   function "/"
      (V : in     VECTOR;
       S : in     MAGNITUDE) return VECTOR;

   function "*"
      (P : in     POINT;
       S : in     COORD) return POINT;

   function "*"
      (S : in     COORD;
       P : in     POINT) return POINT;

   function "/"
      (P : in     POINT;
       S : in     COORD) return POINT;

   function "*"
      (P : in     POINT;
       S : in     MAGNITUDE) return POINT;

   function "*"
      (S : in     MAGNITUDE;
       P : in     POINT) return POINT;

   function "/"
      (P : in     POINT;
       S : in     MAGNITUDE) return POINT;

-- - V   => V [for I in X..Y loop V(I) := - V(I); end loop;]
-- V + V => V [for I in X..Y loop V(I) := VA(I) + VB(I); end loop;]
-- V - V => V [for I in X..Y loop V(I) := VA(I) - VB(I); end loop;]
-- V * V => V [for I in X..Y loop V(I) := VA(I) * VB(I); end loop;]
-- V / V => V [for I in X..Y loop V(I) := VA(I) / VB(I); end loop;]

   function "-"
      (A: in     VECTOR) return VECTOR;

   function "+"
      (A : in     VECTOR;
       B : in     VECTOR) return VECTOR;

   function "-"
      (A : in     VECTOR;
       B : in     VECTOR) return VECTOR;

   function "*"
      (A : in     VECTOR;
       B : in     VECTOR) return VECTOR;

   function "/"
      (A : in     VECTOR;
       B : in     VECTOR) return VECTOR;


-- - P   => P [for I in X..Y loop P(I) := - P(I); end loop;]
-- P + P => P [for I in X..Y loop P(I) := PA(I) + PB(I); end loop;]
-- P - P => P [for I in X..Y loop P(I) := PA(I) - PB(I); end loop;]
-- P * P => P [for I in X..Y loop P(I) := PA(I) * PB(I); end loop;]
-- P / P => P [for I in X..Y loop P(I) := PA(I) / PB(I); end loop;]
--
   function "-"
      (A : in     POINT) return POINT;

   function "+"
      (A : in     POINT;
       B : in     POINT) return POINT;

   function "-"
      (A : in     POINT;
       B : in     POINT) return POINT;

   function "*"
      (A : in     POINT;
       B : in     POINT) return POINT;

   function "/"
       (A : in     POINT;
        B : in     POINT) return POINT;

-- P - P => V [for I in X..Y loop V(I) := PA(I) - PB(I); end loop;]

   function "-"
      (HEAD : in     POINT;
       TAIL : in     POINT) return VECTOR;

-- P + V => P [for I in X..Y loop P(I) := PA(I) + VB(I); end loop;]
-- V + P => P [for I in X..Y loop P(I) := VA(I) + PB(I); end loop;]
-- P - V => P [for I in X..Y loop P(I) := PA(I) - VB(I); end loop;]
-- V - P => P [for I in X..Y loop P(I) := VA(I) - PB(I); end loop;]

   function "+"
      (P : in     POINT;
       V : in     VECTOR) return POINT;

   function "+"
      (V : in     VECTOR;
       P : in     POINT) return POINT;

   function "-"
      (P : in     POINT;
       V : in     VECTOR) return POINT;

   function "-"
      (V : in     VECTOR;
       P : in     POINT) return POINT;

end NDC_POINT_OPS;