[MODULE] PALgorithms 0.01: Fancy Palette Effects for 256 Colour Mode (AGS3.1.2)

[Scavenger]

Ever wanted to do some neat colour effects, but found out too late that you're actually making a 256 colour game? Don't want to take the easy route of switching up the colours to 16bit? Fancy spending long nights tearing your hair out over ill-documented, messy code?

I don't either, but here it is anyway. I was gonna release it after I finished DWEF, but heck, that would take years and by then, who knows if 256 colour games would even be made. I can attest that the functions work really nicely, but  full screen stuff is kind of slow - unless they're on small sprites. Use these things tastefully and sparingly.

PALGORITHMS: The 256 Colour Translucency Module

This module can do it if it's got something to do with a palette:

• Percentage based simulated translucency (10 real levels, interpolation/dithering for the rest)
  
• Discworld I style colourisation: Turn everything monochrome and a colour.
  
• TintScreen and FadeToColour, both of which don't pause the game - your characters can walk off screen while the shot fades to black, red, or magenta!
  
• Module is currently 99.9% nondestructive. If you ever mess up the palette enough, switching rooms will solve it.
  

This module also contains crazy voodoo I don't fully comprehend (The Translucency stuff, appropriately enough. The CLUT generation was SteveMcCrea's work, and I reused the buffer technology from Astauber's dialogue module). As of now, translucency only works on objects (no translucent characters as I can't work out how ViewFrame works), and the translucency rendering is rather slow, but that's Get/PutPixel for you. As soon as I work out how to replace frames in a view nondestructively, I'll implement character translucency. I'm not a programmer, so that will take a long time.


DOWNLOAD IT HERE!

How to use PALgorithms:

  COLOURISATION FUNCTIONS

ProcessPalette (int palsiz, int palindex[])
  Creates a new colourisation palette and sets it to the current room palette. For instance, for a discworld inventory effect, you need
   a series of the colour blue, from lightest to darkest. here is the example. PALsiz would be 7, palindex would be bluearray:
      bluearray = new int [ 7 ];
      bluearray [ 0 ] = 46;
      bluearray [ 1 ] = 47;
      bluearray [ 2 ] = 48;
      bluearray [ 3 ] = 49;
      bluearray [ 4 ] = 50;
      bluearray [ 5 ] = 51;
      bluearray [ 6 ] = 52;
   While this can be declared in Game_Start, the game will crash horribly if Process_Palette is called before a room is loaded.
   Put it in On_event for before room fades in, and you'll get a colourisation palette you can use in every room.
   Multiple minipalettes at once aren't supported in this version, unfortunately. DO NOT sort these out of luminescience order, or
   freaky stuff happens.
   
ColouriseArea (this DynamicSprite*, int x1,  int y1,  int w,  int h);
   Places a colourised version of the selected area (x1,y1 are the top left coordinates, w+h are width and height) and places it inside
   the selected Dynamic Sprite. Useful for GUI backgrounds. WARNING: Generating a realtime colourised area that is too large may
   slow down your game!
   
CreateColourisedSprite (this DynamicSprite*,  int oldsprite);
   Creates a colourised version of a sprite (oldsprite is the ID of the sprite in question) and places it in the selected Dynamic Sprite.
   Palette Index 0 is ignored.
   
  FADE FUNCTIONS

   Tint(char R, char G, char B, char p);
    Tints the entire palette that particular RGB value, with an intensity of P. P is 0-63 in range. Leaving a room will restore the palette.
   
   UnTint(char R, char G, char B, char p);
    UNtints the entire palette FROM that particular RGB value, with an intensity of P. I'm not sure what happens if you call UnTint without calling Tint first.
   
   Fadeout(char R, char G, char B, char speed);
    Fades out the entire palette to that RGB value, where P is the speed at which it happens. P is 0-63.
   
   Fadein (char R, char G, char B, char speed);
    Fades out the entire palette from that RGB value, where P is the speed at which it happens. P is 0-63.
   
   
   TRANSLUCENCY FUNCTIONS
    The most complex of the PALgorithms, since it requires being set up from outside the game.

GenerateCLUTForRoom ();
    Generates a CLUT from the room's palette for 10 levels of transparency and saves it in CLUTROOMX.BMP, where X is the Room number.
    This takes an inordinately long time, and the game may appear to hang, but a display box will pop up when it is finished. It should
    take around 5 minutes for the generation to complete, so be patient. Once you have the image file, import it into AGS (exact palette import only, room specific)
    and make a new property for your room: TransCLUTSlot. Set that value to the sprite ID of the CLUT file, and you've finished setting up.

  SetTransparency (this Object*, char alpha);
    Replaces Object.Transparency. Anything below 90 or above 10 will register on the renderer (I don't suggest breaking these bounds with
    a transparent sprite) and render it translucent. Values divisible by 10 are completely smoothly translucent, ones divisible by 5 are evenly
    dithered between the value +5 and the value -5. Values imbetween that are diffusion dithered, and will look like static.
    This is a limitation to keep down generation time and file sizes.

