GdkPixbuf *pixbuf_copy_mirror(GdkPixbuf *src, gboolean mirror, gboolean flip);
GdkPixbuf* pixbuf_apply_orientation(GdkPixbuf *pixbuf, gint orientation);
+/**
+ * @brief Composites the fill color with the existing contents of the pixbuf,
+ * within the specified region, with a proportion set by the alpha (`a`)
+ * parameter.
+ * @param pb The `GdkPixbuf` to paint into.
+ * @param x,y Coordinates of the top-left corner of the first region.
+ * @param w,h Extent of the first region.
+ * @param r,g,b Fill color.
+ * @param a The alpha to use for compositing. a=255 is solid (fully the new
+ * color). a=0 is tranparent (fully the original contents).
+ */
void pixbuf_draw_rect_fill(GdkPixbuf *pb,
gint x, gint y, gint w, gint h,
gint r, gint g, gint b, gint a);
+/**
+ * @brief Fills the specified region of the pixbuf with the specified color.
+ * @param pb The `GdkPixbuf` to paint into.
+ * @param x,y Coordinates of the top-left corner of the first region.
+ * @param w,h Extent of the first region.
+ * @param r,g,b,a Fill color and alpha.
+ */
void pixbuf_set_rect_fill(GdkPixbuf *pb,
gint x, gint y, gint w, gint h,
gint r, gint g, gint b, gint a);
+/**
+ * @brief Draws a rectangular stroke of the specified stroke width and color
+ * around the specified region of the pixbuf.
+ * @param pb The `GdkPixbuf` to paint into.
+ * @param x,y Coordinates of the top-left corner of the region.
+ * @param w,h Extent of the region.
+ * @param r,g,b,a Line color and alpha.
+ * @param left_width Stroke width of the left edge of the rectangle.
+ * @param right_width Stroke width of the right edge of the rectangle.
+ * @param top_width Stroke width of the top edge of the rectangle.
+ * @param bottom_width Stroke width of the bottom edge of the rectangle.
+ */
void pixbuf_set_rect(GdkPixbuf *pb,
gint x, gint y, gint w, gint h,
gint r, gint g, gint b, gint a,
- gint left, gint right, gint top, gint bottom);
+ gint left_width, gint right_width, gint top_width, gint bottom_width);
+/**
+ * @brief Sets the specified pixel of the pixbuf to the specified color.
+ * @param pb The `GdkPixbuf` to paint into.
+ * @param x,y Coordinates of the pixel to set.
+ * @param r,g,b,a Color and alpha.
+ */
void pixbuf_pixel_set(GdkPixbuf *pb, gint x, gint y, gint r, gint g, gint b, gint a);
guint8 r, guint8 g, guint8 b, guint8 a);
+/**
+ * @brief Draws a filled triangle of the specified color into the pixbuf, constrained
+ * to the specified clip region.
+ * @param pb The `GdkPixbuf` to paint into.
+ * @param x1,y1 Coordinates of the first corner of the triangle.
+ * @param x2,y2 Coordinates of the second corner of the triangle.
+ * @param x3,y3 Coordinates of the third corner of the triangle.
+ * @param clip_x,clip_y Coordinates of the top-left corner of the clipping region.
+ * @param clip_w,clip_h Extent of the clipping region.
+ * @param r,g,b,a Color and alpha.
+ */
void pixbuf_draw_triangle(GdkPixbuf *pb,
gint clip_x, gint clip_y, gint clip_w, gint clip_h,
gint x1, gint y1, gint x2, gint y2, gint x3, gint y3,
guint8 r, guint8 g, guint8 b, guint8 a);
+/**
+ * @brief Draws the sub-segment of the specified line segment that lies within the
+ * clip region into the pixbuf.
+ * @param pb The `GdkPixbuf` to paint into.
+ * @param clip_x,clip_y Coordinates of the top-left corner of the clipping region.
+ * @param clip_w,clip_h Extent of the clipping region.
+ * @param x1,y1 Coordinates of the first point of the line segment.
+ * @param x2,y2 Coordinates of the second point of the line segment.
+ * @param r,g,b,a Color and alpha.
+ */
void pixbuf_draw_line(GdkPixbuf *pb,
gint clip_x, gint clip_y, gint clip_w, gint clip_h,
gint x1, gint y1, gint x2, gint y2,
guint8 r, guint8 g, guint8 b, guint8 a);
+/**
+ * @brief Composites a "shaded" region of the specified color and with the
+ * specified size and border gradient width into the clip region of the
+ * specified pixbuf.
+ * @param pb The `GdkPixbuf` to paint into.
+ * @param clip_x,clip_y Coordinates of the top-left corner of the clipping region.
+ * @param clip_w,clip_h Extent of the clipping region.
+ * @param x,y Coordinates of the top-left corner of the shaded region.
+ * @param w,h Extent of the shaded region.
+ * @param border The thickness, in pixels, of the gradient border around the
+ * fully-shaded region.
+ * @param r,g,b Shadow base color.
+ * @param a The max shadow composition fraction. Note that any alpha value of the
+ * original pixel will remain untouched.
+ */
void pixbuf_draw_shadow(GdkPixbuf *pb,
gint clip_x, gint clip_y, gint clip_w, gint clip_h,
gint x, gint y, gint w, gint h, gint border,
guint8 r, guint8 g, guint8 b, guint8 a);
+/**
+ * @brief Sets the r, g, and b values for each pixel within the specified region
+ * of the pixbuf the average of the original values for that pixel.
+ * @param pb The `GdkPixbuf` to paint into.
+ * @param x,y Coordinates of the top-left corner of the region.
+ * @param w,h Extent of the region.
+ */
void pixbuf_desaturate_rect(GdkPixbuf *pb,
gint x, gint y, gint w, gint h);
+/**
+ * @brief Sets each full-black `(0, 0, 0)` or full-white `(255, 255, 255)` pixel in the
+ * specified pixbuf region to full-red `(255, 0, 0)`. Does not change alpha.
+ * @param pb The `GdkPixbuf` to paint into.
+ * @param x,y Coordinates of the top-left corner of the first region.
+ * @param w,h Extent of the first region.
+ */
void pixbuf_highlight_overunderexposed(GdkPixbuf *pb,
- gint x, gint y, gint w, gint h);
+ gint x, gint y, gint w, gint h);
+/**
+ * @brief Sets the alpha channel to 255 (fully opaque) for every pixel in the specified
+ * pixbuf region.
+ * @param pb The `GdkPixbuf` to paint into.
+ * @param x,y Coordinates of the top-left corner of the first region.
+ * @param w,h Extent of the first region.
+ */
void pixbuf_ignore_alpha_rect(GdkPixbuf *pb,
- gint x, gint y, gint w, gint h);
+ gint x, gint y, gint w, gint h);
/* clipping utils */
+// TODO(xsdg): Rename this function to util_intersect_regions.
+/**
+ * @brief Performs an intersection of the two specified regions.
+ * @param[in] x,y Coordinates of the top-left corner of the first region.
+ * @param[in] w,h Extent of the first region.
+ * @param[in] clip_x,clip_y Coordinates of the top-left corner of the second region.
+ * @param[in] clip_w,clip_h Extent of the second region.
+ * @param[out] rx,ry Computed coordinates of the top-left corner of the intersection.
+ * @param[out] rw,rh Computed extent of the intersection.
+ * @retval FALSE The specified regions are non-overlapping.
+ * @retval TRUE The intersection operation was performed, and the output params were set.
+ */
gboolean util_clip_region(gint x, gint y, gint w, gint h,
gint clip_x, gint clip_y, gint clip_w, gint clip_h,
gint *rx, gint *ry, gint *rw, gint *rh);
+
+// TODO(xsdg): Rename this function to util_triangle_bounding_box.
+/**
+ * @brief Computes the bounding box for the specified triangle.
+ * @param[in] x1,y1 Coordinates of the first corner of the triangle.
+ * @param[in] x2,y2 Coordinates of the second corner of the triangle.
+ * @param[in] x3,y3 Coordinates of the third corner of the triangle.
+ * @param[out] rx,ry Computed coordinates of the top-left corner of the bounding box.
+ * @param[out] rw,rh Computed extent of the bounding box.
+ */
void util_clip_triangle(gint x1, gint y1, gint x2, gint y2, gint x3, gint y3,
gint &rx, gint &ry, gint &rw, gint &rh);