colorm: add DrawImageOptions.ColorScale

Closes #3188

colorm/draw.go

@@ -25,6 +25,15 @@ type DrawImageOptions struct {
 	// The default (zero) value is identity, which draws the image at (0, 0).
 	GeoM ebiten.GeoM
 
+	// ColorScale is a scale of color.
+	//
+	// ColorScale is slightly different from colorm.ColorM's Scale in terms of alphas.
+	// ColorScale is applied to premultiplied-alpha colors, while colorm.ColorM is applied to straight-alpha colors.
+	// Thus, ColorM.Scale(r, g, b, a) equals to ColorScale.Scale(r*a, g*a, b*a, a).
+	//
+	// The default (zero) value is identity, which is (1, 1, 1, 1).
+	ColorScale ebiten.ColorScale
+
 	// Blend is a blending way of the source color and the destination color.
 	// The default (zero) value is the regular alpha blending.
 	Blend ebiten.Blend
@@ -44,6 +53,7 @@ func DrawImage(dst, src *ebiten.Image, colorM ColorM, op *DrawImageOptions) {
 
 	opShader := &ebiten.DrawRectShaderOptions{}
 	opShader.GeoM = op.GeoM
+	opShader.ColorScale = op.ColorScale
 	opShader.CompositeMode = ebiten.CompositeModeCustom
 	opShader.Blend = op.Blend
 	opShader.Uniforms = uniforms(colorM)

colorm/draw_test.go

@@ -299,3 +299,18 @@ func TestColorMCopy(t *testing.T) {
 		}
 	}
 }
+
+func TestColorScale(t *testing.T) {
+	dst := ebiten.NewImage(1, 1)
+	src := ebiten.NewImage(1, 1)
+	src.Fill(color.White)
+
+	op := &colorm.DrawImageOptions{}
+	op.ColorScale.Scale(0.25, 0.5, 0.5, 0.5)
+	var cm colorm.ColorM
+	cm.Scale(1, 0.5, 1, 0.5)
+	colorm.DrawImage(dst, src, cm, op)
+	if got, want := dst.At(0, 0).(color.RGBA), (color.RGBA{0x20, 0x20, 0x40, 0x40}); !sameColors(got, want, 1) {
+		t.Errorf("got: %v, want: %v", got, want)
+	}
+}