GraphicImage Template

colourAlloc()

Allocate a colour for use in drawing methods

Syntax

number = rb.GraphicImage.colourAlloc(red, green, blue, alpha)

Parameters

The 'colourAlloc' method takes 4 parameters:

Results

The 'colourAlloc' method returns number:

Remarks

Allocate a colour for subsequent drawing operations.

For true-colour images (the default) this method doesn't do a lot - the number returned will be 0xAARRGGBB - where 'AA' is the alpha component, 'RR' is the red component, 'GG' the green component and 'BB' the blue component.

In the case of palette images, created by passing 'false' as the third parameter of 'create', or by loading a GIF image, require colours to be mapped into the limited space of the palette.

For palette images, an attempt is made to find an existing palette entry with the specified colour values. If found this is returned. If not then a search is made for an empty palette slot. If an empty slot is found the map is made and the index assigned is returned to the caller.

If the requested colour is not already in the palette and the palette is full then this method returns -1. For palette images it is always a good idea to check the return value unless your application allocates all colours and keeps it's own tally on usage.

Alternatively, for palette images, call 'colourResolve' to automatically allocate the closest colour if the palette is currently full.

Example

  // Create an empty 100x100 pixel palette based image
  var img = (new GraphicImage).create(100,100, false);

  // Draw the pixels {0,0},{1,1},{2,2} to red and the pixel at {3,3} to blue
  var red   = img.colourAlloc(255,  0,  0);
  var greem = img.colourAlloc(  0,255,  0);
  var blue  = img.colourAlloc(  0,  0,255);

  var pixels = [
    {x:0, y:1},
    {x:1, y:1},
    {x:2, y:2},
    {x:3, y:3, c:blue}
  ];
  img.drawPixels(pixels,red);