path: root/src/Geom/Geom_Surface.cdl

-- File:	Geom_Surface.cdl
-- Created:	Wed Mar 10 10:24:50 1993
-- Author:	JCV
--		<fid@phylox>
-- Copyright:	 Matra Datavision 1993


deferred class Surface from Geom inherits Geometry from Geom
      
        ---Purpose : Describes the common behavior of surfaces in 3D
    	-- space. The Geom package provides many
    	-- implementations of concrete derived surfaces, such as
    	-- planes, cylinders, cones, spheres and tori, surfaces of
    	-- linear extrusion, surfaces of revolution, Bezier and
    	-- BSpline surfaces, and so on.
    	-- The key characteristic of these surfaces is that they
    	-- are parameterized. Geom_Surface demonstrates:
    	-- - how to work with the parametric equation of a
    	--   surface to compute the point of parameters (u,
    	--   v), and, at this point, the 1st, 2nd ... Nth derivative,
    	-- - how to find global information about a surface in
    	--   each parametric direction (for example, level of
    	--   continuity, whether the surface is closed, its
    	--   periodicity, the bounds of the parameters and so on), and
    	-- - how the parameters change when geometric
    	--   transformations are applied to the surface, or the
    	--   orientation is modified.
    	--   Note that all surfaces must have a geometric
    	-- continuity, and any surface is at least "C0". Generally,
    	-- continuity is checked at construction time or when the
    	-- curve is edited. Where this is not the case, the
    	-- documentation makes this explicit.
    	-- Warning
    	-- The Geom package does not prevent the construction of 
    	-- surfaces with null areas, or surfaces which self-intersect.
       

uses  Pnt     from gp,
      Vec     from gp,
      Trsf    from gp,
      GTrsf2d from gp,
      Shape   from GeomAbs,
      Curve   from Geom

raises RangeError          from Standard,
       NoSuchObject        from Standard,
       UndefinedDerivative from Geom,
       UndefinedValue      from Geom

