gg: deprecate gg.DrawImageConfig.rotate, in favor of gg.DrawImageConf…

…ig.rotation, improve the documentation comments (#21963)

examples/gg/additive.v

@@ -29,9 +29,10 @@ pub fn (mut window Window) draw(_ voidptr) {
 			width: window.image.width
 			height: window.image.height
 		}
+		rotation: f32(window.ctx.frame)
 		// effect: .alpha <-- this can be omitted completely as it is alpha by default.
 	}
-	window.ctx.draw_image_with_config(myconfig)
+	window.ctx.draw_image_with_config(gg.DrawImageConfig{ ...myconfig, flip_x: true })
 
 	// Red
 	window.ctx.draw_image_with_config(gg.DrawImageConfig{
@@ -110,6 +111,7 @@ fn main() {
 	mut window := &Window{}
 
 	window.ctx = gg.new_context(
+		window_title: 'Additive colors & image rotation'
 		width: 800
 		height: 600
 		user_data: window

vlib/gg/image.c.v

@@ -387,13 +387,13 @@ pub fn (ctx &Context) draw_image_with_config(config DrawImageConfig) {
 	sgl.enable_texture()
 	sgl.texture(img.simg, img.ssmp)
 
-	if config.rotate != 0 {
+	if config.rotation != 0 {
 		width := img_rect.width * ctx.scale
 		height := (if img_rect.height > 0 { img_rect.height } else { img.height }) * ctx.scale
 
 		sgl.push_matrix()
 		sgl.translate(x0 + (width / 2), y0 + (height / 2), 0)
-		sgl.rotate(sgl.rad(-config.rotate), 0, 0, 1)
+		sgl.rotate(sgl.rad(-config.rotation), 0, 0, 1)
 		sgl.translate(-x0 - (width / 2), -y0 - (height / 2), 0)
 	}
 
@@ -405,7 +405,7 @@ pub fn (ctx &Context) draw_image_with_config(config DrawImageConfig) {
 	sgl.v3f_t2f(x0, y1, config.z, u0f, v1f)
 	sgl.end()
 
-	if config.rotate != 0 {
+	if config.rotation != 0 {
 		sgl.pop_matrix()
 	}
 

vlib/gg/image.v

@@ -8,16 +8,18 @@ import gx
 // that can be used to draw an image onto the screen
 pub struct DrawImageConfig {
 pub mut:
-	flip_x    bool
-	flip_y    bool
+	flip_x    bool // set to true, if you need to flip the image horizontally (around a vertical axis), <- will become ->
+	flip_y    bool // set to true, if you need to flip the image vertically (around a horizontal axiz), -\/- will become -/\-
 	img       &Image = unsafe { nil }
 	img_id    int
 	img_rect  Rect // defines the size and position on image when rendering to the screen
 	part_rect Rect // defines the size and position of part of the image to use when rendering
-	rotate    f32  // amount to rotate the image in degrees
+	rotate    f32         @[deprecated: 'use `rotation` instead of `rotate`'; deprecated_after: '2024-07-30']
 	z         f32
 	color     gx.Color    = gx.white
 	effect    ImageEffect = .alpha
+	//
+	rotation f32 // the amount to rotate the image in degrees, counterclockwise. Use a negative value, to rotate it clockwise.
 }
 
 pub enum ImageEffect {