## renderingAtomic

renderingAtomic — A rendering method to draw atoms positioned in a box.

## Synopsis

    enum                renderingAtomic_shapeId;

    float               renderingAtomicGet_radius           (VisuElement *ele);
    int                 renderingAtomicSet_radius           (VisuElement *ele,
                                                             float value);
    float               renderingAtomicGet_radiusDefault    ();
    gboolean            renderingAtomicSet_elipsoidParameters
                                                            (VisuElement *ele,
                                                             float ratio,
                                                             float phi,
                                                             float theta);
    float               renderingAtomicGet_elipsoidPhi      (VisuElement *ele);
    gboolean            renderingAtomicSet_elipsoidPhi      (VisuElement *ele,
                                                             float phi);
    float               renderingAtomicGet_elipsoidTheta    (VisuElement *ele);
    gboolean            renderingAtomicSet_elipsoidTheta    (VisuElement *ele,
                                                             float theta);
    float               renderingAtomicGet_elipsoidRatio    (VisuElement *ele);
    gboolean            renderingAtomicSet_elipsoidRatio    (VisuElement *ele,
                                                             float ratio);

    int                 renderingAtomicSet_shape            (VisuElement *ele,
                                                             int shape);
    int                 renderingAtomicGet_shape            (VisuElement *ele);
    int                 renderingAtomicSet_shapeFromName    (VisuElement *ele,
                                                             char *shape);
    const char*         renderingAtomicGet_shapeName        (int shape);
    int                 renderingAtomicGet_shapeDefault     ();
    const char*         renderingAtomicGet_shapeNameDefault ();
    const char**        renderingAtomicGet_allShapes        ();
    const char**        renderingAtomicGet_allShapesI18n    ();

    gboolean            renderingAtomicLoad                 (VisuData *data,
                                                             FileFormat *format,
                                                             int nSet,
                                                             GError **error);
    void                renderingAtomicAdd_loadMethod       (RenderingFormatLoad *meth);

    RenderingMethod*    initAtomic                          ();
    int                 renderingAtomic_createShape         (VisuData *visuData,
                                                             VisuElement *ele);
    void                renderingAtomic_positionShape       (VisuData *visuData,
                                                             VisuNode *node,
                                                             VisuElement *ele);

## Description

This the main part of a rendering method made to represent atomic positions. It draws either spheres or cubes depending of the elements properties. The radius (for the sphere) or the length of the sides of the cubes can be tuned.

## Details

### enum renderingAtomic_shapeId

    typedef enum
      {
        shapeSphere,
        shapeCube,
        shapeElipsoid,
        shapePoint,
        nbAtomicShapes
      } renderingAtomic_shapeId;

This enum is used as identifier for shapes managed by the attomic rendering method.

`shapeSphere` | draw sphere ;
`shapeCube` | draw cube ;
`shapeElipsoid` | draw elipsoid ;
`shapePoint` | draw square dot ;
`nbAtomicShapes` | number of shapes.

### renderingAtomicGet_radius ()

    float               renderingAtomicGet_radius           (VisuElement *ele);

In the rendering atomic method, shapes are characterized by a radius. This method gets it for the specified element. If this element has no radius defined yet, the default value is associated and returned.

`ele` : | a VisuElement object.
Returns : | the radius of the specified element. A negative value if something goies wrong.

### renderingAtomicSet_radius ()

    int                 renderingAtomicSet_radius           (VisuElement *ele,
                                                             float value);

This change the radius value of element `ele` to `value`.

`ele` : | a VisuElement object ;
`value` : | a positive floating point value.
Returns : | 1 if a call to `renderingAtomic_createShape()` is required, 0 if not.

### renderingAtomicGet_radiusDefault ()

    float               renderingAtomicGet_radiusDefault    ();

This method gets the default radius of the rendering atomic method.

Returns : | the default value for radius resource.

### renderingAtomicSet_elipsoidParameters ()

    gboolean            renderingAtomicSet_elipsoidParameters
                                                            (VisuElement *ele,
                                                             float ratio,
                                                             float phi,
                                                             float theta);

Change the parameters for the elipsoid shape for the given `ele`. These parameters include a `ratio` which is the ratio of the long axis on the short one. Thus `ratio` is always equal or greater than 1. Arguments `theta` and `phi` are the direction of the long axis.

`ele` : | a VisuElement object ;
`ratio` : | a float ;
`phi` : | a float ;
`theta` : | a float.
Returns : | TRUE if `renderingAtomic_createShape()` should be called.

### renderingAtomicGet_elipsoidPhi ()

    float               renderingAtomicGet_elipsoidPhi      (VisuElement *ele);

Retrieve the phi angle parameter of the elipsoid shape for the element `ele`.

`ele` : | a VisuElement object.
Returns : | the phi angle of the elipsoid.

### renderingAtomicSet_elipsoidPhi ()

    gboolean            renderingAtomicSet_elipsoidPhi      (VisuElement *ele,
                                                             float phi);

Set the phi angle parameter of the elipsoid shape for the element `ele`.

`ele` : | a VisuElement object.
`phi` : | a float ;
Returns : | TRUE if `renderingAtomic_createShape()` should be called.

### renderingAtomicGet_elipsoidTheta ()

    float               renderingAtomicGet_elipsoidTheta    (VisuElement *ele);

Retrieve the theta angle parameter of the elipsoid shape for the element `ele`.

