0024070: OpenGL capped object-level clipping planes

[occt.git] / src / Select3D / Select3D_Projector.cdl

-- Created on: 1992-03-12
-- Created by: Christophe MARION
-- Copyright (c) 1992-1999 Matra Datavision
-- Copyright (c) 1999-2012 OPEN CASCADE SAS
--
-- The content of this file is subject to the Open CASCADE Technology Public
-- License Version 6.5 (the "License"). You may not use the content of this file
-- except in compliance with the License. Please obtain a copy of the License
-- at http://www.opencascade.org and read it completely before using this file.
--
-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
--
-- The Original Code and all software distributed under the License is
-- distributed on an "AS IS" basis, without warranty of any kind, and the
-- Initial Developer hereby disclaims all such warranties, including without
-- limitation, any warranties of merchantability, fitness for a particular
-- purpose or non-infringement. Please see the License for the specific terms
-- and conditions governing the rights and limitations under the License.

--        <cma@sdsun2> copie quasi exacte de HLRAlgo_Projector

class Projector from Select3D inherits Transient from Standard
    ---Purpose: A framework to define 3D projectors.
    -- Projector provides services for projecting points from
    -- world-coordinates to a viewing plane. Projection could be defined by
    -- corresponding transformation, or coordinate system. The transformation
    -- could be constructed for a view with transposed view transformation
    -- matrix ( that represents view-orientation ), including, for perspective
    -- view, focal distance ( distance from an eye to the view plane ) and
    -- translational part that represents translation of focal point in
    -- view-coordinate space. The Select3D_Projector class recognizes the
    -- predefined set of popular projections: axonometric, top view, front
    -- view and uses more efficient algorithm for projection computations.
    -- User-defined transformation could be also defined in constructor.
    -- Perspective projection consists of two separate parts, that are
    -- composed together during computation: transformation component and
    -- focale distance.

uses
    Real    from Standard,
    Boolean from Standard,
    Trsf    from gp,
    GTrsf   from gp,
    Lin     from gp,
    Pnt     from gp,
    Vec     from gp,
    Ax2     from gp,
    Vec2d   from gp,
    Pnt2d   from gp,
    Box     from Bnd,
    View    from V3d

raises
    NoSuchObject from Standard

