 |
Simple Game Graphics Library 1.1
|
|
Simple Game Graphics Library 1.1
|
Functions | |
| std::vector< std::string > | preloadBitmaps (const std::string &dir) |
| bool | getBitmapData (const std::string &bitmap_name, unsigned char **buffer, unsigned int *width, unsigned int *height) |
| bool | updateBitmapData (const std::string &bitmap_name, const unsigned char *buffer) |
| bool getBitmapData | ( | const std::string & | bitmap_name, |
| unsigned char ** | buffer, | ||
| unsigned int * | width, | ||
| unsigned int * | height ) |
Get the internally stored image buffer of the bitmap, along with the width and height of the internally stored image.
The size of the image buffer is not necessarily the same with that of the requested bitmap to load, since SGG internally makes the image dimensions powers of two. The reported width and height are therefore the corrected dimensions. The image can be used for obtaining the data to a bitmap used as texture in the engine and modify its contents. The number of channels in the image buffer are always expected to be 4 (red, green, blue and opacity - alpha).
| bitmap_name | is the name of the bitmap as loaded and indexed by SGG. |
| buffer | is a pointer to an unsigned char array to pass the internal address of the image buffer to. Warning, the data can be directly modified. |
| width | is a pointer to an unsigned int variable to store the width of the image buffer. |
| height | is a pointer to an unsigned int variable to store the height of the image buffer. |
| std::vector< std::string > preloadBitmaps | ( | const std::string & | dir | ) |
Loads all PNG bitmaps located in a directory specified by the argument dir at once.
Preloading image assets prior to actually requesting a draw call with a brush that uses them can significantly boost performance during the typical draw call when a bitmap is first used.
When a named image is used for a brush, the first time the library encounters the image asset with the specific unique name, it attempts to load the image, scale the bitmap to the closest power of two (if not already in the right resolution) and create the necessary internal representation for the underlying graphics API. For large assets, this process can take some time, noticeable as momentary freeze and general slowdown, depending on the size and number of images needed to be loaded. This of course happens only the first time a bitmap is used in the application, but can nevertheless degrade the user experience.
preloadBitmaps performs the above process in bulk, for all PNG bitmaps found in the provided directory. This can be done during the application initialization stage, before the actual main interaction loop begins. The function can be called multiple times for a different directory each time, to progressively load organized collections of bitmaps. preloadBitmaps returns a vector of the bitmaps successfully loaded, which can be used as a means to validate that all assets have been properly loaded. Another useful application of the function is to load multiple bitmaps without the need to know the specific names beforehand. For example, one can organize the frames of an animation sequence into a separate folder and load all the sequence at once, maintaining the animation bitmap names for reference and cycling over the animation sequence. Another different application example is the call of the function on a directory to discover and load all images contained there to be able to list and preview the images during runtime (e.g. in an image viewer application).
The preloadBitmaps function can be called at any time after the graphics initialization, i.e. after the call to createWindow.
Please note that since a bitmap is identified by its fully qualified path, bitmaps with the same filename residing in different directories are treated as two different assets. Also note that multiple attempts to preload the same bitmap will report the bitmap as successfully loaded in the return vector, but the actual bitmap loaded the first time will be used and will not be replaced by the loader in subsequent calls. This means that during runtime, even if one modifies the bitmap asset externally and explicitly calls preloadBitmaps (or any other bitmap loading via a new brush creation), the original bitmap loaded the first time will be used.
| dir | is the directory of the bitmaps to preload. Only PNG images will be loaded (extension is case-insensitive) and all other files in the directory will be ignored. The function is not called recursively for contained sub-directories. |
| bool updateBitmapData | ( | const std::string & | bitmap_name, |
| const unsigned char * | buffer ) |
Update the internally stored image buffer data of a bitmap.
The function passes an image buffer to SGG to replace the data of an existing bitmap. The expected dimensions of the buffer can be obtained using the getBitmapData function. The number of channels in the image buffer are always expected to be 4 (red, green, blue and opacity - alpha). The size of the image buffer is not necessarily the same with that of the requested bitmap to load, since SGG internally makes the image dimensions powers of two. The reported width and height are therefore the corrected dimensions. The image can be used for obtaining the data to a bitmap used as texture in the engine, modify its contents and update it using the updateBitmapData function.
| bitmap_name | is the name of the bitmap as loaded and indexed by SGG. |
| buffer | is an unsigned char array to copy the image data from. If nullptr, no pixel copy is performed, but the texture is nevertheless rebuilt. This is useful for reloading the internal image buffer to the graphics back end, after directly modifying the texture data using the pointer returned by getBitmapData. |
1.14.0