## 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);
    void                openGLViewGet_boxSpan               (OpenGLView *view,
                                                             float span[2]);
    void                openGLViewGet_boxVertices           (OpenGLView *view,
                                                             float vertices[8][3],
                                                             gboolean withExtension);
    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]);
    void                openGLViewSet_box                   (OpenGLView *view,
                                                             float basisSet[6],
                                                             float extension[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);
    gboolean            openGLViewSet_refLength             (OpenGLView *view,
                                                             float length);

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

    typedef             OpenGLBox;

    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;

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

### 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_boxSpan ()

    void                openGLViewGet_boxSpan               (OpenGLView *view,
                                                             float span[2]);

Compute the two most far distance from origin in the box. The first is the negative one and the second, the positive one.

`view` : | an OpenGLView object with an allocated `box` attribute ;
`span` : | a location to store two floats.

### openGLViewGet_boxVertices ()

    void                openGLViewGet_boxVertices           (OpenGLView *view,
                                                             float vertices[8][3],
                                                             gboolean withExtension);

Return the vertices coordinates of the box of the `view`, for the primitive cell if `withExtension` is FALSE or for the current extension if TRUE.

`view` : | an OpenGLView object with an allocated `box` attribute ;
`vertices` : | a location to store the vertice coordinates ;
`withExtension` : | a boolean.

### 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 ;
`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_box ()

    void                openGLViewSet_box                   (OpenGLView *view,
                                                             float basisSet[6],
                                                             float extension[3]);

Compute the coordinates of the box vertex built on the basis-set axis. The size of the overall view is computed using the longest length in the box using the extension. If this extension is null, then the smallest box built on the basis-set is used, whereas if the extension is not null, then it means a double extension of the basis-set axis in each direction.

`view` : | an OpenGLView object with an allocated `box` attribute ;
`basisSet` : | the basis-set in reduced form (see visu_data.h) ;
`extension` : | the (x,y,z) extension in box coordinates.

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

### openGLViewSet_refLength ()

    gboolean            openGLViewSet_refLength             (OpenGLView *view,
                                                             float length);

Change the reference length. If `length` is null or negative, the reference length is automatically computed using the box (without duplication).

`view` : | a valid OpenGLView object ;
`length` : | a floating point value.
Returns : | TRUE if `openGLViewCompute_matrixAndView()` should be called after.

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

### OpenGLCamera

    typedef struct OpenGLCamera_struct OpenGLCamera;

A short way to adress OpenGLCamera_struct objects.

### OpenGLBox

    typedef struct OpenGLBox_struct OpenGLBox;

A short way to identify OpenGLBox_struct object.

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