geometry module, Circle base

[itzpr3d4t0r]

Follows #2267.
This PR aims to start the port with the geometry module base and a basic Circle implementation, comprehensive of (see credits below):

• Circle object instantiation
• Circle x, y, r attributes
• copy() function
• repr/str functionality

The PR also adds two new functions for getting double values from python objects that are (see credits below):

• pg_DoubleFromObj
• pg_TwoDoublesFromObj

The addition of these two functions is critical as all shapes will be using doubles as values.

typestubs, docs and tests were also added (see credits below).

Note: Extra changes to adapt to pygame-ce's codebase are all authored by me. I also took the liberty to remove a couple of old/meaningless C comments that are still there in the original codebase, rename a macro originally named by @Emc2356 to make it clearer and slightly modified docs sections since they wouldn't work with sphinx rules anyway (docs all authored by me already)

The module will be in experimental mode for quite a while, and docs reflect that:

You can search for geometry and find it but it won't appear anywhere on the main page.

Credits

Geometry Project:
For code, docs and tests:
@novialriptide @Emc2356 @itzpr3d4t0r @ScriptLineStudios @avaxar @Matiiss @newpaxonian @maqa41 @blankRiot96
Also thanks to @Starbuck5 for kickstarting the idea and the occasional help!

Functionality added in this PR

• geometry.pyi
  https://github.com/pygame-community/pygame-geometry/blame/main/geometry.pyi
  Credits to @Emc2356 @itzpr3d4t0r @novialriptide @ScriptLineStudios @avaxar

• geometry.rst
  https://github.com/pygame-community/pygame-geometry/blame/main/docs/circle.rst
  Credits to @itzpr3d4t0r

• base.c
  https://github.com/pygame-community/pygame-geometry/blame/main/src_c/include/base.h
  Credits to @Emc2356 @itzpr3d4t0r

• circle.c
  https://github.com/pygame-community/pygame-geometry/blame/main/src_c/circle.c
  Credits to @Emc2356 @itzpr3d4t0r @novialriptide

• geometry.h
  https://github.com/pygame-community/pygame-geometry/blame/main/src_c/include/geometry.h
  Credits to @Emc2356 @itzpr3d4t0r @maqa41

• geometry_test.py
  https://github.com/pygame-community/pygame-geometry/blame/main/test/test_circle.py
  Credits to @itzpr3d4t0r @novialriptide

[Starbuck5]

I don't think should be added so prominently to the mainpage, at least right now.

[Starbuck5]

This is not resolved.

[Starbuck5]

If radius is less than 0 wouldn't this return error without setting an error?

[Starbuck5]

Also is radius 0 allowed or not? The docs say less than zero, the code says zero or less. IMO zero radius should be allowed to get a scuffed vector (because people might make a shrinking circle and it would be nice to just go to zero)

[itzpr3d4t0r]

If radius is less than 0 wouldn't this return error without setting an error?

Yes because that function is used inside functions that don't set errors ( specifically pgCircle_FromObject and in the future its fastcall version), so the error code 0 is forwarded to that function that then forwards its error code 0 and then sets the error. Like this:

static int
pg_circle_init(pgCircleObject *self, PyObject *args, PyObject *kwds)
{
    if (!pgCircle_FromObject(args, &self->circle)) {
        PyErr_SetString(
            PyExc_TypeError,
            "Arguments must be a Circle, a sequence of length 3 or 2, or an "
            "object with an attribute called 'circle'");
        return -1;
    }
    return 0;
}

Also is radius 0 allowed or not?

Right now radius=0 is not allowed since geometrically and mathematically that's a degenerate shape.

The docs say less than zero, the code says zero or less.

Yeah i didn't port the docs fully so the part that specified that it's not valid was missing. Now it's there.

IMO zero radius should be allowed to get a scuffed vector (because people might make a shrinking circle and it would be nice to just go to zero)

I'm not so sure about this tbh might cause issues with collision or other stuff.

[Starbuck5]

We have zero vectors and zero surfaces. It seems more inconvenient to not be able to make it with zero radius.

This is not a blocker for this PR though.

[Starbuck5]

A question, should i add these to static.c?

I guess so.

[Starbuck5]

This strategy is unconventional versus the rest of the docs, gave me a pause when looking at the generated copy.

[Starbuck5]

It's experimental, it's hidden. That makes it okay to merge.

Still have some open feedback but nothing critical.

This could be a really cool module!

[MyreMylar]

Alright, this seems to work OK to me.

I think the main thing I would focus on next for circle is making it match some of the feature set of Rect/Frect. Particularly some of those familiar properties that make sense, e.g.:

x,y,r
center
diameter

where you can set one and it updates the other (e.g. I set diameter to X and radius becomes x/2).

Then I would make sure we have a good story for interoperability with pygame.draw.circle, compared to Rect/Frect:

pygame.draw.rect(screen, Color("red"), rect_1)
pygame.draw.circle(screen, Color("red"), circle_1)  # - Ideal, but not backwards compatible
pygame.draw.circle(screen, Color("red"), circle_1.center, circle_1.r)  # - Workable
pygame.draw.circle(screen, Color("red"), (circle_1.x, circle_1.y), circle_1.r)  # - Current situation