## view

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

## Synopsis

    struct      OpenGLView_struct;
    typedef     OpenGLView;
    OpenGLView* OpenGLViewNew                   ();
    OpenGLView* OpenGLViewCopy                  (OpenGLView *view);
    void        OpenGLViewFree                  (OpenGLView *view);
    float       OpenGLViewGet_fileUnitPerPixel  (OpenGLView *view);
    int         OpenGLViewGet_numberOfFacettes  (OpenGLView *view,
                                                 float dimension);
    float       OpenGLViewGet_precision         ();
    void        OpenGLViewGet_screenAxes        (OpenGLView *view,
                                                 float xAxis[3],
                                                 float yAxis[3]);
    int         OpenGLViewSet_precision         (float value);
    int         OpenGLViewSet_windowSize        (OpenGLView *view,
                                                 guint width,
                                                 guint height);
    void        openGLViewCompute_matrixAndView (OpenGLView *view);
    void        openGLViewRotate_box            (OpenGLView *view,
                                                 float dTheta,
                                                 float dPhi,
                                                 float angles[2]);
    void        openGLViewRotate_camera         (OpenGLView *view,
                                                 float dTheta,
                                                 float dPhi,
                                                 float angles[3]);
    int         openGLViewSet_XsYs              (OpenGLView *view,
                                                 float valueX,
                                                 float valueY,
                                                 int mask);
    int         openGLViewSet_gross             (OpenGLView *view,
                                                 float value);
    int         openGLViewSet_persp             (OpenGLView *view,
                                                 float value);
    int         openGLViewSet_thetaPhiOmega     (OpenGLView *view,
                                                 float valueTheta,
                                                 float valuePhi,
                                                 float valueOmega,
                                                 int mask);

    #define     MASK_THETA
    #define     MASK_PHI
    #define     MASK_OMEGA
    #define     MASK_XS
    #define     MASK_YS
    struct      OpenGLCamera_struct;
    typedef     OpenGLCamera;

    struct      OpenGLBox_struct;
    typedef     OpenGLBox;

    struct      OpenGLWindow_struct;
    typedef     OpenGLWindow;

    void        OpenGLViewInit                  ();

## Description

