gfx_capabilities(3alleg4)

💖 gfx_capabilities 💖

okay bestie, welcome to the Allegro manual — this one's all about gfx_capabilities, and no cap, it's lowkey one of the most useful little globals in the whole game programming library. let's get into it 🫶

✨ NAME ✨

gfx_capabilities — a bitfield that spills all the tea about what your video hardware can actually do. it's part of the Allegro game programming library, and it's giving "receipts for your GPU" energy. 👑

🦋 SYNOPSIS 🦋

#include <allegro.h>

extern int gfx_capabilities;

🌸 DESCRIPTION 🌸

So. gfx_capabilities is a bitfield that describes the capabilities of the current graphics driver and the video hardware underneath it. It can contain any combination of these flags, bestie — mix and match, it's a vibe:

• GFX_CAN_SCROLL — this one means the scroll_screen() function is allowed to be used with this driver. scroll girl summer. ✨
• GFX_CAN_TRIPLE_BUFFER — says that request_scroll() and poll_scroll() are usable with this driver. if this flag is not set, it's possible that enable_triple_buffer() might be able to activate it anyway. so like, don't lose hope 💅
• GFX_HW_CURSOR — a hardware mouse cursor is in use. when this is set, it is safe to draw onto the screen without hiding the mouse pointer first. but okay, listen: not every cursor graphic can be implemented in hardware. in particular, VBE/AF only supports 2-color images up to 32x32 in size, where the second color is an exact inverse of the first. this means Allegro may need to switch between hardware and software cursors at literally any point while your program runs, so do not assume this flag stays constant for long stretches of time. it only tells you whether a hardware cursor is in use at the current time, and it may change whenever you hide/redisplay the pointer. it's giving main character who changes outfits mid-scene. 🙈
• GFX_SYSTEM_CURSOR — the mouse cursor is the default system cursor, not Allegro's custom cursor. iconic, honestly.
• GFX_HW_HLINE — the normal opaque version of the hline() function is implemented using a hardware accelerator. and this improves performance not just for hline() itself, but for soooo many other functions that use it as a workhorse, for example circlefill(), triangle(), and floodfill(). it's giving teamwork. 🎀
• GFX_HW_HLINE_XOR — the XOR version of hline(), plus any other functions that use it as a workhorse, are implemented using a hardware accelerator.
• GFX_HW_HLINE_SOLID_PATTERN — the solid and masked pattern modes of hline(), and any other functions that use it as a workhorse, are implemented using a hardware accelerator (peep the note below 👀).
• GFX_HW_HLINE_COPY_PATTERN — the copy pattern mode of hline(), and any other functions that use it as a workhorse, are implemented using a hardware accelerator (again, note below 👀).
• GFX_HW_FILL — the opaque version of rectfill(), the clear_bitmap() routine, and clear_to_color() are all implemented using a hardware accelerator.
• GFX_HW_FILL_XOR — the XOR version of rectfill() is implemented using a hardware accelerator.
• GFX_HW_FILL_SOLID_PATTERN — the solid and masked pattern modes of rectfill() are implemented using a hardware accelerator (note below, bestie 👀).
• GFX_HW_FILL_COPY_PATTERN — the copy pattern mode of rectfill() is implemented using a hardware accelerator (yes, note below 👀).
• GFX_HW_LINE — the opaque mode line() and vline() functions are implemented using a hardware accelerator.
• GFX_HW_LINE_XOR — the XOR version of line() and vline() are implemented using a hardware accelerator.
• GFX_HW_TRIANGLE — the opaque mode triangle() function is implemented using a hardware accelerator.
• GFX_HW_TRIANGLE_XOR — the XOR version of triangle() is implemented using a hardware accelerator.
• GFX_HW_GLYPH — monochrome character expansion (you know, for text drawing) is implemented using a hardware accelerator.
• GFX_HW_VRAM_BLIT — blitting from one part of the screen to another is implemented using a hardware accelerator. if this flag is set, blitting within the video memory will almost certainly be the fastest possible way to display an image, so it may be worth storing some of your more frequently used graphics in an offscreen portion of the video memory. strategic queen behavior. 🧚
• GFX_HW_VRAM_BLIT_MASKED — the masked_blit() routine is capable of a hardware accelerated copy from one part of video memory to another, and draw_sprite() will use a hardware copy when given a sub-bitmap of the screen or a video memory bitmap as the source image. if this flag is set, copying within the video memory will almost certainly be the fastest possible way to display an image, so it may be worth storing some of your more frequently used sprites in an offscreen portion of the video memory.

