AGS 4: Script API: add Overlay.Tint and SetLevel, complying to character and object settings

[ivan-mogilko]

Support for tinting overlay, for consistency with characters and objects.

Added following to the Overlay struct in script:

  /// Tints the overlay to the specified colour.
  import void     Tint(int red, int green, int blue, int saturation, int luminance);
  /// Sets the light level for this overlay.
  import void     SetLightLevel(int light_level);
  /// Removes an existing colour tint or light level from this overlay.
  import void     RemoveTint();
  /// Gets whether the overlay has a tint set.
  readonly import attribute bool HasTint;
  /// Gets whether the overlay has a light level set.
  readonly import attribute bool HasLightLevel;
  /// Gets the individual light level for this character.
  readonly import attribute int  LightLevel;
  /// Gets the Blue component of this overlay's colour tint.
  readonly import attribute int  TintBlue;
  /// Gets the Green component of this overlay's colour tint.
  readonly import attribute int  TintGreen;
  /// Gets the Red component of this overlay's colour tint.
  readonly import attribute int  TintRed;
  /// Gets the Saturation of this overlay's colour tint.
  readonly import attribute int  TintSaturation;
  /// Gets the Luminance of this overlay's colour tint.
  readonly import attribute int  TintLuminance;

[ericoporto]

What is LightLevel and why it isn't a property that can be set too?

Also shouldn't the comment description have the ranges of these?

https://github.com/user-attachments/assets/94ba12ed-790b-4f35-8181-1354730ddb01

In other news it appears to work alright with overlays, I am testing luminance here.

I think if I could in a single API call set an overlay position and size too, it would be great! (like Overlay.SetDimensions(int x, int y, int width, int height))

[ivan-mogilko]

What is LightLevel and why it isn't a property that can be set too?

Light level brightens or darkens sprite. It may be set using function SetLightLevel(), and read using LightLevel property. This is done for consistency with characters and objects, and also to emphasize that it is mutually exclusive with the Tint. Either Tint or LightLevel may be set at the same time, so calling function resets the other setting. With settable properties that may be less obvious.

[ivan-mogilko]

Oops, I just noticed that SetLightLevel is declared as "function" instead of "void". Probably a result of copy-paste.

[ericoporto]

Is it possible to add the ranges right in the comments too? Like does it goes to 0-100 or 0-255 or 0-250 ...?

[ivan-mogilko]

Is it possible to add the ranges right in the comments too? Like does it goes to 0-100 or 0-255 or 0-250 ...?

Yes, I shall add these.

[ericoporto]

@ivan-mogilko you are hitting a weird error below according to the CI

libsrc/allegro/src/file.c:508:18: error: passing argument 1 of 'utf8_getx' from incompatible pointer type [-Wincompatible-pointer]

// in unicode.c
/*static*/ int utf8_getx(char **s)

// in unicode.h
AL_FUNC(int, utf8_getx, (char **s));

// ... in file.c
#define ugetxc    utf8_getx
// ...
int c; 
const char *ptr; //...
c = ugetxc(&ptr)
...

I think it's the mix of char and const char. Should be char *ptr; in file.c at line 502.

[ivan-mogilko]

That is not a problem of this PR, this happens in ags4 branch.

[ivan-mogilko]

I think if I could in a single API call set an overlay position and size too, it would be great! (like Overlay.SetDimensions(int x, int y, int width, int height))

That will be fine to add; although i am not certain about the name. "Dimensions" term seems to refer strictly to the sizes, this term is never used in ags api. The only instance of a function that sets all 4 values is "Viewport.SetPosition" (probably because I found it easier to remember, but that could be a mistake). The equivalent that i found in C# is "Control.SetBounds".

It would be proper to introduce a set of terms that may be applied everywhere (gui, overlays, viewport, camera, etc).

[ericoporto]

Other possible naming would be something like SetGeometry. SetPosition is fine too. There isn't a good word for Size and Position together I think, so going with either works.

I know it's not related to this PR it's just that looking at SetTint it would be awesome for performance that does more of setting the overlay in a single call for uses of overlays in things like a particle or in this alternative renderer of mine.

[ivan-mogilko]

Added SetPosition and SetSize in a separate PR: #2483

[ivan-mogilko]

Rebased to be after mingw fixes.