Point3D: Graphene Reference Manual

## Point3D Point3D — A point with 3 coordinates |

## Functions

#define | GRAPHENE_POINT3D_INIT()
graphene_point3d_t * | graphene_point3d_alloc ()
void | graphene_point3d_free ()
graphene_point3d_t * | graphene_point3d_init ()
graphene_point3d_t * | graphene_point3d_init_from_point ()
graphene_point3d_t * | graphene_point3d_init_from_vec3 ()
void | graphene_point3d_to_vec3 ()
bool | graphene_point3d_equal ()
bool | graphene_point3d_near ()
void | graphene_point3d_scale ()
void | graphene_point3d_cross ()
float | graphene_point3d_dot ()
float | graphene_point3d_length ()
void | graphene_point3d_normalize ()
void | graphene_point3d_normalize_viewport ()
float | graphene_point3d_distance ()
void | graphene_point3d_interpolate ()
const graphene_point3d_t * | graphene_point3d_zero ()

## Types and Values

#define | GRAPHENE_POINT3D_INIT_ZERO
| graphene_point3d_t

## Includes

    #include <graphene-gobject.h>

## Description

graphene_point3d_t is a data structure capable of describing a point with three coordinates:

- `graphene_point3d_t.x`

- `graphene_point3d_t.y`

- `graphene_point3d_t.z`

## Functions

### GRAPHENE_POINT3D_INIT()

    #define GRAPHENE_POINT3D_INIT(_x,_y,_z) (graphene_point3d_t) { .x = (_x), .y = (_y), .z = (_z) }

Initializes a graphene_point3d_t to the given coordinates when declaring it.

#### Parameters

_x | the X coordinate |
_y | the Y coordinate |
_z | the Z coordinate |

Since: 1.0

### graphene_point3d_alloc ()

    graphene_point3d_t *
    graphene_point3d_alloc (void);

Allocates a graphene_point3d_t structure.

[constructor]

#### Returns

the newly allocated structure. Use `graphene_point3d_free()` to free the resources allocated by this function.

[transfer full]

Since: 1.0

### graphene_point3d_free ()

    void
    graphene_point3d_free (graphene_point3d_t *p);

Frees the resources allocated via `graphene_point3d_alloc()`.

#### Parameters

p | a graphene_point3d_t |

Since: 1.0

### graphene_point3d_init ()

    graphene_point3d_t *
    graphene_point3d_init (graphene_point3d_t *p,
                           float x,
                           float y,
                           float z);

Initializes a graphene_point3d_t with the given coordinates.

#### Parameters

p | the graphene_point3d_t to initialize |
x | the X coordinate of the point |
y | the Y coordinate of the point |
z | the Z coordinate of the point |

#### Returns

the initialized graphene_point3d_t.

[transfer none]

Since: 1.0

### graphene_point3d_init_from_point ()

    graphene_point3d_t *
    graphene_point3d_init_from_point (graphene_point3d_t *p,
                                      const graphene_point3d_t *src);

Initializes a graphene_point3d_t using the coordinates of another graphene_point3d_t.

#### Parameters

p | a graphene_point3d_t |
src | a graphene_point3d_t |

#### Returns

the initialized point.

[transfer none]

Since: 1.0

### graphene_point3d_init_from_vec3 ()

    graphene_point3d_t *
    graphene_point3d_init_from_vec3 (graphene_point3d_t *p,
                                     const graphene_vec3_t *v);

Initializes a graphene_point3d_t using the components of a graphene_vec3_t.

#### Parameters

p | a graphene_point3d_t |
v | a graphene_vec3_t |

#### Returns

the initialized graphene_point3d_t.

[transfer none]

Since: 1.0

### graphene_point3d_to_vec3 ()

    void
    graphene_point3d_to_vec3 (const graphene_point3d_t *p,
                              graphene_vec3_t *v);

Stores the coordinates of a graphene_point3d_t into a graphene_vec3_t.

#### Parameters

p | a graphene_point3d_t |
v | return location for a graphene_vec3_t. | [out caller-allocates]

Since: 1.0

### graphene_point3d_equal ()

    bool
    graphene_point3d_equal (const graphene_point3d_t *a,
                            const graphene_point3d_t *b);

Checks whether two given points are equal.

#### Parameters

a | a graphene_point3d_t |
b | a graphene_point3d_t |

#### Returns

`true` if the points are equal

Since: 1.0

### graphene_point3d_near ()

    bool
    graphene_point3d_near (const graphene_point3d_t *a,
                           const graphene_point3d_t *b,
                           float epsilon);

Checks whether the two points are near each other, within an `epsilon` factor.

#### Parameters