`ele` : | a VisuElement object.
Returns : | the theta angle of the elipsoid.

### renderingAtomicSet_elipsoidTheta ()

    gboolean            renderingAtomicSet_elipsoidTheta    (VisuElement *ele,
                                                             float theta);

Set the theta angle parameter of the elipsoid shape for the element `ele`.

`ele` : | a VisuElement object.
`theta` : | a float.
Returns : | TRUE if `renderingAtomic_createShape()` should be called.

### renderingAtomicGet_elipsoidRatio ()

    float               renderingAtomicGet_elipsoidRatio    (VisuElement *ele);

Retrieve the ratio parameter of the elipsoid shape for the element `ele`.

`ele` : | a VisuElement object.
Returns : | the ratio of the elipsoid.

### renderingAtomicSet_elipsoidRatio ()

    gboolean            renderingAtomicSet_elipsoidRatio    (VisuElement *ele,
                                                             float ratio);

Set the ratio parameter of the elipsoid shape for the element `ele`.

`ele` : | a VisuElement object.
`ratio` : | a float ;
Returns : | TRUE if `renderingAtomic_createShape()` should be called.

### renderingAtomicSet_shape ()

    int                 renderingAtomicSet_shape            (VisuElement *ele,
                                                             int shape);

This changes the shape of the element `ele` to the shape defined by its id.

`ele` : | a VisuElement object ;
`shape` : | an integer.
Returns : | 1 if a call to `renderingAtomic_createShape()` is required, 0 if not.

### renderingAtomicGet_shape ()

    int                 renderingAtomicGet_shape            (VisuElement *ele);

In the rendering atomic method, shapes are multiple. This method gets it for the specified element. Shapes are characterized by their id, corresponding to an integer value. Use the enum renderingAtomic_shapeId to associate an integer value to a specific shape.

`ele` : | a VisuElement object.
Returns : | the shape id of the element `ele`.

### renderingAtomicSet_shapeFromName ()

    int                 renderingAtomicSet_shapeFromName    (VisuElement *ele,
                                                             char *shape);

This method is equivalent to `renderingAtomicSet_shape()` but the shape is defined by its name.

`ele` : | a VisuElement object ;
`shape` : | a string.
Returns : | 1 if a call to `renderingAtomic_createShape()` is required, 0 if not.

### renderingAtomicGet_shapeName ()

    const char*         renderingAtomicGet_shapeName        (int shape);

This method does the corresponding between a shape id and its name (a string value).

`shape` : | an integer.
Returns : | the name associated to a shape.

### renderingAtomicGet_shapeDefault ()

    int                 renderingAtomicGet_shapeDefault     ();

This method gets the default shape.

Returns : | the default shape id.

### renderingAtomicGet_shapeNameDefault ()

    const char*         renderingAtomicGet_shapeNameDefault ();

This method is used to retrieve the default name for shapes.

Returns : | the name associated to the default shape.

### renderingAtomicGet_allShapes ()

    const char**        renderingAtomicGet_allShapes        ();

This methods retrieve the whole list of shape names used by V_Sim for example in the resources file. These names are not translated. If internationalized names are required, use `renderingAtomicGet_allShapesI18n()` instead.

Returns : | a pointer to a list of shape names (should not be modified or freed).

### renderingAtomicGet_allShapesI18n ()

    const char**        renderingAtomicGet_allShapesI18n    ();

This methods retrieve the whole list of shape names, translated strings.

Returns : | a pointer to a list of shape names (should not be modified or freed).

### renderingAtomicLoad ()

    gboolean            renderingAtomicLoad                 (VisuData *data,
                                                             FileFormat *format,
                                                             int nSet,
                                                             GError **error);

Try to load the file declared in the `data`. It tries all formats added with `renderingAtomicAdd_loadMethod()`. The `nSet` argument is used to load a specific set of nodes if the input format supports it. If `nSet` is 0, then the default set of nodes is loaded.

`data` : | a VisuData object ;
`format` : | a pointer on a format (can be NULL if format is to be guessed) ;
`nSet` : | an integer ;
`error` : | a pointer to store a possible error.
Returns : | FALSE if the file can't be loaded.

### renderingAtomicAdd_loadMethod ()

    void                renderingAtomicAdd_loadMethod       (RenderingFormatLoad *meth);

This routine is used to register a new load method with its description (file formats, name...). The list of all known load methods is automatically resorted after a call to this method to reflect the priorities.

`meth` : | a new load method.

### initAtomic ()

    RenderingMethod*    initAtomic                          ();

Create the structure and initialise its values.

Returns : | a newly allocated rendering method.

### renderingAtomic_createShape ()

    int                 renderingAtomic_createShape         (VisuData *visuData,
                                                             VisuElement *ele);

This function is used to create the OpenGL objects that correspond to the `ele` VisuElement in the atomic rendering method. It creates an OpenGL list whose number is stored internaly and returned. For the atomic method, elements are represented by spheres and similar shapes.

`visuData` : | a VisuData object ;
`ele` : | a visu element.
Returns : | an id representing an OpenGL list where the shape has been created.

### renderingAtomic_positionShape ()

    void                renderingAtomic_positionShape       (VisuData *visuData,
                                                             VisuNode *node,
                                                             VisuElement *ele);

This method translates the given node to the right position. The `ele` parameter is the VisuElement of the given node.

`visuData` : | a VisuData object ;
`node` : | a VisuNode object ;
`ele` : | a VisuElement.