# sdl2.ext.algorithms - Useful Algorithms

This module contains some useful algorithms for working with shapes and surfaces. At present it contains functions for clipping lines to fit within a set of 2D boundaries and for determining whether a point falls along a given line.

sdl2.ext.algorithms.liangbarsky(left, top, right, bottom, x1, y1, x2, y2)

  Clips a line to a rectangular area.

  This implements the Liang-Barsky line clipping algorithm. `left`, `top`, `right` and `bottom` define the bounds of the clipping area, by which the line from `(x1, y1)` to `(x2, y2)` will be clipped.

  Parameters:

    - left (int) – The left boundary of the clipping area.

    - top (int) – The top boundary of the clipping area.

    - right (int) – The right boundary of the clipping area.

    - bottom (int) – The bottom boundary of the clipping area.

    - x1 (int) – The x-coordinate of the starting point of the line.

    - y1 (int) – The y-coordinate of the starting point of the line.

    - x2 (int) – The x-coordinate of the end point of the line.

    - y2 (int) – The y-coordinate of the end point of the line.

  Returns:

    The start and end coordinates of the clipped line in the form `(cx1, cy1, cx2, cy2)`. If the line does not intersect with the rectangular clipping area, all 4 values will be `None`.

  Return type:

    tuple

sdl2.ext.algorithms.cohensutherland(left, top, right, bottom, x1, y1, x2, y2)

  Clips a line to a rectangular area.

  This implements the Cohen-Sutherland line clipping algorithm. `left`, `top`, `right` and `bottom` define the bounds of the clipping area, by which the line from `(x1, y1)` to `(x2, y2)` will be clipped.

  Parameters:

    - left (int) – The left boundary of the clipping area.

    - top (int) – The top boundary of the clipping area.

    - right (int) – The right boundary of the clipping area.

    - bottom (int) – The bottom boundary of the clipping area.

    - x1 (int) – The x-coordinate of the starting point of the line.

    - y1 (int) – The y-coordinate of the starting point of the line.

    - x2 (int) – The x-coordinate of the end point of the line.

    - y2 (int) – The y-coordinate of the end point of the line.

  Returns:

    The start and end coordinates of the clipped line in the form `(cx1, cy1, cx2, cy2)`. If the line does not intersect with the rectangular clipping area, all 4 values will be `None`.

  Return type:

    tuple

sdl2.ext.algorithms.clipline(l, t, r, b, x1, y1, x2, y2, method='liangbarsky')

  Clips a line to a rectangular area using a given method.

  Parameters:

    - l (int) – The left boundary of the clipping area.

    - t (int) – The top boundary of the clipping area.

    - r (int) – The right boundary of the clipping area.

    - b (int) – The bottom boundary of the clipping area.

    - x1 (int) – The x-coordinate of the starting point of the line.

    - y1 (int) – The y-coordinate of the starting point of the line.

    - x2 (int) – The x-coordinate of the end point of the line.

    - y2 (int) – The y-coordinate of the end point of the line.

    - method (str, optional) – The method to use for clipping lines, can be either ‘cohensutherland’ or ‘liangbarsky’. Defaults to liangbarsky.

  Returns:

    The start and end coordinates of the clipped line in the form `(cx1, cy1, cx2, cy2)`. If the line does not intersect with the rectangular clipping area, all 4 values will be `None`.

  Return type:

    tuple

sdl2.ext.algorithms.point_on_line(p1, p2, point)

  Checks if a point falls along a given line segment.

  Parameters:

    - p1 (tuple) – The (x, y) coordinates of the starting point of the line.

    - p2 (tuple) – The (x, y) coordinates of the end point of the line.

    - point (tuple) – The (x, y) coordinates to test against the line.

  Returns:

    `True` if the point falls along the line segment, otherwise `False`.

  Return type:

    bool