## view

view — Defines all necessary informations for the rendering of a view.

## Synopsis

    #define             PI180
                        VisuOpenGLView;
                        VisuOpenGLCamera;
    enum                ViewAxis;
    #define             VISU_CAMERA_THETA
    #define             VISU_CAMERA_PHI
    #define             VISU_CAMERA_OMEGA
    gboolean            openGLCameraSet_thetaPhiOmega       (VisuOpenGLCamera *camera,
                                                             float valueTheta,
                                                             float valuePhi,
                                                             float valueOmega,
                                                             int mask);
    #define             MASK_XS
    #define             MASK_YS
    gboolean            openGLCameraSet_XsYs                (VisuOpenGLCamera *camera,
                                                             float valueX,
                                                             float valueY,
                                                             int mask);
    gboolean            openGLCameraSet_gross               (VisuOpenGLCamera *camera,
                                                             float value);
    gboolean            openGLCameraSet_persp               (VisuOpenGLCamera *camera,
                                                             float value);
    gboolean            openGLCameraSet_refLength           (VisuOpenGLCamera *camera,
                                                             float value,
                                                             ToolUnits unit);
    float               openGLCameraGet_refLength           (VisuOpenGLCamera *camera,
                                                             ToolUnits *unit);
                        OpenGLWindow;
    gboolean            openGLWindowSet_viewport            (OpenGLWindow *window,
                                                             guint width,
                                                             guint height);
    float               VisuOpenGLViewGet_fileUnitPerPixel  (VisuOpenGLView *view);
    void                VisuOpenGLViewGet_screenAxes        (VisuOpenGLView *view,
                                                             float xAxis[3],
                                                             float yAxis[3]);
    float               openGLViewGet_zCoordinate           (VisuOpenGLView *view,
                                                             float xyz[3]);
    void                openGLViewGet_realCoordinates       (VisuOpenGLView *view,
                                                             float xyz[3],
                                                             float winx,
                                                             float winy,
                                                             float winz);
    void                openGLViewSet_upAxis                (VisuOpenGLView *view,
                                                             ViewAxis upAxis);
    VisuOpenGLView*     VisuOpenGLViewNew                   (void);
    void                VisuOpenGLViewFree                  (VisuOpenGLView *view);
    VisuOpenGLView*     VisuOpenGLViewCopy                  (VisuOpenGLView *view);
    gint                VisuOpenGLCameraGet_numberOfFacettes
                                                            (VisuOpenGLCamera *camera,
                                                             guint winSize,
                                                             float dimension);
    void                openGLProject                       (OpenGLWindow *window,
                                                             const VisuOpenGLCamera *camera,
                                                             float extens);
    void                openGLModelize                      (VisuOpenGLCamera *camera);
    int                 VisuOpenGLViewSet_precision         (float value);
    float               VisuOpenGLViewGet_precision         (void);
    void                openGLViewRotate_box                (VisuOpenGLView *view,
                                                             float dTheta,
                                                             float dPhi,
                                                             float angles[2]);
    void                openGLViewRotate_camera             (VisuOpenGLView *view,
                                                             float dTheta,
                                                             float dPhi,
                                                             float angles[3]);
    void                VisuOpenGLViewInit                  (void);

## Description

The VisuOpenGLView stores three basic informations: one for the position and orientation of the camera (VisuOpenGLCamera), one for the description of the bounding box in the OpenGL coordinates (OpenGLBox, should be moved elsewhere later) and one last for the definition of the viewing window (OpenGLWindow, including volumic informations).

One resource is used by this part, defining the precision desired by the user when drawing OpenGL objects. This precision can be changed using `VisuOpenGLViewSet_precision()` and all V_Sim part drawing something should use `VisuOpenGLCameraGet_numberOfFacettes()` to know the size of the vertices to be drawn depending on this precision and the level of zoom.

The rendering is done in an OpenGl viewport whose size is given by the bounding box (plus 10%). The camera can be positionned with three angles (theta, phi and omega) and has a zoom factor (gross) and a perspective value (d_red). The angle theta is around the z axis (box coordinates), phi is around the new x axis (after the theta rotation) and omega is a rotation around the axis which goes from the observer to the center of the bounding box. By default the camera looks at the center of the bounding box but this can be changed with the Xs and Ys parameters. These values are stored and are readable through the VisuOpenGLCamera structure. They must be changed with the following methods : `openGLViewSet_thetaPhiOmega()`, `openGLViewSet_gross()`, `openGLViewSet_persp()` and `openGLViewSet_XsYs()`.

