+/**
+ * @brief Composites a horizontal or vertical linear gradient into the rectangular
+ * region defined by corners `(x1, y1)` and `(x2, y2)`. Note that the
+ * current implementation breaks if the max distance between `s` and
+ * `x1/x2/y1/y2` is greater than `border`.
+ * @param p_pix The pixel buffer to paint into.
+ * @param prs The pixel row stride (how many pixels per row of the buffer).
+ * @param has_alpha TRUE if the p_pix representation is rgba. FALSE if just rgb.
+ * @param s The "center" of the gradient, along the axis defined by `vertical`.
+ * Note that if the center is not along an edge, the gradient will be
+ * symmetric about the center.
+ * @param vertical When `TRUE`, the gradient color will vary vertically. When `FALSE`,
+ * horizontally.
+ * @param border The maximum extent of the gradient, in pixels.
+ * @param x1,y1 Coordinates of the first corner of the region.
+ * @param x2,y2 Coordinates of the second corner of the region.
+ * @param r,g,b Base color of the gradient.
+ * @param a The peak alpha value when compositing the gradient. The alpha varies
+ * from this value down to 0 (fully transparent). Note that any alpha
+ * value associated with the original pixel is unmodified.
+ */