Added geometry.Line base (#3131)

* Added a first implementation of the geometry.Line class.

Co-authored-by: Emc2356 <[email protected]>
Co-authored-by: NovialRiptide <[email protected]>
Co-authored-by: ScriptLineStudios <[email protected]>
Co-authored-by: Avaxar <[email protected]>
Co-authored-by: maqa41 <[email protected]>

* fixed geometry.pyi a bit, removed redundant tuple specification as covered by SequenceLike.

* more fixes and added FRect to _CanBeLine.

* last .pyi fixes.

* removed some unused/duplicate defines.

* Fix merge errors

* Now accepting degenerate lines, added some more __init__ tests.

* Move pgLine_FromObject to geometry_common to conform with circle.

* Now using PySequence_ITEM in pgLine_FromObject.

* remove doc about not accepting degenerate lines

* Renamed (xa, ya, xb, yb) -> (ax, ay, bx, by).
Removed Rect/Frect from canbeline stub.
Added some more info about passing a Rect/Frect to construct a Line and about degenerate lines potentially making some methods not work.

---------

Co-authored-by: Emc2356 <[email protected]>
Co-authored-by: NovialRiptide <[email protected]>
Co-authored-by: ScriptLineStudios <[email protected]>
Co-authored-by: Avaxar <[email protected]>
Co-authored-by: maqa41 <[email protected]>
Co-authored-by: Dan Lawrence <[email protected]>

Author: 7 people

buildconfig/stubs/pygame/geometry.pyi

@@ -13,13 +13,27 @@ from pygame.typing import Point, RectLike, SequenceLike
 from .math import Vector2
 
 _CanBeCircle = Union[Circle, Tuple[Point, float], SequenceLike[float]]
+_CanBeLine = Union[
+    Line,
+    SequenceLike[float],
+    SequenceLike[Point],
+]
 
 class _HasCirclettribute(Protocol):
     # An object that has a circle attribute that is either a circle, or a function
     # that returns a circle
     circle: Union[_CanBeCircle, Callable[[], _CanBeCircle]]
 
 _CircleValue = Union[_CanBeCircle, _HasCirclettribute]
+
+class _HasLineAttribute(Protocol):
+    # An object that has a line attribute that is either a line, or a function
+    # that returns a line
+    line: Union[_CanBeLine, Callable[[], _CanBeLine]]
+
+
+_LineValue = Union[_CanBeLine, _HasLineAttribute]
+
 _CanBeCollided = Union[Circle, Rect, FRect, Point, Vector2]
 _CanBeIntersected = Union[Circle]
 
@@ -133,3 +147,37 @@ class Circle:
     def as_frect(self) -> FRect: ...
     def copy(self) -> Circle: ...
     def __copy__(self) -> Circle: ...
+
+class Line:
+    @property
+    def ax(self) -> float: ...
+    @ax.setter
+    def ax(self, value: float) -> None: ...
+    @property
+    def ay(self) -> float: ...
+    @ay.setter
+    def ay(self, value: float) -> None: ...
+    @property
+    def bx(self) -> float: ...
+    @bx.setter
+    def bx(self, value: float) -> None: ...
+    @property
+    def by(self) -> float: ...
+    @by.setter
+    def by(self, value: float) -> None: ...
+    @property
+    def a(self) -> Tuple[float, float]: ...
+    @a.setter
+    def a(self, value: Point) -> None: ...
+    @property
+    def b(self) -> Tuple[float, float]: ...
+    @b.setter
+    def b(self, value: Point) -> None: ...
+    @overload
+    def __init__(self, ax: float, ay: float, bx: float, by: float) -> None: ...
+    @overload
+    def __init__(self, a: Point, b: Point) -> None: ...
+    @overload
+    def __init__(self, line: _LineValue) -> None: ...
+    def __copy__(self) -> Line: ...
+    def copy(self) -> Line: ...

docs/reST/ref/geometry.rst

@@ -487,3 +487,127 @@
          .. ## Circle.copy ##
 
    .. ## pygame.Circle ##
+
+
+.. class:: Line
+
+   | :sl:`pygame object for representing a line`
+   | :sg:`Line((ax, ay), (bx, by)) -> Line`
+   | :sg:`Line(ax, ay, bx, by) -> Line`
+
+   .. versionadded:: 2.5.2
+
+   The `Line` class provides many useful methods for collision testing, transformation and intersection.
+   A `Line` can be created from a combination of two pairs of coordinates that represent the start and end points.
+   Lines can also be created from python objects that are already a `Line` (effectively copying the line) or have an attribute named "line".
+
+   Specifically, to construct a `Line` you can pass the ax, ay, bx, and by values as separate
+   arguments or inside a sequence(list or tuple).
+
+   As a special case you can also pass in `pygame.Rect` / `pygame.FRect`, in which case the
+   line will be created with (x, y, width, height) as the start and end points.
+
+   You can create lines with the same start and end points, but beware that some methods may
+   not work as expected or error out.
+
+   Functions that require a `Line` argument may also accept these values as Lines:
+
+   ::
+
+      ((ax, ay), (bx, by))
+      (ax, ay, bx, by)
+      (vector2, vector2)
+
+   The `Line` class only stores the ax, ay, bx, and by attributes, everything else is calculated
+   on the fly based on them.
+
+   **Line Attributes**
+
+   ----
+
+   .. attribute:: ax
+
+         | :sl:`x coordinate of the start point of the line`
+         | :sg:`ax -> float`
+
+         The horizontal coordinate of the start point of the line. Reassigning it moves the line.
+
+         .. versionadded:: 2.5.2
+
+         .. ## Line.ax ##
+
+   .. attribute:: ay
+
+         | :sl:`y coordinate of the start point of the line`
+         | :sg:`ay -> float`
+
+         The vertical coordinate of the start point of the line. Reassigning it moves the line.
+
+         .. versionadded:: 2.5.2
+
+         .. ## Line.ay ##
+
+   .. attribute:: bx
+
+         | :sl:`x coordinate of the end point of the line`
+         | :sg:`bx -> float`
+
+         The horizontal coordinate of the end point of the line. Reassigning it moves the line.
+
+         .. versionadded:: 2.5.2
+
+         .. ## Line.bx ##
+
+   .. attribute:: by
+
+         | :sl:`y coordinate of the end point of the line`
+         | :sg:`by -> float`
+
+         The vertical coordinate of the end point of the line. Reassigning it moves the line.
+
+         .. versionadded:: 2.5.2
+
+         .. ## Line.by ##
+
+   .. attribute:: a
+
+         | :sl:`the first point of the line`
+         | :sg:`a -> (float, float)`
+
+         It's a tuple containing the `ax` and `ay` attributes representing the line's first point.
+         It can be reassigned to move the `Line`. If reassigned the `ax` and `ay` attributes
+         will be changed to produce a `Line` with matching first point position.
+         The `bx` and `by` attributes will not be affected.
+
+         .. versionadded:: 2.5.2
+
+         .. ## Line.a ##
+
+   .. attribute:: b
+
+         | :sl:`the second point of the line`
+         | :sg:`b -> (float, float)`
+
+         It's a tuple containing `bx` and `by` attributes representing the line's second point.
+         It can be reassigned to move the `Line`. If reassigned the `bx` and `by` attributes
+         will be changed to produce a `Line` with matching second point position.
+         The `ax` and `ay` attributes will not be affected.
+
+         .. versionadded:: 2.5.2
+
+         .. ## Line.b ##
+
+   **Line Methods**
+
+   ----
+
+   .. method:: copy
+
+         | :sl:`copies the line`
+         | :sg:`copy() -> Line`
+
+         Returns a copy of this `Line`.
+
+         .. versionadded:: 2.5.2
+
+         .. ## Line.copy ##

src_c/_pygame.h

@@ -540,6 +540,6 @@ typedef enum {
 #define PYGAMEAPI_BASE_NUMSLOTS 29
 #define PYGAMEAPI_EVENT_NUMSLOTS 10
 #define PYGAMEAPI_WINDOW_NUMSLOTS 1
-#define PYGAMEAPI_GEOMETRY_NUMSLOTS 1
+#define PYGAMEAPI_GEOMETRY_NUMSLOTS 2
 
 #endif /* _PYGAME_INTERNAL_H */

src_c/doc/geometry_doc.h

@@ -29,3 +29,11 @@
 #define DOC_CIRCLE_ASRECT "as_rect() -> Rect\nreturns the smallest Rect containing the circle"
 #define DOC_CIRCLE_ASFRECT "as_frect() -> FRect\nreturns the smallest FRect containing the circle"
 #define DOC_CIRCLE_COPY "copy() -> Circle\ncopies the circle"
+#define DOC_LINE "Line((ax, ay), (bx, by)) -> Line\nLine(ax, ay, bx, by) -> Line\npygame object for representing a line"
+#define DOC_LINE_AX "ax -> float\nx coordinate of the start point of the line"
+#define DOC_LINE_AY "ay -> float\ny coordinate of the start point of the line"
+#define DOC_LINE_BX "bx -> float\nx coordinate of the end point of the line"
+#define DOC_LINE_BY "by -> float\ny coordinate of the end point of the line"
+#define DOC_LINE_A "a -> (float, float)\nthe first point of the line"
+#define DOC_LINE_B "b -> (float, float)\nthe second point of the line"
+#define DOC_LINE_COPY "copy() -> Line\ncopies the line"

src_c/geometry.c

@@ -1,4 +1,5 @@
 #include "circle.c"
+#include "line.c"
 #include "geometry_common.c"
 
 static PyMethodDef geometry_methods[] = {{NULL, NULL, 0, NULL}};
@@ -30,6 +31,10 @@ MODINIT_DEFINE(geometry)
         return NULL;
     }
 
+    if (PyType_Ready(&pgLine_Type) < 0) {
+        return NULL;
+    }
+
     module = PyModule_Create(&_module);
     if (!module) {
         return NULL;
@@ -42,7 +47,15 @@ MODINIT_DEFINE(geometry)
         return NULL;
     }
 
+    Py_INCREF(&pgLine_Type);
+    if (PyModule_AddObject(module, "Line", (PyObject *)&pgLine_Type)) {
+        Py_DECREF(&pgLine_Type);
+        Py_DECREF(module);
+        return NULL;
+    }
+
     c_api[0] = &pgCircle_Type;
+    c_api[1] = &pgLine_Type;
     apiobj = encapsulate_api(c_api, "geometry");
     if (PyModule_AddObject(module, PYGAMEAPI_LOCAL_ENTRY, apiobj)) {
         Py_XDECREF(apiobj);

src_c/geometry.h

@@ -16,12 +16,25 @@ typedef struct {
 
 #define pgCircle_CAST(o) ((pgCircleObject *)(o))
 #define pgCircle_AsCircle(o) (pgCircle_CAST(o)->circle)
-#define pgCircle_GETX(self) (pgCircle_CAST(self)->circle.x)
-#define pgCircle_GETY(self) (pgCircle_CAST(self)->circle.y)
-#define pgCircle_GETR(self) (pgCircle_CAST(self)->circle.r)
 #define pgCircle_Check(o) ((o)->ob_type == &pgCircle_Type)
 
+typedef struct {
+    double ax, ay;
+    double bx, by;
+} pgLineBase;
+
+typedef struct {
+    PyObject_HEAD pgLineBase line;
+    PyObject *weakreflist;
+} pgLineObject;
+
+#define pgLine_CAST(o) ((pgLineObject *)(o))
+#define pgLine_AsLine(o) (pgLine_CAST(o)->line)
+#define pgLine_Check(o) ((o)->ob_type == &pgLine_Type)
+
 static PyTypeObject pgCircle_Type;
+static PyTypeObject pgLine_Type;
+
 /* Constants */
 
 /* PI */