## Details

### PI180

    #define PI180 0.017453292522

Value of pi / 180.

### VisuOpenGLView

    typedef struct {
      VisuOpenGLCamera *camera;
      OpenGLWindow *window;
    } VisuOpenGLView;

A container structure to deal with OpenGL observer position, size of rendering viewport...

VisuOpenGLCamera *`camera`; | a VisuOpenGLCamera structure;
OpenGLWindow *`window`; | a OpenGLWindow structure;

### VisuOpenGLCamera

    typedef struct {
      /* Perspective. */
      double d_red;
      /* Orientation. */
      double theta, phi, omega;
      /* Position. */
      double xs, ys;
      /* Zoom. */
      double gross;
      /* A length reference and its unit. */
      double length0;
      ToolUnits unit;

      /* Up vector. */
      double up[3];
      /* Up axis. */
      ViewAxis upAxis;
      /* Eye target and eye position. */
      double centre[3], eye[3];
    } VisuOpenGLCamera;

Values to define the position of the observer.

double `d_red`; | a factor for perspective from 1. to inifnity. With one, the nose of the observer is completly set on the rendered object, and the size of the observer is neglectible compared to the size of the object.
double `theta`; | the theta angle in spherical coordinates of the position of the observer ;
double `phi`; | the phi angle in spherical coordinates of the position of the observer ;
double `omega`; | rotation of the observer on itself ;
double `xs`; | a value for translation of the viewport on x axis ;
double `ys`; | a value for translation of the viewport on y axis ;
double `gross`; | a value of zoom ;
double `length0`; | a length reference to adimension all values, by default, this is the longest diagonal of the current box (without duplication) ;
ToolUnits `unit`; | the unit of `length0`.
double `up`[3]; | the current up vector.. in. array fixed-size=3.
ViewAxis `upAxis`; | which axis define the north pole.
double `centre`[3]; | position of the eye look at ;. in. array fixed-size=3.
double `eye`[3]; | position of the eye.. in. array fixed-size=3.

### enum ViewAxis

    typedef enum
      {
        VIEW_X,
        VIEW_Y,
        VIEW_Z
      } ViewAxis;

Define the up axis.

`VIEW_X` | the up axis is X ;
`VIEW_Y` | the up axis is Y ;
`VIEW_Z` | the up axis is Z.

### VISU_CAMERA_THETA

    #define VISU_CAMERA_THETA (1 << 1)

Value used in the `openGLCameraSet_thetaPhiOmega()` method to store the tetha angle.

### VISU_CAMERA_PHI

    #define VISU_CAMERA_PHI   (1 << 2)

Value used in the `openGLCameraSet_thetaPhiOmega()` method to store the phi angle.

### VISU_CAMERA_OMEGA

    #define VISU_CAMERA_OMEGA   (1 << 3)

Value used in the `openGLCameraSet_thetaPhiOmega()` method to store the omega angle.

### openGLCameraSet_thetaPhiOmega ()

    gboolean            openGLCameraSet_thetaPhiOmega       (VisuOpenGLCamera *camera,
                                                             float valueTheta,
                                                             float valuePhi,
                                                             float valueOmega,
                                                             int mask);

Change the orientation of the camera to the specified angles.

`camera` : | a valid VisuOpenGLCamera object ;
`valueTheta` : | a floatinf point value in degrees ;
`valuePhi` : | a floating point value in degrees ;
`valueOmega` : | a floating point value in degrees ;
`mask` : | to specified what values will be changed.
Returns : | TRUE if the signal OpenGLAskForReDraw should be emitted.

### MASK_XS

    #define MASK_XS (1 << 1)

Value used in the `openGLCameraSet_XsYs()` method to store the horizontal offset.

### MASK_YS

    #define MASK_YS   (1 << 2)

Value used in the `openGLCameraSet_XsYs()` method to store the vertical offset.

### openGLCameraSet_XsYs ()

    gboolean            openGLCameraSet_XsYs                (VisuOpenGLCamera *camera,
                                                             float valueX,
                                                             float valueY,
                                                             int mask);

Change the point where the camera is pointed to.