SetGraphic (this Object*,  int graphic);
    Replaces Object.Graphic. Use this when you want to actually change a translucent sprites appearance for animation et al.
    Views for animated objects are not supported.

[Monsieur OUXX]

This module can do it if it's got something to do with a palette:

• Percentage based simulated translucency (10 real levels, interpolation/dithering for the rest)
  
• Discworld I style colourisation: Turn everything monochrome and a colour.
  
• TintScreen and FadeToColour, both of which don't pause the game - your characters can walk off screen while the shot fades to black, red, or magenta!
  
• Module is currently 99.9% nondestructive. If you ever mess up the palette enough, switching rooms will solve it.
  

Hmmm, makes me want to try it.  "Percentage based simulated translucency" sounds cool! I wonder if it renders well when the palette doesn't have the required colors.

[Trapezoid]

I'm trying to mess around with this. I don't know a lot about coding and the documentation here isn't much help. For instance, with ProcessPalette, how am I supposed to pass the "palindex" array?

ProcessPalette(7, bluearray[]);   gets me an "array index not specified" error

ProcessPalette(7, bluearray[0]);   gets "Type mismatch: cannot convert 'int' to 'int[]'"


Maybe you could make an example game? Or at least some example code?

[Kweepa]

Welcome back, stranger!

This seems to work:

Code: ags

  int paltemp[] = new int[3];
  paltemp[0] = 0;
  paltemp[1] = 13;
  paltemp[2] = 42;
  PALgorithms.ProcessPalette(3, paltemp);

I don't know what it does though

[monkey0506]

I also don't know what it does, but if a function expects a dynamic array as a parameter, you would pass just the name of your array. If you need more help with dynamic arrays you can PM me (as it's totally off-topic). I've used them quite regularly and for a variety of reasons and implementations.

[Trapezoid]

Oh, ok. Adding the "PALgorithms." part hadn't occurred to me.

Now I can't get the "ColouriseArea" function to work. It gets an "Undefined token" error.

[Kweepa]

For some reason, some functions use the PALgorithms. namespace and some don't.

Code: ags

DynamicSprite *spr = DynamicSprite.CreateFromBackground();
ColouriseArea(spr, 10, 10, 20, 20);

[Trapezoid]

Yeah, it won't recognize ColouriseArea. No matter if I put it in Palgorithms.asc's on_event, or in a room script, with or without the PALgorithms. prefix.

edit: Ok, I guess I had to use spr.ColouriseArea. I can run the game with no error now, but nothing seems to happen.

[Kweepa]

It's a bit of a weird one.
It takes the rectangle x,y,w,h from the screen, and draws a colourised version into the sprite you use to call it (spr in this case).

e.g.

Code: ags

  DynamicSprite *spr = DynamicSprite.Create(20, 20);
  spr.ColouriseArea(10, 10, 20, 20);
  DrawingSurface *surf = Room.GetDrawingSurfaceForBackground();
  surf.DrawImage(10, 10, spr.Graphic);
  surf.Release();

Will replace the 20x20 area beginning at 10,10 with a colourised version, using a lookup table generated with ProcessPalette, whatever that does.

[Scavenger]

It's a bit of a weird one.
It takes the rectangle x,y,w,h from the screen, and draws a colourised version into the sprite you use to call it (spr in this case).

e.g.

Code: ags

  DynamicSprite *spr = DynamicSprite.Create(20, 20);
  spr.ColouriseArea(10, 10, 20, 20);
  DrawingSurface *surf = Room.GetDrawingSurfaceForBackground();
  surf.DrawImage(10, 10, spr.Graphic);
  surf.Release();

Will replace the 20x20 area beginning at 10,10 with a colourised version, using a lookup table generated with ProcessPalette, whatever that does.

Yeah, this function is for the backgrounds of GUIs and stuff, and I guess I didn't pay enough attention to what the function names were called.

ProcessPalette simply finds the equivilent greyscale luminence of every colour in the global palette and maps the colours in the given array to them, so that when the Colourise functions are run, the resulting image still looks correct in terms of luminence.

I never expected anyone to actually use my module. I'll whip up an example game that uses this module and try to document it as best as possible. I've been meaning to use it myself anyway. x3