The OpenGLView stores three basic informations: one for the position and orientation of the camera (OpenGLCamera), 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 `OpenGLViewSet_precision()` and all V_Sim part drawing something should use `OpenGLViewGet_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 OpenGLCamera structure. They must be changed with the following methods : `openGLViewSet_thetaPhiOmega()`, `openGLViewSet_gross()`, `openGLViewSet_persp()` and `openGLViewSet_XsYs()`.

## Details

### struct OpenGLView_struct

    struct OpenGLView_struct {
      OpenGLCamera *camera;
      OpenGLWindow *window;
      OpenGLBox *box;
    };

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

OpenGLCamera *`camera`; | a OpenGLCamera structure;
OpenGLWindow *`window`; | a OpenGLWindow structure;
OpenGLBox *`box`; | a OpenGLBox structure;

### OpenGLView

    typedef struct OpenGLView_struct OpenGLView;

Short name for OpenGLView_struct structures.

### OpenGLViewNew ()

    OpenGLView* OpenGLViewNew                   ();

Create a new OpenGLView object with default values.

Returns : | the newly created object (to be free with `OpenGLViewFree()`).

### OpenGLViewCopy ()

    OpenGLView* OpenGLViewCopy                  (OpenGLView *view);

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

`view` : | a valid OpenGLView object.
Returns : | a newly allocated OpenGLView with same values than `view`.

### OpenGLViewFree ()

    void        OpenGLViewFree                  (OpenGLView *view);

Free the given `view`.

`view` : | a valid OpenGLView object.

### OpenGLViewGet_fileUnitPerPixel ()

    float       OpenGLViewGet_fileUnitPerPixel  (OpenGLView *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 OpenGLView object.
Returns : | how much of a unit of file is in a pixel.

### OpenGLViewGet_numberOfFacettes ()

    int         OpenGLViewGet_numberOfFacettes  (OpenGLView *view,
                                                 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.

`view` : | a valid OpenGLView object ;
`dimension` : | the size of the object which asks for its number of facettes.
Returns : | the number of facettes the object should used.

### OpenGLViewGet_precision ()

    float       OpenGLViewGet_precision         ();

This function retrieve the value of the parameter precisionOfRendering.

Returns : | the actual precision.

### OpenGLViewGet_screenAxes ()

    void        OpenGLViewGet_screenAxes        (OpenGLView *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 OpenGLView.
`xAxis` : | three float values representing x axis ;
`yAxis` : | three float values representing y axis.

### OpenGLViewSet_precision ()

    int         OpenGLViewSet_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.

### OpenGLViewSet_windowSize ()

    int         OpenGLViewSet_windowSize        (OpenGLView *view,
                                                 guint width,
                                                 guint height);

It changes the size of the OpenGl area and reccompute the OpenGL viewport. Warning : it doesn't change the size of the window. If the `view` is NULL, then only the OpenGl area is changed (usefull when no VisuData is available).

`view` : | a valid OpenGLView object (can be NULL);
`width` : | the new horizontal size ;
`height` : | the new vertical size.
Returns : | TRUE if the signals OpenGLWidthHeight, OpenGLFacetteChanged and OpenGLAskForReDraw should be emitted.

### openGLViewCompute_matrixAndView ()

    void        openGLViewCompute_matrixAndView (OpenGLView *view);

This method is used to set the projection and the OpenGL viewport. It's used by VisuData and should not be called elsewhere.

`view` : | a valid OpenGLView object.

### openGLViewRotate_box ()

    void        openGLViewRotate_box            (OpenGLView *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 OpenGLView object ;
`dTheta` : | a float value ;
`dPhi` : | a float value ;
`angles` : | a storing area two floats.

### openGLViewRotate_camera ()

    void        openGLViewRotate_camera         (OpenGLView *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 OpenGLView object ;
`dTheta` : | a float value ;
`dPhi` : | a float value ;
`angles` : | a storing area three floats.

### openGLViewSet_XsYs ()

    int         openGLViewSet_XsYs              (OpenGLView *view,
                                                 float valueX,
                                                 float valueY,
                                                 int mask);

Change the point where the camera is pointed to.

`view` : | a valid OpenGLView 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.

### openGLViewSet_gross ()

    int         openGLViewSet_gross             (OpenGLView *view,
                                                 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.

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

### openGLViewSet_persp ()

    int         openGLViewSet_persp             (OpenGLView *view,
                                                 float value);

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

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

### openGLViewSet_thetaPhiOmega ()

    int         openGLViewSet_thetaPhiOmega     (OpenGLView *view,
                                                 float valueTheta,
                                                 float valuePhi,
                                                 float valueOmega,
                                                 int mask);

Change the orientation of the camera to the specified angles.

`view` : | a valid OpenGLView 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_THETA

    #define MASK_THETA (1 << 1)

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

### MASK_PHI

    #define MASK_PHI   (1 << 2)

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

### MASK_OMEGA

    #define MASK_OMEGA   (1 << 3)

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

### 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.

### struct OpenGLCamera_struct

    struct OpenGLCamera_struct {
      /* Perspective. */
      double d_red;
      double gr; /* equal to d_red / (d_red - 1.) */
      /* Orientation. */
      double theta, phi, omega;
      /* Position. */
      double xs, ys;
      /* Zoom. */
      double gross;
    };

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 `gr`; | a private value equal to d_red / (d_red - 1.) ;
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.

### OpenGLCamera

    typedef struct OpenGLCamera_struct OpenGLCamera;

A short way to adress OpenGLCamera_struct objects.

### struct OpenGLBox_struct

    struct OpenGLBox_struct {
      double extens; /* makes changes in modelize, project, and numberOfFacette */

      double dxxs2, dyys2, dzzs2;
      double p1[3], p2[3], p3[3], p4[3], p5[3], p6[3], p7[3], p8[3];
    };

Values to describe the box where the render is done. These values are linked to a VisuData object (the currentVisuData pointer) and valid as long as this object is available. This should migrate to the VisuData object in future releases.

double `extens`; | not used ;
double `dxxs2`; | the square value of the norm of the x vector of the box ;
double `dyys2`; | the square value of the norm of the y vector of the box ;
double `dzzs2`; | the square value of the norm of the z vector of the box ;
double `p1`[3]; | the coordinates of the point (0,0,0) ;
double `p2`[3]; | the coordinates of the point (1,0,0) ;
double `p3`[3]; | the coordinates of the point (1,1,0) ;
double `p4`[3]; | the coordinates of the point (0,1,0) ;
double `p5`[3]; | the coordinates of the point (0,0,1) ;
double `p6`[3]; | the coordinates of the point (1,0,1) ;
double `p7`[3]; | the coordinates of the point (1,1,1) ;
double `p8`[3]; | the coordinates of the point (0,1,1).

### OpenGLBox

    typedef struct OpenGLBox_struct OpenGLBox;

A short way to identify OpenGLBox_struct object.

### struct OpenGLWindow_struct

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

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 ;

### OpenGLWindow

    typedef struct OpenGLWindow_struct OpenGLWindow;

A short way to identify OpenGLWindow_struct object.

### OpenGLViewInit ()

    void        OpenGLViewInit                  ();

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

## See Also

Usually a OpenGLView is associated to a VisuData for its rendering.