`camera` : | a valid VisuOpenGLCamera object ;
`valueX` : | a floatinf point value in the bounding box scale (1 is the size of the bounding box) ;
`valueY` : | a floating point value in bounding box scale ;
`mask` : | to specified what values will be changed.
Returns : | TRUE if the signal OpenGLAskForReDraw should be emitted.

### openGLCameraSet_gross ()

    gboolean            openGLCameraSet_gross               (VisuOpenGLCamera *camera,
                                                             float value);

Change the value of the camera zoom value. If the value is higher than 10 it is set to 10 and if the value is negative it is set to 0.001.

`camera` : | a valid VisuOpenGLCamera object ;
`value` : | a positive floating point value.
Returns : | TRUE if the signal OpenGLAskForReDraw should be emitted.

### openGLCameraSet_persp ()

    gboolean            openGLCameraSet_persp               (VisuOpenGLCamera *camera,
                                                             float value);

Change the value of the camera perspective value and put it in bounds if needed.

`camera` : | a valid VisuOpenGLCamera object ;
`value` : | a floating point value greater than 1.1.
Returns : | TRUE if the signal OpenGLAskForReDraw should be emitted.

### openGLCameraSet_refLength ()

    gboolean            openGLCameraSet_refLength           (VisuOpenGLCamera *camera,
                                                             float value,
                                                             ToolUnits unit);

Change the reference value that is used for the zoom.

`camera` : | a VisuOpenGLCamera object.
`value` : | a new length.
`unit` : | its measurement unit.
Returns : | TRUE if the value is indeed changed.

Since 3.6

### openGLCameraGet_refLength ()

    float               openGLCameraGet_refLength           (VisuOpenGLCamera *camera,
                                                             ToolUnits *unit);

The zoom is define from a reference length in given unit. If `unit` is provided, the corresponding unit will be set.

`camera` : | a VisuOpenGLCamera object.
`unit` : | a location for unit value (can be NULL).
Returns : | the current reference length.

Since 3.6

### OpenGLWindow

    typedef struct {
      guint width, height;
      double near, far;
      double left, right, bottom, top;
    } OpenGLWindow;

Values to describe the window where the render is done.

guint `width`; | the width of the window ;
guint `height`; | the height of the window ;
double `near`; | the beginning of the viewport on z axis (z for observer) ;
double `far`; | the end of the viewport on z axis (z for observer) ;
double `left`; | the left of the viewport on x axis ;
double `right`; | the right of the viewport on x axis ;
double `bottom`; | the bottom of the viewport on y axis ;
double `top`; | the top of the viewport on y axis ;

### openGLWindowSet_viewport ()

    gboolean            openGLWindowSet_viewport            (OpenGLWindow *window,
                                                             guint width,
                                                             guint height);

It changes the size of the OpenGl area and reccompute the OpenGL viewport.

`window` : | a valid OpenGLWindow object ;
`width` : | the new horizontal size ;
`height` : | the new vertical size.
Returns : | TRUE the size of `window` is actually changed.

### VisuOpenGLViewGet_fileUnitPerPixel ()

    float               VisuOpenGLViewGet_fileUnitPerPixel  (VisuOpenGLView *view);

This method is used to know the ratio of a pixel with the unit of the file. WARNING : this method is valid only when the camera is position at infinity.

`view` : | a valid VisuOpenGLView object.
Returns : | how much of a unit of file is in a pixel.

### VisuOpenGLViewGet_screenAxes ()

    void                VisuOpenGLViewGet_screenAxes        (VisuOpenGLView *view,
                                                             float xAxis[3],
                                                             float yAxis[3]);

This method is used to get the coordinates in box frame of x axis and y axis of the current camera view.

`view` : | a valid VisuOpenGLView.
`xAxis` : | three float values representing x axis ;. in. array fixed-size=3.
`yAxis` : | three float values representing y axis.. in. array fixed-size=3.

### openGLViewGet_zCoordinate ()

    float               openGLViewGet_zCoordinate           (VisuOpenGLView *view,
                                                             float xyz[3]);

Use this routine to know the Z value of a real point defined by `xyz` in caretsian coordinates.

`view` : | a VisuOpenGLView object.
`xyz` : | a cartesian point.

### openGLViewGet_realCoordinates ()

    void                openGLViewGet_realCoordinates       (VisuOpenGLView *view,
                                                             float xyz[3],
                                                             float winx,
                                                             float winy,
                                                             float winz);

Use this routine to get the cartesian coordinates in real space of a point located at `winx` and `winy` on screen.