is


  UReverse (me : mutable)
        ---Purpose :
        --  Reverses the U direction of parametrization of <me>. 
        --  The bounds of the surface are not modified.
     is deferred;


  UReversed (me)   returns mutable like me
        ---Purpose :
        --  Reverses the U direction of parametrization of <me>. 
        --  The bounds of the surface are not modified.
        --  A copy of <me> is returned.
     is static;

  UReversedParameter (me; U : Real) returns Real
	---Purpose: Returns the  parameter on the  Ureversed surface for
	--          the point of parameter U on <me>.
	--          
	--          me->UReversed()->Value(me->UReversedParameter(U),V)
	--          
	--          is the same point as
	--          
	--          me->Value(U,V)
     is deferred;

  VReverse (me : mutable)
        ---Purpose :
        --  Reverses the V direction of parametrization of <me>. 
        --  The bounds of the surface are not modified.
     is deferred;


  VReversed (me)  returns mutable like me
        ---Purpose :
        --  Reverses the V direction of parametrization of <me>.
        --  The bounds of the surface are not modified.
        --  A copy of <me> is returned.
     is static;


  VReversedParameter (me; V : Real) returns Real
	---Purpose: Returns the  parameter on the  Vreversed surface for
	--          the point of parameter V on <me>.
	--          
	--          me->VReversed()->Value(U,me->VReversedParameter(V))
	--          
	--          is the same point as
	--          
	--          me->Value(U,V)
     is deferred;

  TransformParameters(me; U,V : in out Real; T : Trsf from gp)
	---Purpose: Computes the  parameters on the  transformed  surface for
	--          the transform of the point of parameters U,V on <me>.
	--          
	--          me->Transformed(T)->Value(U',V')
	--          
	--          is the same point as
	--          
	--          me->Value(U,V).Transformed(T)
	--          
	--          Where U',V' are the new values of U,V after calling
	--          
	--          me->TranformParameters(U,V,T)
	--          
	--          This methods does not change <U> and <V>
	--          
	--          It  can be redefined.  For  example on  the Plane,
	--          Cylinder, Cone, Revolved and Extruded surfaces.
     is virtual;  

  ParametricTransformation(me; T : Trsf from gp) returns GTrsf2d from gp
	---Purpose: Returns a 2d transformation  used to find the  new
	--          parameters of a point on the transformed surface.
	--          
	--          me->Transformed(T)->Value(U',V')
	--          
	--          is the same point as
	--          
	--          me->Value(U,V).Transformed(T)
	--          
	--          Where U',V' are  obtained by transforming U,V with
	--          th 2d transformation returned by
	--          
	--          me->ParametricTransformation(T)
	--          
	--          This methods returns an identity transformation
	--          
	--          It  can be redefined.  For  example on  the Plane,
	--          Cylinder, Cone, Revolved and Extruded surfaces.
	--          
     is virtual;  

  Bounds(me; U1, U2, V1, V2 : out Real)
        ---Purpose: Returns the parametric bounds U1, U2, V1 and V2 of this surface.
    	-- If the surface is infinite, this function can return a value
    	-- equal to Precision::Infinite: instead of Standard_Real::LastReal.
     is deferred;
  

  IsUClosed (me)   returns Boolean
        ---Purpose : Checks whether this surface is closed in the u 
    	-- parametric direction.
    	-- Returns true if, in the u parametric direction: taking
    	-- uFirst and uLast as the parametric bounds in
    	-- the u parametric direction, for each parameter v, the
    	-- distance between the points P(uFirst, v) and
    	-- P(uLast, v) is less than or equal to gp::Resolution(). 
     is deferred;


  IsVClosed (me)   returns Boolean
    	---Purpose : Checks whether this surface is closed in the u 
    	-- parametric direction.
    	-- Returns true if, in the v parametric
    	-- direction: taking vFirst and vLast as the
    	-- parametric bounds in the v parametric direction, for
    	-- each parameter u, the distance between the points
    	-- P(u, vFirst) and P(u, vLast) is less than
    	-- or equal to gp::Resolution().
     is deferred;


  IsUPeriodic (me)   returns Boolean
        ---Purpose : Checks if this surface is periodic in the u 
    	-- parametric direction. Returns true if:
    	-- - this surface is closed in the u parametric direction, and
    	-- - there is a constant T such that the distance
    	--   between the points P (u, v) and P (u + T,
    	--   v) (or the points P (u, v) and P (u, v +
    	--   T)) is less than or equal to gp::Resolution().
    	-- Note: T is the parametric period in the u parametric direction.
    is deferred;

  UPeriod (me)  returns Real from Standard
	---Purpose: Returns the period of this surface in the u
        -- parametric direction.
  raises
    	NoSuchObject from Standard
	---Purpose: raises if the surface is not uperiodic.
  is virtual;


  IsVPeriodic (me)   returns Boolean
        ---Purpose : Checks if this surface is periodic in the v 
    	-- parametric direction. Returns true if:
    	-- - this surface is closed in the v parametric direction, and
    	-- - there is a constant T such that the distance
    	--   between the points P (u, v) and P (u + T,
    	--   v) (or the points P (u, v) and P (u, v +
    	--   T)) is less than or equal to gp::Resolution().
    	-- Note: T is the parametric period in the v parametric direction.
     is deferred;


  VPeriod (me)    returns Real from Standard
	---Purpose: Returns the period of this surface in the v parametric direction.
  raises
    	NoSuchObject from Standard
	---Purpose: raises if the surface is not vperiodic.
    is virtual;
    

  UIso (me; U : Real)  returns  mutable Curve
        ---Purpose : Computes the U isoparametric curve.
     is deferred;
     

  VIso (me; V : Real)  returns mutable Curve
        ---Purpose : Computes the V isoparametric curve.
     is deferred;


  Continuity (me)   returns Shape from GeomAbs
        ---Purpose :
        --  Returns the Global Continuity of the surface in direction U and V : 
        --  C0 : only geometric continuity,
        --  C1 : continuity of the first derivative all along the surface,
        --  C2 : continuity of the second derivative all along the surface,
        --  C3 : continuity of the third derivative all along the surface,
        --  G1 : tangency continuity all along the surface,
        --  G2 : curvature continuity all along the surface,
        --  CN : the order of continuity is infinite.
        -- Example :
        --  If the surface is C1 in the V parametric direction and C2
        --  in the U parametric direction Shape = C1.
     is deferred;


  IsCNu (me; N : Integer)   returns Boolean
        ---Purpose : Returns the order of continuity of the surface in the 
        --  U parametric direction. 
     raises RangeError
        ---Purpose : Raised if N < 0.
     is deferred;


  IsCNv (me; N : Integer)   returns Boolean
        ---Purpose : Returns the order of continuity of the surface in the 
        --  V parametric direction. 
     raises RangeError
        ---Purpose : Raised if N < 0.
     is deferred;


  D0 (me; U, V : Real; P : out Pnt)
        ---Purpose : Computes the point of parameter U,V on the surface.
     raises UndefinedValue
        ---Purpose : 
        --  Raised only for an "OffsetSurface" if it is not possible to
        --  compute the current point. 
     is deferred;


  D1 (me; U, V : Real; P : out Pnt; D1U, D1V : out Vec)
        ---Purpose :
        --  Computes the point P and the first derivatives in the
        --  directions U and V at this point.
     raises UndefinedDerivative
        ---Purpose : Raised if the continuity of the surface is not C1.
     is deferred;


  D2 (me; U, V : Real; P : out Pnt; D1U, D1V, D2U, D2V, D2UV : out Vec)
        ---Purpose :
        --  Computes the point P, the first and the second derivatives in
        --  the directions U and V at this point.
     raises UndefinedDerivative
        ---Purpose : Raised if the continuity of the surface is not C2.
     is deferred;


  D3 (me; U, V : Real; P : out Pnt; 
      D1U, D1V, D2U, D2V, D2UV, D3U, D3V, D3UUV, D3UVV :out Vec)
        ---Purpose :
        --  Computes the point P, the first,the second and the third 
        --  derivatives in the directions U and V at this point.
     raises UndefinedDerivative
        ---Purpose : Raised if the continuity of the surface is not C2.
     is deferred;


  DN (me; U, V : Real; Nu, Nv : Integer)   returns Vec
        ---Purpose ;
        --  Computes the derivative of order Nu in the direction U and Nv
        --  in the direction V at the point P(U, V).
     raises UndefinedDerivative,
        ---Purpose : 
        --  Raised if the continuity of the surface is not CNu in the U
        --  direction or not CNv in the V direction.
            RangeError
        ---Purpose : Raised if Nu + Nv < 1 or Nu < 0 or Nv < 0.
     is deferred;
  

  Value (me; U, V : Real)    returns Pnt
        ---Purpose :
        --  Computes the point of parameter U on the surface.
        --  
        --  It is implemented with D0
     raises UndefinedValue
        ---Purpose : 
        --  Raised only for an "OffsetSurface" if it is not possible to
        --  compute the current point. 
     is static;


end;