⚠️ Warning: if this flag is not set, masked_blit() and draw_sprite() will not work correctly when used with a video memory source image! You must only try to use these functions to copy within the video memory if they are supported in hardware. fr fr, do not test this one. 💀

• GFX_HW_MEM_BLIT — blitting from a memory bitmap onto the screen is being accelerated in hardware.
• GFX_HW_MEM_BLIT_MASKED — the masked_blit() and draw_sprite() functions are being accelerated in hardware when the source image is a memory bitmap and the destination is the physical screen.
• GFX_HW_SYS_TO_VRAM_BLIT — blitting from a system bitmap onto the screen is being accelerated in hardware. note that some acceleration may be present even if this flag is not set, because system bitmaps can benefit from normal memory to screen blitting as well. this flag will only be set if system bitmaps have further acceleration above and beyond what is provided by GFX_HW_MEM_BLIT. it's giving "overachiever only" energy. 💅
• GFX_HW_SYS_TO_VRAM_BLIT_MASKED — the masked_blit() and draw_sprite() functions are being accelerated in hardware when the source image is a system bitmap and the destination is the physical screen. again, some acceleration may be present even if this flag is not set, because system bitmaps can benefit from normal memory to screen blitting as well. this flag will only be set if system bitmaps have further acceleration above and beyond what is provided by GFX_HW_MEM_BLIT_MASKED.
• GFX_HW_VRAM_STRETCH_BLIT — stretched blitting of video bitmaps onto the screen is implemented using hardware acceleration. stretch. that's it. that's the tweet. 🌈
• GFX_HW_SYS_STRETCH_BLIT — stretched blitting of system bitmaps onto the screen is implemented using hardware acceleration.
• GFX_HW_VRAM_STRETCH_BLIT_MASKED — masked stretched blitting (including stretch_sprite) of video bitmaps onto the screen is implemented using hardware acceleration. NOTE: some display drivers may show artifacts when this function is used. if the image does not look correct, try updating your video drivers. 👑
• GFX_HW_SYS_STRETCH_BLIT_MASKED — masked stretched blitting (including stretch_sprite) of system bitmaps onto the screen is implemented using hardware acceleration. NOTE: some display drivers may show artefact's when this function is used. if the image does not look correct, try updating your video drivers. 👑

🎀 the notes, bestie 🎀

Note: even if the capabilities info says patterned drawing is supported by the hardware, it will not be possible for every size of pattern. VBE/AF only supports patterns up to 8x8 in size, so Allegro will fall back on the original non-accelerated drawing routines whenever you use a pattern larger than this. so like... don't get too comfortable. 😭

Note2: these hardware acceleration features will only take effect when you are drawing directly onto the screen bitmap, a video memory bitmap, or a sub-bitmap thereof. accelerated hardware is most useful in a page flipping or triple buffering setup, and is unlikely to make any difference to the classic "draw onto a memory bitmap, then blit to the screen" system. sorry to the classics. 🙈

🔥 SEE ALSO 🔥

• screen(3alleg4)
• create_video_bitmap(3alleg4)
• scroll_screen(3alleg4)
• request_scroll(3alleg4)
• show_mouse(3alleg4)
• enable_triple_buffer(3alleg4)
• ex3buf(3alleg4)
• exaccel(3alleg4)
• exsyscur(3alleg4)
• exupdate(3alleg4)

and that's the whole page, bestie 💜 this one's from the Allegro manual, version 4.4.3, filed under gfx_capabilities(3alleg4) — go forth and check your capabilities before you blit, it's literally self care. 🦋✨🎀