Bitmap

Bitmap Data

.max_size (This is a static/class method) returns the maximum size of Bitmaps allowed by the GPU.

#mega? checks if the Bitmap is too big for the GPU to handle. You can still blit from these bitmaps, but you can't do basically anything else with them, besides save them again.

#to_file(path: String) saves the Bitmap to path. The format will be PNG, JPEG or BMP depending on the extension given.

#raw_data/#raw_data= provides access to the Bitmap's RGBA pixel data. It will return an ASCII-8BIT string. You can upload new data to the bitmap with the same property, but be careful; if the length of the string supplied to it is not equal to the bitmap's width * height * 4, an error will be thrown.

In mkxp, Bitmaps have their data stored on the GPU instead of in RAM. This essentially means that any modification made to the bitmap is expensive. Each and every one. If you need to make a lot of "draw calls" to a bitmap all at once (like through #set_pixel), consider using #raw_data to get all of the pixel data as a string, iterate over that, and upload it back through #raw_data= when you are done.

mkxp-z supports loading Bitmaps from JXL files.

Animation

Bitmaps in mkxp-z can have multiple frames of animation. This is just something that all Bitmaps can do; if it works with a Bitmap (which almost everything graphics-related in RGSS does), it can be animated.

There's a "high-level" way to make them (loading a gif), and a "low-level" way to make them (manually animating them yourself). You can pick whichever one you like.

"I just wanna play a GIF!"

spr = Sprite.new
spr.bitmap = Bitmap.new("some.gif")
spr.bitmap.play if spr.bitmap.animated?

If you want all GIF files to automatically play with no input from you, override Bitmap's constructor:

class Bitmap
    alias old_initialize initialize

    def initialize(*args)
        old_initialize(*args)
        self.play if self.animated?
    end
end

"Let me handle everything myself!"

All non-mega (held in RAM because they are too big for the GPU to handle) Bitmaps can be animated. These animations can be manually constructed and manipulated.

Animated bitmaps are primarily meant to be played, not changed. They do not support some editing operations, and #get_pixel calls aren't cached until the Bitmap has its frame count reduced to 1 again, de-animating it.

Individual frames given and returned by these functions are 0-indexed. Animations are only updated after Graphics.update is called. Nothing will change between frame renders.

Accessing Animation Information

• #animated? returns true if the bitmap is animated (has more than 1 frame)
• #playing/#playing= gets and sets whether or not the bitmap is currently playing. It's false if the bitmap doesn't loop and has reached its end.
• #looping/#looping= gets and sets whether or not the Bitmap should loop infinitely. Defaults to true, or if the Bitmap was loaded with a gif, whether the gif is set to loop.
• #current_frame returns the index for the frame that the Bitmap is currently depicting.
• #frame_count returns the total number of frames contained in the Bitmap.
• #frame_rate/#frame_rate= gets and sets the intended playback speed of the bitmap. This is a float, and can be as precise as you like. If you want 29.97 or 59.94, you can have it. There is no upper limit to the framerate.

Automatic Playback

• #play will begin playback of the Bitmap. mkxp-z times this internally, so the Bitmap will always play back at the intended speed, regardless of how the game is running or what Graphics.frame_rate is set to.
• #stop will stop playback of the bitmap. It will just stop the Bitmap where it is. Use #goto_and_stop(0) if you want to rewind.

Manual Control

• #goto_and_stop(pos: Integer) moves to the frame with an index of pos, stopping the Bitmap there if it was playing.
• #goto_and_play(pos: Integer) does the same as the above, but plays the Bitmap if it was stopped.
• #next_frame advances the Bitmap to its next frame. If the Bitmap is set to loop, it will move from the last frame to the first. Returns the index of the new current frame.
• #previous_frame moves the Bitmap back one frame. If the Bitmap is set to loop, it will move from the first frame to the last. Returns the index of the new current frame.

Timeline Editing

• #add_frame(source: Bitmap[, position: Integer]) adds a new frame using the Bitmap source. By default, the new frame will be appended to the end of the animation. The destination index can be specified with position. Converts the Bitmap to an animated Bitmap if it was not one already. If the value of its frame_rate is zero in this case, it is changed to match Graphics.frame_rate.
• #remove_frame([position: Integer]) removes the frame at the index position if it's provided, otherwise defaults to removing the last frame in the animation. Changes an animated Bitmap to a normal one if it causes its frame_count to reach 1.

Manipulating frame data

• #snap_to_bitmap([position: Integer]) captures the currently displayed frame -- or the frame at position if it's given -- and returns a new Bitmap created from it. It is different from using something like Bitmap.dup in that it only copies the single frame, and not all of them.
• Blitting, using the #raw_data/#raw_data=, and #to_file should all work on animated Bitmaps just fine.

Sprite (Pattern overlays)

Patterns can be applied to a Sprite as an additional way to add effects. Patterns are just Bitmaps which overlay the sprite's base bitmap; there are a few options to be set to configure them as well, but that's the gist of it. It should work similarly to how it does here. It should also work perfectly fine with animated Bitmaps, in case you happened to wonder.

• #pattern/#pattern=: A property, similar to bitmap, that points to a Bitmap object to use as the sprite's pattern.
• #pattern_blend_type/#pattern_blend_type=: A property, similar to blend_type, indicating the blend mode to use when mixing the pattern with the base Bitmap. It accepts the same values.
• #pattern_tile/#pattern_tile=: A Boolean indicating that the pattern should not be automatically zoomed to fit the rest of the sprite. If you would prefer it the other way, this can be set to false and save a few CPU cycles from doing the math with #pattern_zoom_x/#pattern_zoom_y yourself.
• #pattern_opacity/#pattern_opacity=: An Integer ranging from 0-255, indicating how opaque the pattern should be when mixed over the base bitmap.
• #pattern_scroll_x/#pattern_scroll_x=, #pattern_scroll_y/#pattern_scroll_y=: An Integer specifying the X and Y positions of the pattern.
• #pattern_zoom_x/#pattern_zoom_x=, #pattern_zoom_y/#pattern_zoom_y=: A Float specifying the pattern's scaling values.
• #invert/#invert=: A Boolean property that allows inverting the color of everything visible on the Sprite.