southclaws / samp-bitmapper

For generating in-game coordinates from a bitmap.

samp-bitmapper

For generating in-game coordinates from a bitmap.

See this thread for the primary reason that this plugin exists. It's best used with MapAndreas or ColAndreas and a texture map so you can automatically place items in the game world in areas.

Create a bitmap image of the map then paint specific colours over it. Then, load the bitmap and specify which colours you want to cache with OpenBitmapCache. You can then get random points in the image of specific cached colours with GetRandomCachedRGB.

If you want to map larger or smaller bitmaps to areas of the map, use this library to create a virtual canvas to perform the scaling.

For example, this:

Generates this:

See the thread linked above for more examples.

Installation

Simply install to your project:

sampctl package install Southclaws/samp-bitmapper

Or, if you prefer GitHub:

• Binaries
• Source & Include

Include in your code and begin using the library:

#include <bitmapper>

Usage

Functions

OpenBitmap(const filename[], &Bitmap:handle);

Opens the given file as a bitmap image and stores thefile handle in handle. Returns 0 on success or an error code.

OpenBitmapCache(const filename[], &Bitmap:handle, const colours[], len = sizeof colours);

Opens the given file and caches all pixels that match the colours listed in colours. Returns 0 on success or an error code.

CloseBitmap(Bitmap:handle);

Closes the specified file handle. Returns 0 on success, 1 if the handle is invalid.

GetRGB(Bitmap:handle, x, y, &r, &g, &b);

Looks up the red, green and blue values stored in the specified X and Y coordinates and stores them in the result parameters r, b and g.

GetRandomCachedRGB(Bitmap:handle, colour, &x, &y);

Provides coordinates and RGB information from a random pixel in the bitmap that contains the specified colour.

Testing

You can compile the plugin and test it in a Docker container all with one command:

make build-e2e

This will:

• build the plugin inside a Debian docker image
• build the Pawn package in test/ with sampctl
• run the server in test/ as a container, also with sampctl

Or you can just do the build process with:

make build-debian

(thanks to maddinat0r for the Docker images!)

samp-bitmapper's Issues

API Design

So the primary goal of this plugin is not to simply read bitmaps and provide an API to access the pixel values. It's to facilitate things like this http://forum.sa-mp.com/showthread.php?t=516560 and the API should provide a simple and optimised way to do that leaving Pawn to do as little work as possible.

I'm thinking there should be the standard open and close functions that allocate and free a bitmap.

While it's in memory, the plugin should process the data in some way (off thread probably?) to build something akin to an index so picking pixels based on colour is fast. The kinds of images this plugin will work well with are flat images of the world map with very few colours (like on the link above). So I'm thinking of a pixel sorter style algorithm with buckets for each colour that map to XY coordinates.

Possible API:

• PointFromColour(int colour)
• PointsFromColour(int colour, int dest[], int max)

If these operations do turn out to be slow, I'm thinking of a streaming asynchronous API that uses Pawn callbacks when data is available:

• PointsFromColour(int colour, string callback)
  • which would call callback either for each pixel or a group of pixels of a predefined size

Still needs ironing out, feedback appreciated!

Bitmap library

Hual suggested this one: https://github.com/skywind3000/BasicBitmap