a | a graphene_point3d_t |
b | a graphene_point3d_t |
epsilon | fuzzyness factor |

#### Returns

`true` if the points are near each other

Since: 1.0

### graphene_point3d_scale ()

    void
    graphene_point3d_scale (const graphene_point3d_t *p,
                            float factor,
                            graphene_point3d_t *res);

Scales the coordinates of the given graphene_point3d_t by the given `factor` .

#### Parameters

p | a graphene_point3d_t |
factor | the scaling factor |
res | return location for the scaled point. | [out caller-allocates]

Since: 1.0

### graphene_point3d_cross ()

    void
    graphene_point3d_cross (const graphene_point3d_t *a,
                            const graphene_point3d_t *b,
                            graphene_point3d_t *res);

Computes the cross product of the two given graphene_point3d_t.

#### Parameters

a | a graphene_point3d_t |
b | a graphene_point3d_t |
res | return location for the cross product. | [out caller-allocates]

Since: 1.0

### graphene_point3d_dot ()

    float
    graphene_point3d_dot (const graphene_point3d_t *a,
                          const graphene_point3d_t *b);

Computes the dot product of the two given graphene_point3d_t.

#### Parameters

a | a graphene_point3d_t |
b | a graphene_point3d_t |

#### Returns

the value of the dot product

Since: 1.0

### graphene_point3d_length ()

    float
    graphene_point3d_length (const graphene_point3d_t *p);

Computes the length of the vector represented by the coordinates of the given graphene_point3d_t.

#### Parameters

p | a graphene_point3d_t |

#### Returns

the length of the vector represented by the point

Since: 1.0

### graphene_point3d_normalize ()

    void
    graphene_point3d_normalize (const graphene_point3d_t *p,
                                graphene_point3d_t *res);

Computes the normalization of the vector represented by the coordinates of the given graphene_point3d_t.

#### Parameters

p | a graphene_point3d_t |
res | return location for the normalized graphene_point3d_t. | [out caller-allocates]

Since: 1.0

### graphene_point3d_normalize_viewport ()

    void
    graphene_point3d_normalize_viewport (const graphene_point3d_t *p,
                                         const graphene_rect_t *viewport,
                                         float z_near,
                                         float z_far,
                                         graphene_point3d_t *res);

Normalizes the coordinates of a graphene_point3d_t using the given viewport and clipping planes.

The coordinates of the resulting graphene_point3d_t will be in the [ -1, 1 ] range.

#### Parameters

p | a graphene_point3d_t |
viewport | a graphene_rect_t representing a viewport |
z_near | the coordinate of the near clipping plane, or 0 for the default near clipping plane |
z_far | the coordinate of the far clipping plane, or 1 for the default far clipping plane |
res | the return location for the normalized graphene_point3d_t. | [out caller-allocates]

Since: 1.4

### graphene_point3d_distance ()

    float
    graphene_point3d_distance (const graphene_point3d_t *a,
                               const graphene_point3d_t *b,
                               graphene_vec3_t *delta);

Computes the distance between the two given graphene_point3d_t.

#### Parameters

a | a graphene_point3d_t |
b | a graphene_point3d_t |
delta | return location for the distance components on the X, Y, and Z axis. | [out caller-allocates][optional]

#### Returns

the distance between two points

Since: 1.4

### graphene_point3d_interpolate ()

    void
    graphene_point3d_interpolate (const graphene_point3d_t *a,
                                  const graphene_point3d_t *b,
                                  double factor,
                                  graphene_point3d_t *res);

Linearly interpolates each component of `a` and `b` using the provided `factor` , and places the result in `res` .

#### Parameters

a | a graphene_point3d_t |
b | a graphene_point3d_t |
factor | the interpolation factor |
res | the return location for the interpolated graphene_point3d_t. | [out caller-allocates]

Since: 1.0

### graphene_point3d_zero ()

    const graphene_point3d_t *
    graphene_point3d_zero (void);

Retrieves a constant point with all three coordinates set to 0.

#### Returns

a zero point.

[transfer none]

Since: 1.0

## Types and Values

### GRAPHENE_POINT3D_INIT_ZERO

    #define GRAPHENE_POINT3D_INIT_ZERO      GRAPHENE_POINT3D_INIT (0.f, 0.f, 0.f)

Initializes a graphene_point3d_t to (0, 0, 0) when declaring it.

Since: 1.0

### graphene_point3d_t

    typedef struct {
      float x;
      float y;
      float z;
    } graphene_point3d_t;

A point with three components: X, Y, and Z.

#### Members

float `x`; | the X coordinate |
float `y`; | the Y coordinate |
float `z`; | the Z coordinate |

Since: 1.0