major overhaul

README.md

@@ -1,5 +1,58 @@
+![popsicgl](./docs/assets/popsicgl.WEBP)
+
 # pysicgl
 
 pysicgl is a Python C extension interface for the [sicgl](https://github.com/oclyke/sicgl) graphics library.
 
 both projects are young and would benefit from community involvement.
+
+# getting started as a developer
+
+**get submodules**
+
+```bash
+git submodule update --init --recursive
+```
+
+**set up the python environment**
+
+* remove any existing virtual environment
+* create a new virtual environment
+* activate the virtual environment
+* install development dependencies
+
+```bash
+rm -rf venv
+python3 -m venv venv # use your Python 3 interpreter
+source venv/bin/activate
+pip install -r requirements.dev.txt
+```
+
+**build and develop pysicl**
+
+```bash
+python setup.py build
+python setup.py develop
+```
+
+**run tests and install**
+
+```bash
+python -m pytest
+python setup.py test
+python setup.py install
+```
+
+# formatting
+
+```
+source venv/bin/activate
+./scripts/third-party/run-clang-format/run-clang-format.py -r include src
+black .
+```
+
+# design choices
+
+## color sequences
+
+color sequences are immutable. side effects are not allowed.

examples/simple.py

@@ -15,7 +15,7 @@
 display = pysicgl.Interface(display_screen, display_memory)
 
 # create a orange-red color using a 4-tuple of RGBA components
-color = pysicgl.Color.from_rgba((255, 128, 3, 0))
+color = pysicgl.color.from_rgba((255, 128, 3, 0))
 
 # draw a pixel directly to the interface origin
 # the coordinates are given in the interface-relative system

include/pysicgl/submodules/color.h

@@ -0,0 +1,7 @@
+#pragma once
+
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+// python includes first (clang-format)
+
+PyMODINIT_FUNC PyInit_color(void);

include/pysicgl/submodules/composition.h

@@ -0,0 +1,7 @@
+#pragma once
+
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+// python includes first (clang-format)
+
+PyMODINIT_FUNC PyInit_composition(void);

include/pysicgl/submodules/functional.h

@@ -0,0 +1,7 @@
+#pragma once
+
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+// python includes first (clang-format)
+
+PyMODINIT_FUNC PyInit_functional(void);

include/pysicgl/submodules/functional/color.h

@@ -0,0 +1,8 @@
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+// python includes first (clang-format)
+
+PyObject* color_from_rgba(PyObject* self, PyObject* args);
+PyObject* color_to_rgba(PyObject* self, PyObject* args);
+PyObject* interpolate_color_sequence(
+    PyObject* self_in, PyObject* args, PyObject* kwds);

include/pysicgl/submodules/functional/color_correction.h

@@ -0,0 +1,5 @@
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+// python includes first (clang-format)
+
+PyObject* gamma_correct(PyObject* self, PyObject* args);

include/pysicgl/drawing/global.h → include/pysicgl/submodules/functional/drawing/global.h

@@ -2,7 +2,7 @@
 
 #define PY_SSIZE_T_CLEAN
 #include <Python.h>
-// python includes must come first
+// python includes first (clang-format)
 
 PyObject* global_pixel(PyObject* self_in, PyObject* args);
 PyObject* global_line(PyObject* self_in, PyObject* args);

include/pysicgl/drawing/interface.h → include/pysicgl/submodules/functional/drawing/interface.h

@@ -2,7 +2,10 @@
 
 #define PY_SSIZE_T_CLEAN
 #include <Python.h>
-// python includes must come first
+// python includes first (clang-format)
+
+PyObject* interface_compose(PyObject* self_in, PyObject* args);
+PyObject* interface_blit(PyObject* self_in, PyObject* args);
 
 PyObject* interface_fill(PyObject* self_in, PyObject* args);
 PyObject* interface_pixel(PyObject* self_in, PyObject* args);

include/pysicgl/drawing/screen.h → include/pysicgl/submodules/functional/drawing/screen.h

@@ -2,7 +2,7 @@
 
 #define PY_SSIZE_T_CLEAN
 #include <Python.h>
-// python includes must come first
+// python includes first (clang-format)
 
 PyObject* screen_fill(PyObject* self_in, PyObject* args);
 PyObject* screen_pixel(PyObject* self_in, PyObject* args);

include/pysicgl/submodules/functional/operations.h

@@ -0,0 +1,8 @@
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+// python includes first (clang-format)
+
+PyObject* scalar_field(PyObject* self_in, PyObject* args, PyObject* kwds);
+PyObject* compose(PyObject* self_in, PyObject* args);
+PyObject* blit(PyObject* self_in, PyObject* args);
+PyObject* scale(PyObject* self_in, PyObject* args);

include/pysicgl/submodules/interpolation.h

@@ -0,0 +1,7 @@
+#pragma once
+
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+// python includes first (clang-format)
+
+PyMODINIT_FUNC PyInit_interpolation(void);

include/pysicgl/types/color_sequence.h

@@ -0,0 +1,20 @@
+#pragma once
+
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+// python includes first (clang-format)
+
+#include "pysicgl/types/color_sequence_interpolator.h"
+#include "sicgl/color_sequence.h"
+
+// declare the type
+extern PyTypeObject ColorSequenceType;
+
+typedef struct {
+  PyObject_HEAD color_sequence_t sequence;
+  ColorSequenceInterpolatorObject* interpolator;
+
+  // iterator state
+  // protected by the GIL
+  size_t iterator_index;
+} ColorSequenceObject;

include/pysicgl/types/color_sequence_interpolator.h

@@ -0,0 +1,18 @@
+#pragma once
+
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+// python includes first (clang-format)
+
+#include "sicgl/color_sequence.h"
+
+// declare the type
+extern PyTypeObject ColorSequenceInterpolatorType;
+
+typedef struct {
+  PyObject_HEAD sequence_map_fn fn;
+  void* args;
+} ColorSequenceInterpolatorObject;
+
+ColorSequenceInterpolatorObject* new_color_sequence_interpolator_object(
+    sequence_map_fn fn, void* args);

include/pysicgl/types/compositor.h

@@ -0,0 +1,23 @@
+#pragma once
+
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+// python includes first (clang-format)
+
+#include <stdbool.h>
+
+#include "sicgl/compose.h"
+#include "sicgl/compositors.h"
+
+// declare the type
+extern PyTypeObject CompositorType;
+
+typedef struct {
+  PyObject_HEAD
+      /* Type-specific fields go here. */
+      compositor_fn fn;
+  void* args;
+} CompositorObject;
+
+// public constructors
+CompositorObject* new_compositor_object(compositor_fn fn, void* args);

include/pysicgl/interface.h → include/pysicgl/types/interface.h

@@ -2,9 +2,9 @@
 
 #define PY_SSIZE_T_CLEAN
 #include <Python.h>
-// python includes must come first
+// python includes first (clang-format)
 
-#include "pysicgl/screen.h"
+#include "pysicgl/types/screen.h"
 #include "sicgl/interface.h"
 #include "sicgl/screen.h"
 
@@ -18,8 +18,8 @@ typedef struct {
 
   // a ScreenObject which is linked to
   // the interface screen by reference
-  ScreenObject* _screen;
+  ScreenObject* screen;
 
   // a buffer backs up the interface memory
-  Py_buffer _memory_buffer;
+  Py_buffer memory_buffer;
 } InterfaceObject;

include/pysicgl/field.h → include/pysicgl/types/scalar_field.h

@@ -2,16 +2,14 @@
 
 #define PY_SSIZE_T_CLEAN
 #include <Python.h>
-// python includes must come first
+// python includes first (clang-format)
 
 #include "sicgl/field.h"
 
 // declare the type
 extern PyTypeObject ScalarFieldType;
 
 typedef struct {
-  PyObject_HEAD Py_buffer _scalars_buffer;
+  PyObject_HEAD double* scalars;
+  size_t length;
 } ScalarFieldObject;
-
-int scalar_field_get_scalars(
-    ScalarFieldObject* self, size_t* len, double** scalars);

include/pysicgl/screen.h → include/pysicgl/types/screen.h

@@ -2,7 +2,7 @@
 
 #define PY_SSIZE_T_CLEAN
 #include <Python.h>
-// python includes must come first
+// python includes first (clang-format)
 
 #include <stdbool.h>
 
@@ -18,8 +18,5 @@ typedef struct {
   screen_t _screen;
 
   // a flag to explicitly indicate whether this is an object or reference
-  bool _is_reference;
+  bool is_reference;
 } ScreenObject;
-
-// publicly accessible constructors
-ScreenObject* new_screen_object(screen_t* ref);

packages/pysicgl/__init__.py

@@ -0,0 +1 @@
+from ._core import *

requirements.dev.txt

@@ -1,3 +1,4 @@
 black >= 22.12.0, < 23.0.0
 pytest >= 7.2.1, < 8.0.0
+setuptools >= 67.0.0, < 68.0.0
 sphinx >= 6.1.3, < 7.0.0