is

    Create(aView:View from V3d) returns Projector from Select3D;
    --- Purpose: Constructs the 3D projector object defined by the 3D view aView.
    Create returns Projector from Select3D;

    Create(CS : Ax2 from gp)
    ---Purpose: Creates an axonometric projector. <CS> represents viewing coordinate 
    -- system and could be constructed from x direction, view plane normal direction, 
    -- and view point location in world-coordinate space.
    returns Projector from Select3D;

    Create(CS    : Ax2  from gp;
           Focus : Real from Standard)
    ---Purpose: Creates  a  perspective  projector. <CS> represents viewing
    -- coordinate system and could be constructed from x direction, 
    -- view plane normal direction, and focal point location in world-coordinate
    -- space. <Focus> should represent distance of an eye from view plane
    -- in world-coordinate space (focal distance).
    returns Projector from Select3D;

    Create(T         : Trsf    from gp;
           Persp     : Boolean from Standard;
           Focus     : Real    from Standard)
    ---Purpose: build a Projector from the given transformation.
    -- In case, when <T> transformation should represent custom view projection,
    -- it could be constructed from two separate components: transposed view
    -- orientation matrix and translation of focal point in view-coordiante
    -- system. <T> could be built up from x direction, up direction,
    -- view plane normal direction vectors and translation with SetValues(...)
    -- method, where first row arguments (a11, a12, a13, a14)  are x, y, z
    -- component of x direction vector, and x value of reversed translation
    -- vector. Second row arguments, are x y z for up direction and y value of
    -- reversed translation, and the third row defined in the same manner.
    -- This also suits for simple perspective view, where <Focus> is the focale
    -- distance of an eye from view plane in world-space coordiantes.
    -- Note, that in that case amount of perspective distortion (perspective
    -- angle) should be defined through focal distance.
    returns Projector from Select3D;

    Create(GT        : GTrsf   from gp;
           Persp     : Boolean from Standard;
           Focus     : Real    from Standard)
    ---Purpose: build a Projector from the given transformation.
    -- In case, when <GT> transformation should represent custom view
    -- projection, it could be constructed from two separate components:
    -- transposed view orientation matrix and translation of a focal point
    -- in view-coordinate system.
    -- This also suits for perspective view, with <Focus> that could be
    -- equal to distance from an eye to a view plane in 
    -- world-coordinates (focal distance).
    -- The 3x3 transformation matrix is built up from three vectors:
    -- x direction, up direction and view plane normal vectors, where each
    -- vector is a matrix row. Then <GT> is constructed from matrix and
    -- reversed translation with methods SetTranslationPart(..) and
    -- SetVectorialPart(..).
    -- Note, that in that case amount of perspective distortion (perspective
    -- angle) should be defined through focal distance.
    returns Projector from Select3D;

    Set (me : mutable;
         T         : Trsf    from gp;
         Persp     : Boolean from Standard;
         Focus     : Real    from Standard)
    is static;

    SetView(me : mutable; V : View from V3d);
    ---Purpose: Sets the 3D view V used at the time of construction.

    View(me) returns any View from V3d;
    ---Purpose: Returns the 3D view used at the time of construction.
    ---C++: return const&
    ---C++: inline

    Scaled(me : mutable; On : Boolean from Standard = Standard_False)
    ---Purpose: to compute with the given scale and translation.
    is virtual;

    Perspective(me) returns Boolean
    ---Purpose: Returns True if there is a perspective transformation.
    ---C++: inline
    is virtual;

    Transformation(me) returns GTrsf from gp
    ---Purpose: Returns the active transformation.
    ---C++: inline
    ---C++: return const &
    is virtual;

    InvertedTransformation(me) returns GTrsf from gp
    ---Purpose: Returns the active inverted transformation.
    ---C++: inline
    ---C++: return const &
    is virtual;

    FullTransformation(me) returns Trsf from gp
    ---Purpose: Returns the original transformation.
    ---C++: inline
    ---C++: return const &
    is virtual;

    Focus(me) returns Real from Standard
    ---Purpose: Returns the focal length.
    ---C++: inline
    raises
        NoSuchObject from Standard -- if there is no perspective
    is virtual;

    Transform(me; D : in out Vec from gp)
    ---C++: inline
    is virtual;

    Transform(me; Pnt : in out Pnt from gp)
        ---C++: inline
    is virtual;

    Project(me; P    :     Pnt   from gp;
                Pout : out Pnt2d from gp)
    ---Purpose: Transform and apply perspective if needed.
    is virtual;

    Project(me; P     :     Pnt  from gp;
                X,Y,Z : out Real from Standard)
    ---Purpose: Transform and apply perspective if needed.
    is static;

    Project(me; P     :     Pnt   from gp;
                D1    :     Vec   from gp;
                Pout  : out Pnt2d from gp;
        D1out : out Vec2d from gp)
    ---Purpose: Transform and apply perspective if needed.
    is virtual;

    Shoot(me; X , Y : Real from Standard)
    returns Lin from gp
    ---Purpose: return a line going through the eye towards the
    --          2d point <X,Y>.
    is virtual;

    Transform(me; P : in out Pnt from gp;
                  T : GTrsf from gp)
    ---C++: inline
    is virtual;

    Transform(me; D : in out Lin from gp;
                  T : GTrsf from gp)
    ---C++: inline
    is virtual;

fields
    myType       : Integer from Standard;

    myPersp      : Boolean from Standard is protected;
    myFocus      : Real    from Standard is protected;
    myScaledTrsf : Trsf    from gp is protected;
    myGTrsf      : GTrsf   from gp is protected;
    myInvTrsf    : GTrsf   from gp is protected;

    myView       : View    from V3d;

end Projector;