`view` : | a VisuOpenGLView object.
`xyz` : | a location to store the result.
`winx` : | position on X axis of screen.
`winy` : | position on Y axis of screen.
`winz` : | height before projection on screen.

### openGLViewSet_upAxis ()

    void                openGLViewSet_upAxis                (VisuOpenGLView *view,
                                                             ViewAxis upAxis);

In constraint observation mode, the "north" direction is a singular one. Define this direction with this routine.

`view` : | a VisuOpenGLView object.
`upAxis` : | a direction.

Since 3.6

### VisuOpenGLViewNew ()

    VisuOpenGLView*     VisuOpenGLViewNew                   (void);

Create a new VisuOpenGLView object with default values.

Returns : | the newly created object (to be free with `VisuOpenGLViewFree()`).. transfer none.

### VisuOpenGLViewFree ()

    void                VisuOpenGLViewFree                  (VisuOpenGLView *view);

Free the given `view`.

`view` : | a valid VisuOpenGLView object.

### VisuOpenGLViewCopy ()

    VisuOpenGLView*     VisuOpenGLViewCopy                  (VisuOpenGLView *view);

Copy operator (newly VisuOpenGLView created with `g_malloc()` to be freed be `g_free()`).

`view` : | a valid VisuOpenGLView object.
Returns : | a newly allocated VisuOpenGLView with same values than `view`.. transfer none.

### VisuOpenGLCameraGet_numberOfFacettes ()

    gint                VisuOpenGLCameraGet_numberOfFacettes
                                                            (VisuOpenGLCamera *camera,
                                                             guint winSize,
                                                             float dimension);

This is a function to get the number of "facettes" advised by the server (according to its policy on rendering) to draw an object according to a given dimension.

`camera` : | a valid VisuOpenGLCamera object ;
`winSize` : | the size of the rendering area.
`dimension` : | the size of the object which asks for its number of facettes.
Returns : | the number of facettes the object should used.

### openGLProject ()

    void                openGLProject                       (OpenGLWindow *window,
                                                             const VisuOpenGLCamera *camera,
                                                             float extens);

This method is used to set the projection and the OpenGL viewport.

`window` : | definition of the screen.
`camera` : | position of the camera.
`extens` : | expansion of the object.

### openGLModelize ()

    void                openGLModelize                      (VisuOpenGLCamera *camera);

Set-up the orientation matrix, depending on the camera definition.

`camera` : | a VisuOpenGLCamera object.

### VisuOpenGLViewSet_precision ()

    int                 VisuOpenGLViewSet_precision         (float value);

This function change the value of the parameter precisionOfRendering. It changes the number of facettes advised for every objects. It allows to increase or decrease the number of polygons drawn and thus acts on the speed of rendering.

`value` : | a positive value (100 is normal precision).
Returns : | TRUE if the signals OpenGLFacetteChanged and OpenGLAskForReDraw should be emitted.

### VisuOpenGLViewGet_precision ()

    float               VisuOpenGLViewGet_precision         (void);

This function retrieve the value of the parameter precisionOfRendering.

Returns : | the actual precision.

### openGLViewRotate_box ()

    void                openGLViewRotate_box                (VisuOpenGLView *view,
                                                             float dTheta,
                                                             float dPhi,
                                                             float angles[2]);

This methods rotates the camera of the given `view` of (`dTheta`, `dPhi`) and put new theta and phi angles in `angles`, first being theta and second phi.

`view` : | a valid VisuOpenGLView object ;
`dTheta` : | a float value ;
`dPhi` : | a float value ;
`angles` : | a storing area two floats.. in. array fixed-size=2.

### openGLViewRotate_camera ()

    void                openGLViewRotate_camera             (VisuOpenGLView *view,
                                                             float dTheta,
                                                             float dPhi,
                                                             float angles[3]);

This methods rotates the camera of the given `view` of (`dTheta`, `dPhi`). `dTheta` is taken as displacement along camera x axis and dPhi along camera y axis. Then, computations are done to obtain new theta, phi and omega values. They are put in `angles`, first being theta, second phi and third omega.

`view` : | a valid VisuOpenGLView object ;
`dTheta` : | a float value ;
`dPhi` : | a float value ;
`angles` : | a storing area three floats.. in. array fixed-size=3.

### VisuOpenGLViewInit ()

    void                VisuOpenGLViewInit                  (void);

This method is used by V_Sim during initilization process and should not be called.