--- /srv/reproducible-results/rbuild-debian/r-b-build.wlBdFjxb/b1/allegro5_5.2.10.1+dfsg-1_amd64.changes +++ /srv/reproducible-results/rbuild-debian/r-b-build.wlBdFjxb/b2/allegro5_5.2.10.1+dfsg-1_amd64.changes ├── Files │ @@ -1,9 +1,9 @@ │ │ - 2b0876728d33c88d6dd931245e563b8c 1393852 doc optional allegro5-doc_5.2.10.1+dfsg-1_all.deb │ + 4cbe387bf93eac00a696df4df515425f 1400552 doc optional allegro5-doc_5.2.10.1+dfsg-1_all.deb │ 0d0f0e36c802263571c8a4a4d37986e6 19388 libdevel optional liballegro-acodec5-dev_5.2.10.1+dfsg-1_amd64.deb │ 8d1e648c9bc4c82c916d2525be28be63 62524 debug optional liballegro-acodec5.2t64-dbgsym_5.2.10.1+dfsg-1_amd64.deb │ d50d79d7644b1e9c093151f9e7f460f5 38260 libs optional liballegro-acodec5.2t64_5.2.10.1+dfsg-1_amd64.deb │ 88c48ff68fbc70f244e6289381910e53 22164 libdevel optional liballegro-audio5-dev_5.2.10.1+dfsg-1_amd64.deb │ 6510c1199bcb789a150f21f20a92d24c 110092 debug optional liballegro-audio5.2t64-dbgsym_5.2.10.1+dfsg-1_amd64.deb │ 09e68b97528964626a7f9fd05d8e9b9b 61768 libs optional liballegro-audio5.2t64_5.2.10.1+dfsg-1_amd64.deb │ 1392e795640f5aea611fc0be61a01f49 20432 libdevel optional liballegro-dialog5-dev_5.2.10.1+dfsg-1_amd64.deb │ @@ -17,10 +17,10 @@ │ 1399e259e49d926a90ec19b73119cb5c 23612 libs optional liballegro-physfs5.2t64_5.2.10.1+dfsg-1_amd64.deb │ da9f68d4e67494231657f1fe069ad829 19488 libdevel optional liballegro-ttf5-dev_5.2.10.1+dfsg-1_amd64.deb │ 0b3e406b09b165e0e1094460d0646a2d 32212 debug optional liballegro-ttf5.2t64-dbgsym_5.2.10.1+dfsg-1_amd64.deb │ 57da52b6a5515644c87552968ad4687d 28924 libs optional liballegro-ttf5.2t64_5.2.10.1+dfsg-1_amd64.deb │ 69c5613595a2d5ef9e3f8db6ae2395b6 19768 libdevel optional liballegro-video5-dev_5.2.10.1+dfsg-1_amd64.deb │ d92d7f58303a1dea788385c82e05a8c9 39632 debug optional liballegro-video5.2t64-dbgsym_5.2.10.1+dfsg-1_amd64.deb │ ae0881f2a421de07bd741312c4544b0d 32828 libs optional liballegro-video5.2t64_5.2.10.1+dfsg-1_amd64.deb │ - 0c66871380d3de3b82916dcdf4dc4aaa 117028 libdevel optional liballegro5-dev_5.2.10.1+dfsg-1_amd64.deb │ + 539c5b7b4d3254281f7ffdddf394ff97 117028 libdevel optional liballegro5-dev_5.2.10.1+dfsg-1_amd64.deb │ 1662b82e9a21e1fb38f59df73d8a5675 1305612 debug optional liballegro5.2t64-dbgsym_5.2.10.1+dfsg-1_amd64.deb │ f00abcde8884d9fee54cc064f12fde02 437344 libs optional liballegro5.2t64_5.2.10.1+dfsg-1_amd64.deb ├── allegro5-doc_5.2.10.1+dfsg-1_all.deb │ ├── file list │ │ @@ -1,3 +1,3 @@ │ │ -rw-r--r-- 0 0 0 4 2025-01-09 13:52:42.000000 debian-binary │ │ --rw-r--r-- 0 0 0 31656 2025-01-09 13:52:42.000000 control.tar.xz │ │ --rw-r--r-- 0 0 0 1362004 2025-01-09 13:52:42.000000 data.tar.xz │ │ +-rw-r--r-- 0 0 0 31644 2025-01-09 13:52:42.000000 control.tar.xz │ │ +-rw-r--r-- 0 0 0 1368716 2025-01-09 13:52:42.000000 data.tar.xz │ ├── control.tar.xz │ │ ├── control.tar │ │ │ ├── ./control │ │ │ │ @@ -1,13 +1,13 @@ │ │ │ │ Package: allegro5-doc │ │ │ │ Source: allegro5 │ │ │ │ Version: 2:5.2.10.1+dfsg-1 │ │ │ │ Architecture: all │ │ │ │ Maintainer: Debian Games Team │ │ │ │ -Installed-Size: 5495 │ │ │ │ +Installed-Size: 5629 │ │ │ │ Depends: fonts-dejavu-core │ │ │ │ Section: doc │ │ │ │ Priority: optional │ │ │ │ Multi-Arch: foreign │ │ │ │ Homepage: https://liballeg.org/ │ │ │ │ Description: documentation for the Allegro 5 library │ │ │ │ This package contains the Allegro documentation in various formats, │ │ │ ├── ./md5sums │ │ │ │ ├── ./md5sums │ │ │ │ │┄ Files differ │ ├── data.tar.xz │ │ ├── data.tar │ │ │ ├── file list │ │ │ │ @@ -198,65 +198,65 @@ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 5396 2024-12-29 03:52:10.000000 ./usr/share/doc/allegro5-doc/examples/ex_window_maximized.c │ │ │ │ -rw-r--r-- 0 root (0) root (0) 2660 2024-12-29 03:52:10.000000 ./usr/share/doc/allegro5-doc/examples/ex_window_title.c │ │ │ │ -rw-r--r-- 0 root (0) root (0) 6511 2024-12-29 03:52:10.000000 ./usr/share/doc/allegro5-doc/examples/ex_windows.c │ │ │ │ -rw-r--r-- 0 root (0) root (0) 1674 2024-12-29 03:52:10.000000 ./usr/share/doc/allegro5-doc/examples/ex_winfull.c │ │ │ │ -rw-r--r-- 0 root (0) root (0) 19521 2024-12-29 03:52:10.000000 ./usr/share/doc/allegro5-doc/examples/nihgui.cpp │ │ │ │ -rw-r--r-- 0 root (0) root (0) 6456 2024-12-29 03:52:10.000000 ./usr/share/doc/allegro5-doc/examples/nihgui.hpp │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/ │ │ │ │ --rw-r--r-- 0 root (0) root (0) 11397 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/acodec.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 206673 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/audio.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 11782 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/acodec.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 234053 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/audio.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 36350 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/autosuggest.js │ │ │ │ --rw-r--r-- 0 root (0) root (0) 62104 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/color.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 37137 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/config.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 17577 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/direct3d.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 87216 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/display.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 79787 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/events.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 61321 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/file.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 66987 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/color.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 37788 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/config.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 17712 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/direct3d.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 89023 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/display.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 82072 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/events.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 62308 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/file.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 56556 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/fixed.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 87416 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/font.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 42130 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/fshook.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 13213 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/fullscreen_mode.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 95359 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/font.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 42369 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/fshook.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 13488 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/fullscreen_mode.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 17055 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/getting_started.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 214433 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/graphics.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 68519 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/haptic.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 12034 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/image.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 224378 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/graphics.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 69780 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/haptic.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 12423 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/image.html │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/images/ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 21480 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/images/LINE_CAP.png │ │ │ │ -rw-r--r-- 0 root (0) root (0) 15893 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/images/LINE_JOIN.png │ │ │ │ -rw-r--r-- 0 root (0) root (0) 65065 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/images/audio.png │ │ │ │ -rw-r--r-- 0 root (0) root (0) 16058 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/images/primitives1.png │ │ │ │ -rw-r--r-- 0 root (0) root (0) 25805 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/images/primitives2.png │ │ │ │ -rw-r--r-- 0 root (0) root (0) 6773 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/index.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 110785 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/index_all.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 29831 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/joystick.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 21928 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/keyboard.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 35289 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/joystick.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 24132 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/keyboard.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 9013 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/main.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 10382 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/memfile.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 21793 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/memory.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 10027 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/misc.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 13740 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/monitor.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 39798 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/mouse.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 74835 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/native_dialog.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 26550 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/opengl.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 10521 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/memfile.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 24142 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/memory.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 10394 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/misc.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 15363 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/monitor.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 43913 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/mouse.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 80347 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/native_dialog.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 27233 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/opengl.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 3973 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/pandoc.css │ │ │ │ --rw-r--r-- 0 root (0) root (0) 33068 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/path.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 11626 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/physfs.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 31348 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/platform.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 136387 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/primitives.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 38119 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/path.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 11854 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/physfs.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 31625 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/platform.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 145966 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/primitives.html │ │ │ │ -rw-r--r-- 0 root (0) root (0) 72292 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/search_index.js │ │ │ │ --rw-r--r-- 0 root (0) root (0) 40567 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/shader.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 13680 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/state.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 69517 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/system.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 31348 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/threads.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 11589 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/time.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 23605 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/timer.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 20618 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/touch.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 76968 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/transformations.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 91582 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/utf8.html │ │ │ │ --rw-r--r-- 0 root (0) root (0) 29905 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/video.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 45920 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/shader.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 15871 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/state.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 72351 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/system.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 35452 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/threads.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 12633 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/time.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 26749 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/timer.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 22267 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/touch.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 82433 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/transformations.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 104512 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/utf8.html │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 31892 2025-01-09 13:52:42.000000 ./usr/share/doc/allegro5-doc/refman/video.html │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/share/doc-base/ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 300 2025-01-01 19:45:12.000000 ./usr/share/doc-base/allegro5-doc.allegro5 │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/share/man/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/share/man/man3/ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 405 2025-01-09 13:52:42.000000 ./usr/share/man/man3/ALLEGRO_AUDIO_DEPTH.3alleg5.gz │ │ │ │ -rw-r--r-- 0 root (0) root (0) 254 2025-01-09 13:52:42.000000 ./usr/share/man/man3/ALLEGRO_AUDIO_DEVICE.3alleg5.gz │ │ │ │ -rw-r--r-- 0 root (0) root (0) 554 2025-01-09 13:52:42.000000 ./usr/share/man/man3/ALLEGRO_AUDIO_EVENT_TYPE.3alleg5.gz │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/acodec.html │ │ │ │ @@ -209,14 +209,23 @@ │ │ │ │ href="audio.html#al_load_sample_f">al_load_sample_f and must be │ │ │ │ streamed with al_load_audio_stream or al_load_audio_stream_f.

│ │ │ │

  • .voc file streaming is unimplemented.

    • │ │ │ │ │ │ │ │

    Return true on success.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_is_acodec_addon_initialized

    │ │ │ │ 
    bool al_is_acodec_addon_initialized(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true if the acodec addon is initialized, otherwise returns │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -64,14 +64,18 @@ │ │ │ │ │ * Module files (.it, .mod, .s3m, .xm) are often composed with streaming in │ │ │ │ │ mind, and sometimes cannot be easily rendered into a finite length │ │ │ │ │ sample. Therefore they cannot be loaded with _a_l___l_o_a_d___s_a_m_p_l_e/ │ │ │ │ │ _a_l___l_o_a_d___s_a_m_p_l_e___f and must be streamed with _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m or │ │ │ │ │ _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m___f. │ │ │ │ │ * .voc file streaming is unimplemented. │ │ │ │ │ Return true on success. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ ************ aall__iiss__aaccooddeecc__aaddddoonn__iinniittiiaalliizzeedd ************ │ │ │ │ │ bool al_is_acodec_addon_initialized(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true if the acodec addon is initialized, otherwise returns false. │ │ │ │ │ Since: 5.2.6 │ │ │ │ │ ************ aall__ggeett__aalllleeggrroo__aaccooddeecc__vveerrssiioonn ************ │ │ │ │ │ uint32_t al_get_allegro_acodec_version(void) │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/audio.html │ │ │ │ @@ -564,14 +564,19 @@ │ │ │ │ Code

    │ │ │ │

    An ALLEGRO_SAMPLE_ID represents a sample being played via al_play_sample. It can be used to │ │ │ │ later stop the sample with al_stop_sample. The underlying │ │ │ │ ALLEGRO_SAMPLE_INSTANCE can be extracted using al_lock_sample_id.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_install_audio

    │ │ │ │ 
    bool al_install_audio(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Install the audio subsystem.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │ @@ -582,22 +587,40 @@ │ │ │ │ this.

    │ │ │ │ │ │ │ │

    See also: al_reserve_samples, al_uninstall_audio, al_is_audio_installed, al_init_acodec_addon

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_uninstall_audio

    │ │ │ │ 
    void al_uninstall_audio(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Uninstalls the audio subsystem.

    │ │ │ │

    See also: al_install_audio

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_is_audio_installed

    │ │ │ │ 
    bool al_is_audio_installed(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true if al_install_audio was called │ │ │ │ @@ -624,14 +647,23 @@ │ │ │ │ sample instance N │ │ │ │

    Returns true on success, false on error. al_install_audio must have been │ │ │ │ called first.

    │ │ │ │

    See also: al_set_default_mixer, al_play_sample

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_play_sample

    │ │ │ │ 
    bool al_play_sample(ALLEGRO_SAMPLE *spl, float gain, float pan, float speed,
│ │ │ │     ALLEGRO_PLAYMODE loop, ALLEGRO_SAMPLE_ID *ret_id)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Plays a sample on one of the sample instances created by See also: al_load_sample, ALLEGRO_PLAYMODE, ALLEGRO_AUDIO_PAN_NONE, ALLEGRO_SAMPLE_ID, al_stop_sample, al_stop_samples, al_lock_sample_id.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_stop_sample

    │ │ │ │ 
    void al_stop_sample(ALLEGRO_SAMPLE_ID *spl_id)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Stop the sample started by al_play_sample.

    │ │ │ │

    See also: al_stop_samples

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_stop_samples

    │ │ │ │ 
    void al_stop_samples(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Stop all samples started by al_play_sample.

    │ │ │ │

    See also: al_stop_sample

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_lock_sample_id

    │ │ │ │ 
    ALLEGRO_SAMPLE_INSTANCE* al_lock_sample_id(ALLEGRO_SAMPLE_ID *spl_id)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Locks a ALLEGRO_SAMPLE_ID, │ │ │ │ returning the underlying See also: al_play_sample, al_unlock_sample_id

    │ │ │ │

    Since: 5.2.3

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: New API.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_unlock_sample_id

    │ │ │ │ 
    void al_unlock_sample_id(ALLEGRO_SAMPLE_ID *spl_id)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Unlocks a ALLEGRO_SAMPLE_ID, allowing │ │ │ │ @@ -720,14 +780,19 @@ │ │ │ │

    See also: al_play_sample, al_lock_sample_id

    │ │ │ │

    Since: 5.2.3

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: New API.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_play_audio_stream

    │ │ │ │ 
    ALLEGRO_AUDIO_STREAM *al_play_audio_stream(const char *filename)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Loads and plays an audio file, streaming from disk as it is needed. │ │ │ │ This API can only play one audio stream at a time. This requires a │ │ │ │ @@ -747,14 +812,19 @@ │ │ │ │ href="audio.html#al_play_audio_stream_f">al_play_audio_stream_f, al_load_audio_stream

    │ │ │ │

    Since: 5.2.8

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: New API.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_play_audio_stream_f

    │ │ │ │ 
    ALLEGRO_AUDIO_STREAM *al_play_audio_stream_f(ALLEGRO_FILE *fp, const char *ident)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Loads and plays an audio file from ALLEGRO_FILE stream, streaming it is │ │ │ │ @@ -792,14 +862,23 @@ │ │ │ │

    An ALLEGRO_SAMPLE object stores the data necessary for playing │ │ │ │ pre-defined digital audio. It holds a user-specified PCM data buffer and │ │ │ │ information about its format (data length, depth, frequency, channel │ │ │ │ configuration). You can have the same ALLEGRO_SAMPLE playing multiple │ │ │ │ times simultaneously.

    │ │ │ │

    See also: ALLEGRO_SAMPLE_INSTANCE

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_create_sample

    │ │ │ │ 
    ALLEGRO_SAMPLE *al_create_sample(void *buf, unsigned int samples,
│ │ │ │     unsigned int freq, ALLEGRO_AUDIO_DEPTH depth,
│ │ │ │     ALLEGRO_CHANNEL_CONF chan_conf, bool free_buf)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -823,14 +902,23 @@ │ │ │ │ * al_get_audio_depth_size(depth); │ │ │ │ int bytes = samples * sample_size; │ │ │ │ void *buffer = al_malloc(bytes); │ │ │ │

    See also: al_destroy_sample, ALLEGRO_AUDIO_DEPTH, ALLEGRO_CHANNEL_CONF

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_load_sample

    │ │ │ │ 
    ALLEGRO_SAMPLE *al_load_sample(const char *filename)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Loads a few different audio file formats based on their │ │ │ │ extension.

    │ │ │ │ @@ -843,14 +931,23 @@ │ │ │ │

    Note: the allegro_audio library does not support any audio │ │ │ │ file formats by default. You must use the allegro_acodec addon, or │ │ │ │ register your own format handler.

    │ │ │ │ │ │ │ │

    See also: al_register_sample_loader, │ │ │ │ al_init_acodec_addon

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_load_sample_f

    │ │ │ │ 
    ALLEGRO_SAMPLE *al_load_sample_f(ALLEGRO_FILE* fp, const char *ident)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Loads an audio file from an ALLEGRO_FILE stream into an This function will stop any sample instances which may be playing the │ │ │ │ buffer referenced by the ALLEGRO_SAMPLE.

    │ │ │ │

    See also: al_destroy_sample_instance, │ │ │ │ al_stop_sample, al_stop_samples

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_sample_channels

    │ │ │ │ 
    ALLEGRO_CHANNEL_CONF al_get_sample_channels(const ALLEGRO_SAMPLE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the channel configuration of the sample.

    │ │ │ │

    See also:

    │ │ │ │

    Return a pointer to the raw sample data.

    │ │ │ │

    See also: al_get_sample_channels, al_get_sample_depth, al_get_sample_frequency, │ │ │ │ al_get_sample_length

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Advanced Audio

    │ │ │ │

    For more fine-grained control over audio output, here’s a short │ │ │ │ description of the basic concepts:

    │ │ │ │

    Voices represent audio devices on the system. Basically, every audio │ │ │ │ output chain that you want to be heard needs to end up in a voice. As │ │ │ │ voices are on the hardware/driver side of things, there is only limited │ │ │ │ control over their parameters (frequency, sample format, channel │ │ │ │ @@ -1085,126 +1196,212 @@ │ │ │ │ instances may be created from the same ALLEGRO_SAMPLE. An ALLEGRO_SAMPLE │ │ │ │ must not be destroyed while there are instances which reference it.

    │ │ │ │

    To actually produce audio output, an ALLEGRO_SAMPLE_INSTANCE must be │ │ │ │ attached to an ALLEGRO_MIXER │ │ │ │ which eventually reaches an ALLEGRO_VOICE object.

    │ │ │ │

    See also: ALLEGRO_SAMPLE

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_create_sample_instance

    │ │ │ │ 
    ALLEGRO_SAMPLE_INSTANCE *al_create_sample_instance(ALLEGRO_SAMPLE *sample_data)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Creates a sample instance, using the supplied sample data. The │ │ │ │ instance must be attached to a mixer (or voice) in order to actually │ │ │ │ produce output.

    │ │ │ │

    The argument may be NULL. You can then set the sample data later with │ │ │ │ al_set_sample.

    │ │ │ │

    See also: al_destroy_sample_instance

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_destroy_sample_instance

    │ │ │ │ 
    void al_destroy_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Detaches the sample instance from anything it may be attached to and │ │ │ │ frees it (the sample data, i.e. its ALLEGRO_SAMPLE, is not │ │ │ │ freed!).

    │ │ │ │

    See also: al_create_sample_instance

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_play_sample_instance

    │ │ │ │ 
    bool al_play_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Play the sample instance. Returns true on success, false on │ │ │ │ failure.

    │ │ │ │

    See also: al_stop_sample_instance

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_stop_sample_instance

    │ │ │ │ 
    bool al_stop_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Stop an sample instance playing.

    │ │ │ │

    See also: al_play_sample_instance

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_sample_instance_channels

    │ │ │ │ 
    ALLEGRO_CHANNEL_CONF al_get_sample_instance_channels(
│ │ │ │     const ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the channel configuration of the sample instance’s sample │ │ │ │ data.

    │ │ │ │

    See also: ALLEGRO_CHANNEL_CONF.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_sample_instance_depth

    │ │ │ │ 
    ALLEGRO_AUDIO_DEPTH al_get_sample_instance_depth(const ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the audio depth of the sample instance’s sample data.

    │ │ │ │

    See also: ALLEGRO_AUDIO_DEPTH.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_sample_instance_frequency

    │ │ │ │ 
    unsigned int al_get_sample_instance_frequency(const ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the frequency (in Hz) of the sample instance’s sample │ │ │ │ data.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_sample_instance_length

    │ │ │ │ 
    unsigned int al_get_sample_instance_length(const ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the length of the sample instance in sample values. This │ │ │ │ property may differ from the length of the instance’s sample data.

    │ │ │ │

    See also: al_set_sample_instance_length, │ │ │ │ al_get_sample_instance_time

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_sample_instance_length

    │ │ │ │ 
    bool al_set_sample_instance_length(ALLEGRO_SAMPLE_INSTANCE *spl,
│ │ │ │     unsigned int val)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Set the length of the sample instance in sample values. This can be │ │ │ │ used to play only parts of the underlying sample. Be careful not to │ │ │ │ exceed the actual length of the sample data, though.

    │ │ │ │

    Return true on success, false on failure. Will fail if the sample │ │ │ │ instance is currently playing.

    │ │ │ │

    See also: al_get_sample_instance_length

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_sample_instance_position

    │ │ │ │ 
    unsigned int al_get_sample_instance_position(const ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Get the playback position of a sample instance.

    │ │ │ │

    See also: al_set_sample_instance_position

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_sample_instance_position

    │ │ │ │ 
    bool al_set_sample_instance_position(ALLEGRO_SAMPLE_INSTANCE *spl,
│ │ │ │     unsigned int val)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Set the playback position of a sample instance.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: al_get_sample_instance_position

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_sample_instance_speed

    │ │ │ │ 
    float al_get_sample_instance_speed(const ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the relative playback speed of the sample instance.

    │ │ │ │

    See also:

    │ │ │ │

    Set the relative playback speed of the sample instance. 1.0 means │ │ │ │ normal speed.

    │ │ │ │

    Return true on success, false on failure. Will fail if the sample │ │ │ │ instance is attached directly to a voice.

    │ │ │ │

    See also: al_get_sample_instance_speed

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_sample_instance_gain

    │ │ │ │ 
    float al_get_sample_instance_gain(const ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the playback gain of the sample instance.

    │ │ │ │

    See also: al_set_sample_instance_gain

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_sample_instance_gain

    │ │ │ │ 
    bool al_set_sample_instance_gain(ALLEGRO_SAMPLE_INSTANCE *spl, float val)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Set the playback gain of the sample instance.

    │ │ │ │

    Returns true on success, false on failure. Will fail if the sample │ │ │ │ instance is attached directly to a voice.

    │ │ │ │

    See also: al_get_sample_instance_gain

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_sample_instance_pan

    │ │ │ │ 
    float al_get_sample_instance_pan(const ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Get the pan value of the sample instance.

    │ │ │ │

    See also: │ │ │ │

    Returns true on success, false on failure. Will fail if the sample │ │ │ │ instance is attached directly to a voice.

    │ │ │ │

    See also: al_get_sample_instance_pan, │ │ │ │ ALLEGRO_AUDIO_PAN_NONE

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_sample_instance_time

    │ │ │ │ 
    float al_get_sample_instance_time(const ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the length of the sample instance in seconds, assuming a │ │ │ │ playback speed of 1.0.

    │ │ │ │

    See also: al_get_sample_instance_length

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_sample_instance_playmode

    │ │ │ │ 
    ALLEGRO_PLAYMODE al_get_sample_instance_playmode(const ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the playback mode of the sample instance.

    │ │ │ │ @@ -1294,36 +1528,57 @@ │ │ │ │ href="https://github.com/liballeg/allegro5/blob/master/addons/audio/kcm_instance.c#L518">Source │ │ │ │ Code

    │ │ │ │

    Set the playback mode of the sample instance.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: ALLEGRO_PLAYMODE, │ │ │ │ al_get_sample_instance_playmode

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_sample_instance_playing

    │ │ │ │ 
    bool al_get_sample_instance_playing(const ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return true if the sample instance is in the playing state. This may │ │ │ │ be true even if the instance is not attached to anything.

    │ │ │ │

    See also: al_set_sample_instance_playing

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_sample_instance_playing

    │ │ │ │ 
    bool al_set_sample_instance_playing(ALLEGRO_SAMPLE_INSTANCE *spl, bool val)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Change whether the sample instance is playing.

    │ │ │ │

    The instance does not need to be attached to anything (since: │ │ │ │ 5.1.8).

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: al_get_sample_instance_playing

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_sample_instance_attached

    │ │ │ │ 
    bool al_get_sample_instance_attached(const ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return whether the sample instance is attached to something.

    │ │ │ │ @@ -1343,14 +1598,19 @@ │ │ │ │

    Returns true on success.

    │ │ │ │

    See also: al_attach_sample_instance_to_mixer, │ │ │ │ al_attach_sample_instance_to_voice, │ │ │ │ al_get_sample_instance_attached

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_sample

    │ │ │ │ 
    ALLEGRO_SAMPLE *al_get_sample(ALLEGRO_SAMPLE_INSTANCE *spl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the sample data that the sample instance plays.

    │ │ │ │

    Note this returns a pointer to an internal structure, not │ │ │ │ @@ -1358,14 +1618,23 @@ │ │ │ │ have passed to al_set_sample. │ │ │ │ However, the sample buffer of the returned ALLEGRO_SAMPLE will be the │ │ │ │ same as the one that was used to create the sample (passed to al_create_sample). You can use al_get_sample_data on the │ │ │ │ return value to retrieve and compare it.

    │ │ │ │

    See also: al_set_sample

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_sample

    │ │ │ │ 
    bool al_set_sample(ALLEGRO_SAMPLE_INSTANCE *spl, ALLEGRO_SAMPLE *data)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Change the sample data that a sample instance plays. This can be │ │ │ │ quite an involved process.

    │ │ │ │ @@ -1378,14 +1647,23 @@ │ │ │ │ Reattaching may not always succeed.

    │ │ │ │

    On success, the sample remains stopped. The playback position and │ │ │ │ loop end points are reset to their default values. The loop mode remains │ │ │ │ unchanged.

    │ │ │ │

    Returns true on success, false on failure. On failure, the sample │ │ │ │ will be stopped and detached from its parent.

    │ │ │ │

    See also: al_get_sample

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_sample_instance_channel_matrix

    │ │ │ │ 
    bool al_set_sample_instance_channel_matrix(ALLEGRO_SAMPLE_INSTANCE *spl, const float *matrix)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Set the matrix used to mix the channels coming from this instance │ │ │ │ @@ -1411,14 +1689,19 @@ │ │ │ │

    Returns true on success, false on failure (e.g. if this is not │ │ │ │ attached to a mixer).

    │ │ │ │

    Since: 5.2.3

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: New API.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Audio streams

    │ │ │ │

    ALLEGRO_AUDIO_STREAM

    │ │ │ │ 
    typedef struct ALLEGRO_AUDIO_STREAM ALLEGRO_AUDIO_STREAM;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    An ALLEGRO_AUDIO_STREAM object is used to stream generated audio to │ │ │ │ @@ -1467,14 +1750,23 @@ │ │ │ │ } │ │ │ │

    If the stream is created by al_load_audio_stream or al_play_audio_stream then it │ │ │ │ will also generate an ALLEGRO_EVENT_AUDIO_STREAM_FINISHED │ │ │ │ event if it reaches the end of the file and is not set to loop.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_create_audio_stream

    │ │ │ │ 
    ALLEGRO_AUDIO_STREAM *al_create_audio_stream(size_t fragment_count,
│ │ │ │     unsigned int frag_samples, unsigned int freq, ALLEGRO_AUDIO_DEPTH depth,
│ │ │ │     ALLEGRO_CHANNEL_CONF chan_conf)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -1523,14 +1815,23 @@ │ │ │ │
    │ │ │ │

    Note: Unlike many Allegro objects, audio streams are not │ │ │ │ implicitly destroyed when Allegro is shut down. You must destroy them │ │ │ │ manually with al_destroy_audio_stream │ │ │ │ before the audio system is shut down.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_load_audio_stream

    │ │ │ │ 
    ALLEGRO_AUDIO_STREAM *al_load_audio_stream(const char *filename,
│ │ │ │     size_t buffer_count, unsigned int samples)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Loads an audio file from disk as it is needed.

    │ │ │ │ @@ -1548,14 +1849,23 @@ │ │ │ │ file formats by default. You must use the allegro_acodec addon, or │ │ │ │ register your own format handler.

    │ │ │ │ │ │ │ │

    See also: al_load_audio_stream_f, al_register_audio_stream_loader, │ │ │ │ al_init_acodec_addon

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_load_audio_stream_f

    │ │ │ │ 
    ALLEGRO_AUDIO_STREAM *al_load_audio_stream_f(ALLEGRO_FILE* fp, const char *ident,
│ │ │ │     size_t buffer_count, unsigned int samples)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Loads an audio file from │ │ │ │

    Note: If the stream is still attached to a mixer or voice, │ │ │ │ al_detach_audio_stream │ │ │ │ is automatically called on it first.

    │ │ │ │ │ │ │ │

    See also: al_drain_audio_stream.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_audio_stream_event_source

    │ │ │ │ 
    ALLEGRO_EVENT_SOURCE *al_get_audio_stream_event_source(
│ │ │ │     ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Retrieve the associated event source.

    │ │ │ │

    See al_get_audio_stream_fragment │ │ │ │ for a description of the ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT │ │ │ │ event that audio streams emit.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_drain_audio_stream

    │ │ │ │ 
    void al_drain_audio_stream(ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    You should call this to finalise an audio stream that you will no │ │ │ │ longer be feeding, to wait for all pending buffers to finish playing. │ │ │ │ The stream’s playing state will change to false.

    │ │ │ │

    See also: al_destroy_audio_stream

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_rewind_audio_stream

    │ │ │ │ 
    bool al_rewind_audio_stream(ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Set the streaming file playing position to the beginning. Returns │ │ │ │ true on success. Currently this can only be called on streams created │ │ │ │ with al_load_audio_stream, │ │ │ │ al_play_audio_stream, al_load_audio_stream_f or │ │ │ │ al_play_audio_stream_f.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_audio_stream_frequency

    │ │ │ │ 
    unsigned int al_get_audio_stream_frequency(const ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the stream frequency (in Hz).

    │ │ │ │ @@ -1660,14 +2002,19 @@ │ │ │ │ href="audio.html#allegro_audio_depth">ALLEGRO_AUDIO_DEPTH.

    │ │ │ │

    al_get_audio_stream_length

    │ │ │ │ 
    unsigned int al_get_audio_stream_length(const ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the stream length in samples.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_audio_stream_speed

    │ │ │ │ 
    float al_get_audio_stream_speed(const ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the relative playback speed of the stream.

    │ │ │ │

    See also: 

    float al_get_audio_stream_gain(const ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the playback gain of the stream.

    │ │ │ │

    See also: al_set_audio_stream_gain.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_audio_stream_gain

    │ │ │ │ 
    bool al_set_audio_stream_gain(ALLEGRO_AUDIO_STREAM *stream, float val)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Set the playback gain of the stream.

    │ │ │ │

    Returns true on success, false on failure. Will fail if the audio │ │ │ │ stream is attached directly to a voice.

    │ │ │ │

    See also: al_get_audio_stream_gain.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_audio_stream_pan

    │ │ │ │ 
    float al_get_audio_stream_pan(const ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Get the pan value of the stream.

    │ │ │ │

    See also: │ │ │ │

    Returns true on success, false on failure. Will fail if the audio │ │ │ │ stream is attached directly to a voice.

    │ │ │ │

    See also: al_get_audio_stream_pan, │ │ │ │ ALLEGRO_AUDIO_PAN_NONE

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_audio_stream_playing

    │ │ │ │ 
    bool al_get_audio_stream_playing(const ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return true if the stream is playing.

    │ │ │ │

    See also: al_set_audio_stream_playing.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_audio_stream_playing

    │ │ │ │ 
    bool al_set_audio_stream_playing(ALLEGRO_AUDIO_STREAM *stream, bool val)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Change whether the stream is playing.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: al_get_audio_stream_playing

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_audio_stream_playmode

    │ │ │ │ 
    ALLEGRO_PLAYMODE al_get_audio_stream_playmode(
│ │ │ │     const ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the playback mode of the stream.

    │ │ │ │ @@ -1760,14 +2142,23 @@ │ │ │ │ href="https://github.com/liballeg/allegro5/blob/master/addons/audio/kcm_stream.c#L461">Source │ │ │ │ Code

    │ │ │ │

    Set the playback mode of the stream.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: ALLEGRO_PLAYMODE, │ │ │ │ al_get_audio_stream_playmode.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_audio_stream_attached

    │ │ │ │ 
    bool al_get_audio_stream_attached(const ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return whether the stream is attached to something.

    │ │ │ │

    See also: Detach the stream from whatever it’s attached to, if anything.

    │ │ │ │

    See also: al_attach_audio_stream_to_mixer, │ │ │ │ al_attach_audio_stream_to_voice, │ │ │ │ al_get_audio_stream_attached.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_audio_stream_played_samples

    │ │ │ │ 
    uint64_t al_get_audio_stream_played_samples(const ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Get the number of samples consumed by the parent since the audio │ │ │ │ @@ -1830,25 +2226,43 @@ │ │ │ │ href="audio.html#al_get_audio_stream_frequency">al_get_audio_stream_frequency, │ │ │ │ al_get_audio_stream_channels, │ │ │ │ al_get_audio_stream_depth, │ │ │ │ al_get_audio_stream_length

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_audio_stream_fragment

    │ │ │ │ 
    bool al_set_audio_stream_fragment(ALLEGRO_AUDIO_STREAM *stream, void *val)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    This function needs to be called for every successful call of al_get_audio_stream_fragment │ │ │ │ to indicate that the buffer (pointed to by val) is filled │ │ │ │ with new data.

    │ │ │ │

    See also: al_get_audio_stream_fragment

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_audio_stream_fragments

    │ │ │ │ 
    unsigned int al_get_audio_stream_fragments(const ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the number of fragments this stream uses. This is the same │ │ │ │ @@ -1882,14 +2296,19 @@ │ │ │ │ href="audio.html#al_load_audio_stream_f">al_load_audio_stream_f or │ │ │ │ al_play_audio_stream_f.

    │ │ │ │

    See also: al_get_audio_stream_position_secs, │ │ │ │ al_get_audio_stream_length_secs

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_audio_stream_position_secs

    │ │ │ │ 
    double al_get_audio_stream_position_secs(ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the position of the stream in seconds. Currently this can only │ │ │ │ @@ -1897,14 +2316,19 @@ │ │ │ │ href="audio.html#al_load_audio_stream">al_load_audio_stream, al_play_audio_stream, al_load_audio_stream_f or │ │ │ │ al_play_audio_stream_f.

    │ │ │ │

    See also: al_get_audio_stream_length_secs

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_audio_stream_length_secs

    │ │ │ │ 
    double al_get_audio_stream_length_secs(ALLEGRO_AUDIO_STREAM *stream)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the length of the stream in seconds, if known. Otherwise │ │ │ │ @@ -1913,28 +2337,38 @@ │ │ │ │ href="audio.html#al_load_audio_stream">al_load_audio_stream, al_play_audio_stream, al_load_audio_stream_f or │ │ │ │ al_play_audio_stream_f.

    │ │ │ │

    See also: al_get_audio_stream_position_secs

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_audio_stream_loop_secs

    │ │ │ │ 
    bool al_set_audio_stream_loop_secs(ALLEGRO_AUDIO_STREAM *stream,
│ │ │ │     double start, double end)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Sets the loop points for the stream in seconds. Currently this can │ │ │ │ only be called on streams created with al_load_audio_stream, al_play_audio_stream, al_load_audio_stream_f or │ │ │ │ al_play_audio_stream_f.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_audio_stream_channel_matrix

    │ │ │ │

    Source Code

    │ │ │ │

    Like al_set_sample_instance_channel_matrix │ │ │ │ but for streams.

    │ │ │ │

    Since: 5.2.3

    │ │ │ │ @@ -2145,14 +2579,21 @@ │ │ │ │ Code

    │ │ │ │

    An opaque datatype that represents a recording device.

    │ │ │ │

    Since: 5.1.1

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: The API may need a slight redesign.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_AUDIO_RECORDER_EVENT

    │ │ │ │ 
    typedef struct ALLEGRO_AUDIO_RECORDER_EVENT ALLEGRO_AUDIO_RECORDER_EVENT;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Structure that holds the audio recorder event data. Every event type │ │ │ │ @@ -2168,14 +2609,21 @@ │ │ │ │

    Since 5.1.1

    │ │ │ │

    See also: al_get_audio_recorder_event

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: The API may need a slight redesign.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_create_audio_recorder

    │ │ │ │ 
    ALLEGRO_AUDIO_RECORDER *al_create_audio_recorder(size_t fragment_count,
│ │ │ │     unsigned int samples, unsigned int frequency,
│ │ │ │     ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf)
    │ │ │ │

    Source │ │ │ │ @@ -2208,14 +2656,21 @@ │ │ │ │ href="audio.html#al_start_audio_recorder">al_start_audio_recorder.

    │ │ │ │

    On failure, returns NULL.

    │ │ │ │

    Since: 5.1.1

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: The API may need a slight redesign.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_start_audio_recorder

    │ │ │ │ 
    bool al_start_audio_recorder(ALLEGRO_AUDIO_RECORDER *r)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Begin recording into the fragment buffer. Once a complete fragment │ │ │ │ @@ -2226,14 +2681,21 @@ │ │ │ │ event will be triggered.

    │ │ │ │

    Returns true if it was able to begin recording.

    │ │ │ │

    Since: 5.1.1

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: The API may need a slight redesign.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_stop_audio_recorder

    │ │ │ │ 
    void al_stop_audio_recorder(ALLEGRO_AUDIO_RECORDER *r)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Stop capturing audio data. Note that the audio recorder is still │ │ │ │ @@ -2272,28 +2734,42 @@ │ │ │ │

    Returns the event as an ALLEGRO_AUDIO_RECORDER_EVENT.

    │ │ │ │

    Since: 5.1.1

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: The API may need a slight redesign.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_audio_recorder_event_source

    │ │ │ │ 
    ALLEGRO_EVENT_SOURCE *al_get_audio_recorder_event_source(ALLEGRO_AUDIO_RECORDER *r)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the event source for the recorder that generates the various │ │ │ │ recording events.

    │ │ │ │

    Since: 5.1.1

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: The API may need a slight redesign.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_destroy_audio_recorder

    │ │ │ │ 
    void al_destroy_audio_recorder(ALLEGRO_AUDIO_RECORDER *r)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Destroys the audio recorder and frees all resources associated with │ │ │ │ @@ -2301,62 +2777,98 @@ │ │ │ │

    You may receive events after the recorder has been destroyed. They │ │ │ │ must be ignored, as the fragment buffer will no longer be valid.

    │ │ │ │

    Since: 5.1.1

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: The API may need a slight redesign.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Audio devices

    │ │ │ │

    ALLEGRO_AUDIO_DEVICE

    │ │ │ │ 
    typedef struct ALLEGRO_AUDIO_DEVICE ALLEGRO_AUDIO_DEVICE;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    An opaque datatype that represents an audio device.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_num_audio_output_devices

    │ │ │ │ 
    int al_get_num_audio_output_devices()
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Get the number of available audio output devices on the system.

    │ │ │ │

    Since: 5.2.8

    │ │ │ │

    return -1 for unsupported drivers.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_audio_output_device

    │ │ │ │ 
    const ALLEGRO_AUDIO_DEVICE* al_get_audio_output_device(int index)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Get the output audio device of the specified index.

    │ │ │ │

    Since: 5.2.8

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_audio_device_name

    │ │ │ │ 
    const char* al_get_audio_device_name(const ALLEGRO_AUDIO_DEVICE * device)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Get the user friendly display name of the device.

    │ │ │ │

    Since: 5.2.8

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Voices

    │ │ │ │

    ALLEGRO_VOICE

    │ │ │ │ 
    typedef struct ALLEGRO_VOICE ALLEGRO_VOICE;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    A voice represents an audio device on the system, which may be a real │ │ │ │ device, or an abstract device provided by the operating system. To play │ │ │ │ back audio, you would attach a mixer, sample instance or audio stream to │ │ │ │ a voice.

    │ │ │ │

    See also: ALLEGRO_MIXER, ALLEGRO_SAMPLE, ALLEGRO_AUDIO_STREAM

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_create_voice

    │ │ │ │ 
    ALLEGRO_VOICE *al_create_voice(unsigned int freq,
│ │ │ │     ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -2372,24 +2884,42 @@ │ │ │ │ make sure to not rely on the parameters passed to this function, but │ │ │ │ instead query the returned voice for the actual settings.

    │ │ │ │

    Reasonable default arguments are:

    │ │ │ │ 
    al_create_voice(44100, ALLEGRO_AUDIO_DEPTH_INT16, ALLEGRO_CHANNEL_CONF_2)
    │ │ │ │

    See also: al_destroy_voice

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_destroy_voice

    │ │ │ │ 
    void al_destroy_voice(ALLEGRO_VOICE *voice)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Destroys the voice and deallocates it from the digital driver. Does │ │ │ │ nothing if the voice is NULL.

    │ │ │ │

    See also: al_create_voice

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_detach_voice

    │ │ │ │ 
    void al_detach_voice(ALLEGRO_VOICE *voice)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Detaches the mixer, sample instance or audio stream from the │ │ │ │ @@ -2417,26 +2947,42 @@ │ │ │ │ The stream position, speed, gain and panning cannot be changed. At this │ │ │ │ time, we don’t recommend attaching audio streams directly to voices. Use │ │ │ │ a mixer inbetween.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: al_detach_voice, │ │ │ │ al_voice_has_attachments

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_attach_mixer_to_voice

    │ │ │ │ 
    bool al_attach_mixer_to_voice(ALLEGRO_MIXER *mixer, ALLEGRO_VOICE *voice)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Attaches a mixer to a voice. It must have the same frequency and │ │ │ │ channel configuration, but the depth may be different.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: al_detach_voice, │ │ │ │ al_voice_has_attachments

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_attach_sample_instance_to_voice

    │ │ │ │ 
    bool al_attach_sample_instance_to_voice(ALLEGRO_SAMPLE_INSTANCE *spl,
│ │ │ │     ALLEGRO_VOICE *voice)
    │ │ │ │

    Source │ │ │ │ @@ -2448,14 +2994,21 @@ │ │ │ │ preloading sample data.

    │ │ │ │

    At this time, we don’t recommend attaching sample instances directly │ │ │ │ to voices. Use a mixer inbetween.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: al_detach_voice, │ │ │ │ al_voice_has_attachments

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_voice_frequency

    │ │ │ │ 
    unsigned int al_get_voice_frequency(const ALLEGRO_VOICE *voice)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the frequency of the voice (in Hz), e.g. 44100.

    │ │ │ │ @@ -2482,26 +3035,36 @@ │ │ │ │ class="sourceCode c">bool al_get_voice_playing(const ALLEGRO_VOICE *voice) │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return true if the voice is currently playing.

    │ │ │ │

    See also: al_set_voice_playing

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_voice_playing

    │ │ │ │ 
    bool al_set_voice_playing(ALLEGRO_VOICE *voice, bool val)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Change whether a voice is playing or not. This can only work if the │ │ │ │ voice has a non-streaming object attached to it, e.g. a sample instance. │ │ │ │ On success the voice’s current sample position is reset.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: al_get_voice_playing

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_voice_position

    │ │ │ │ 
    unsigned int al_get_voice_position(const ALLEGRO_VOICE *voice)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    When the voice has a non-streaming object attached to it, e.g. a │ │ │ │ @@ -2547,14 +3110,23 @@ │ │ │ │ accordingly. You can control the quality of this conversion using │ │ │ │ ALLEGRO_MIXER_QUALITY.

    │ │ │ │

    When going from mono to stereo (and above), the mixer reduces the │ │ │ │ volume of both channels by sqrt(2). When going from stereo │ │ │ │ (and above) to mono, the mixer reduces the volume of the left and right │ │ │ │ channels by sqrt(2) before adding them to the center │ │ │ │ channel (if present).

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_MIXER_QUALITY

    │ │ │ │ 
    enum ALLEGRO_MIXER_QUALITY
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ │ │ │ │

    For convenience:

    │ │ │ │ │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_AUDIO_PAN_NONE

    │ │ │ │ 
    #define ALLEGRO_AUDIO_PAN_NONE      (-1000.0f)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    A special value for the pan property of sample instances and audio │ │ │ │ @@ -2903,14 +3582,19 @@ │ │ │ │

    ALLEGRO_AUDIO_PAN_NONE is different from a pan value of 0.0 │ │ │ │ (centered) because, when panning is enabled, we try to maintain a │ │ │ │ constant sound power level as a sample is panned from left to right. A │ │ │ │ sound coming out of one speaker should sound as loud as it does when │ │ │ │ split over two speakers. As a consequence, a sample with pan value 0.0 │ │ │ │ will be 3 dB softer than the original level.

    │ │ │ │

    (Please correct us if this is wrong.)

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_CHANNEL_CONF

    │ │ │ │ 
    enum ALLEGRO_CHANNEL_CONF
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Speaker configuration (mono, stereo, 2.1, etc).

    │ │ │ │ @@ -2919,14 +3603,23 @@ │ │ │ │
  • ALLEGRO_CHANNEL_CONF_2
    • │ │ │ │
  • ALLEGRO_CHANNEL_CONF_3
    • │ │ │ │
  • ALLEGRO_CHANNEL_CONF_4
    • │ │ │ │
  • ALLEGRO_CHANNEL_CONF_5_1
    • │ │ │ │
  • ALLEGRO_CHANNEL_CONF_6_1
    • │ │ │ │
  • ALLEGRO_CHANNEL_CONF_7_1
    • │ │ │ │ │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_PLAYMODE

    │ │ │ │ 
    enum ALLEGRO_PLAYMODE
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Sample and stream playback mode.

    │ │ │ │ @@ -2940,14 +3633,23 @@ │ │ │ │ respects the loop end point. │ │ │ │
  • ALLEGRO_PLAYMODE_BIDIR - the sample is played from start to finish │ │ │ │ (or between the two loop points). When it reaches the end, it reverses │ │ │ │ the playback direction and plays until it reaches the beginning when it │ │ │ │ reverses the direction back to normal. This is mode is rarely supported │ │ │ │ for streams.
    • │ │ │ │ │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_AUDIO_EVENT_TYPE

    │ │ │ │ 
    enum ALLEGRO_AUDIO_EVENT_TYPE
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Events sent by size_t al_get_audio_depth_size(ALLEGRO_AUDIO_DEPTH depth) │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the size of a sample, in bytes, for the given format. The │ │ │ │ format is one of the values listed under ALLEGRO_AUDIO_DEPTH.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_channel_count

    │ │ │ │ 
    size_t al_get_channel_count(ALLEGRO_CHANNEL_CONF conf)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the number of channels for the given channel configuration, │ │ │ │ which is one of the values listed under ALLEGRO_CHANNEL_CONF.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_fill_silence

    │ │ │ │ 
    void al_fill_silence(void *buf, unsigned int samples,
│ │ │ │     ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Fill a buffer with silence, for the given format and channel │ │ │ │ configuration. The buffer must have enough space for the given number of │ │ │ │ samples, and be properly aligned.

    │ │ │ │

    Since: 5.1.8

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    │ │ │ │ Allegro version 5.2.10 │ │ │ │ - Last updated: 2025-01-09 13:52:42 UTC │ │ │ │

    │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -232,28 +232,38 @@ │ │ │ │ │ the basic API only supports one such audio stream playing at once. │ │ │ │ │ ********** AALLLLEEGGRROO__SSAAMMPPLLEE__IIDD ********** │ │ │ │ │ typedef struct ALLEGRO_SAMPLE_ID ALLEGRO_SAMPLE_ID; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ An ALLEGRO_SAMPLE_ID represents a sample being played via _a_l___p_l_a_y___s_a_m_p_l_e. It │ │ │ │ │ can be used to later stop the sample with _a_l___s_t_o_p___s_a_m_p_l_e. The underlying │ │ │ │ │ ALLEGRO_SAMPLE_INSTANCE can be extracted using _a_l___l_o_c_k___s_a_m_p_l_e___i_d. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___s_i_m_p_l_e_._c │ │ │ │ │ ********** aall__iinnssttaallll__aauuddiioo ********** │ │ │ │ │ bool al_install_audio(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Install the audio subsystem. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ Note: most users will call _a_l___r_e_s_e_r_v_e___s_a_m_p_l_e_s and │ │ │ │ │ _a_l___i_n_i_t___a_c_o_d_e_c___a_d_d_o_n after this. │ │ │ │ │ See also: _a_l___r_e_s_e_r_v_e___s_a_m_p_l_e_s, _a_l___u_n_i_n_s_t_a_l_l___a_u_d_i_o, _a_l___i_s___a_u_d_i_o___i_n_s_t_a_l_l_e_d, │ │ │ │ │ _a_l___i_n_i_t___a_c_o_d_e_c___a_d_d_o_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___d_e_v_i_c_e_s_._c │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ ********** aall__uunniinnssttaallll__aauuddiioo ********** │ │ │ │ │ void al_uninstall_audio(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Uninstalls the audio subsystem. │ │ │ │ │ See also: _a_l___i_n_s_t_a_l_l___a_u_d_i_o │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ ********** aall__iiss__aauuddiioo__iinnssttaalllleedd ********** │ │ │ │ │ bool al_is_audio_installed(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true if _a_l___i_n_s_t_a_l_l___a_u_d_i_o was called previously and returned │ │ │ │ │ successfully. │ │ │ │ │ ********** aall__rreesseerrvvee__ssaammpplleess ********** │ │ │ │ │ bool al_reserve_samples(int reserve_samples) │ │ │ │ │ @@ -270,14 +280,18 @@ │ │ │ │ │ / sample instance 2 │ │ │ │ │ default voice <-- default mixer <--- . │ │ │ │ │ \ . │ │ │ │ │ sample instance N │ │ │ │ │ Returns true on success, false on error. _a_l___i_n_s_t_a_l_l___a_u_d_i_o must have been called │ │ │ │ │ first. │ │ │ │ │ See also: _a_l___s_e_t___d_e_f_a_u_l_t___m_i_x_e_r, _a_l___p_l_a_y___s_a_m_p_l_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___p_r_o_p_s_._c_p_p │ │ │ │ │ + * _e_x___r_e_s_a_m_p_l_e___t_e_s_t_._c │ │ │ │ │ ********** aall__ppllaayy__ssaammppllee ********** │ │ │ │ │ bool al_play_sample(ALLEGRO_SAMPLE *spl, float gain, float pan, float speed, │ │ │ │ │ ALLEGRO_PLAYMODE loop, ALLEGRO_SAMPLE_ID *ret_id) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Plays a sample on one of the sample instances created by _a_l___r_e_s_e_r_v_e___s_a_m_p_l_e_s. │ │ │ │ │ Returns true on success, false on failure. Playback may fail because all the │ │ │ │ │ reserved sample instances are currently used. │ │ │ │ │ @@ -290,24 +304,34 @@ │ │ │ │ │ ALLEGRO_PLAYMODE_BIDIR │ │ │ │ │ * ret_id - if non-NULL the variable which this points to will be assigned │ │ │ │ │ an id representing the sample being played. If _a_l___p_l_a_y___s_a_m_p_l_e returns │ │ │ │ │ false, then the contents of ret_id are invalid and must not be used as │ │ │ │ │ argument to other functions. │ │ │ │ │ See also: _a_l___l_o_a_d___s_a_m_p_l_e, _A_L_L_E_G_R_O___P_L_A_Y_M_O_D_E, _A_L_L_E_G_R_O___A_U_D_I_O___P_A_N___N_O_N_E, │ │ │ │ │ _A_L_L_E_G_R_O___S_A_M_P_L_E___I_D, _a_l___s_t_o_p___s_a_m_p_l_e, _a_l___s_t_o_p___s_a_m_p_l_e_s, _a_l___l_o_c_k___s_a_m_p_l_e___i_d. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__ssttoopp__ssaammppllee ********** │ │ │ │ │ void al_stop_sample(ALLEGRO_SAMPLE_ID *spl_id) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Stop the sample started by _a_l___p_l_a_y___s_a_m_p_l_e. │ │ │ │ │ See also: _a_l___s_t_o_p___s_a_m_p_l_e_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__ssttoopp__ssaammpplleess ********** │ │ │ │ │ void al_stop_samples(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Stop all samples started by _a_l___p_l_a_y___s_a_m_p_l_e. │ │ │ │ │ See also: _a_l___s_t_o_p___s_a_m_p_l_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___s_i_m_p_l_e_._c │ │ │ │ │ ********** aall__lloocckk__ssaammppllee__iidd ********** │ │ │ │ │ ALLEGRO_SAMPLE_INSTANCE* al_lock_sample_id(ALLEGRO_SAMPLE_ID *spl_id) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Locks a _A_L_L_E_G_R_O___S_A_M_P_L_E___I_D, returning the underlying _A_L_L_E_G_R_O___S_A_M_P_L_E___I_N_S_T_A_N_C_E. │ │ │ │ │ This allows you to adjust the various properties of the instance (such as │ │ │ │ │ volume, pan, etc) while the sound is playing. │ │ │ │ │ This function will return NULL if the sound corresponding to the id is no │ │ │ │ │ @@ -315,24 +339,28 @@ │ │ │ │ │ While locked, ALLEGRO_SAMPLE_ID will be unavailable to additional calls to │ │ │ │ │ _a_l___p_l_a_y___s_a_m_p_l_e, even if the sound stops while locked. To put the │ │ │ │ │ ALLEGRO_SAMPLE_ID back into the pool for reuse, make sure to call │ │ │ │ │ al_unlock_sample_id when you’re done with the instance. │ │ │ │ │ See also: _a_l___p_l_a_y___s_a_m_p_l_e, _a_l___u_n_l_o_c_k___s_a_m_p_l_e___i_d │ │ │ │ │ Since: 5.2.3 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: New API. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___s_i_m_p_l_e_._c │ │ │ │ │ ********** aall__uunnlloocckk__ssaammppllee__iidd ********** │ │ │ │ │ void al_unlock_sample_id(ALLEGRO_SAMPLE_ID *spl_id) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Unlocks a _A_L_L_E_G_R_O___S_A_M_P_L_E___I_D, allowing future calls to _a_l___p_l_a_y___s_a_m_p_l_e to reuse │ │ │ │ │ it if possible. Note that after the id is unlocked, the _A_L_L_E_G_R_O___S_A_M_P_L_E___I_N_S_T_A_N_C_E │ │ │ │ │ that was previously returned by _a_l___l_o_c_k___s_a_m_p_l_e___i_d will possibly be playing a │ │ │ │ │ different sound, so you should only use it after locking the id again. │ │ │ │ │ See also: _a_l___p_l_a_y___s_a_m_p_l_e, _a_l___l_o_c_k___s_a_m_p_l_e___i_d │ │ │ │ │ Since: 5.2.3 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: New API. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___s_i_m_p_l_e_._c │ │ │ │ │ ********** aall__ppllaayy__aauuddiioo__ssttrreeaamm ********** │ │ │ │ │ ALLEGRO_AUDIO_STREAM *al_play_audio_stream(const char *filename) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Loads and plays an audio file, streaming from disk as it is needed. This API │ │ │ │ │ can only play one audio stream at a time. This requires a default mixer to be │ │ │ │ │ set, which is typically done via _a_l___r_e_s_e_r_v_e___s_a_m_p_l_e_s, but can also be done via │ │ │ │ │ _a_l___s_e_t___d_e_f_a_u_l_t___m_i_x_e_r. │ │ │ │ │ @@ -341,14 +369,16 @@ │ │ │ │ │ down. │ │ │ │ │ NNoottee:: the allegro_audio library does not support any audio file │ │ │ │ │ formats by default. You must use the allegro_acodec addon, or │ │ │ │ │ register your own format handler. │ │ │ │ │ See also: _a_l___p_l_a_y___a_u_d_i_o___s_t_r_e_a_m___f, _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m │ │ │ │ │ Since: 5.2.8 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: New API. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___s_i_m_p_l_e_._c │ │ │ │ │ ********** aall__ppllaayy__aauuddiioo__ssttrreeaamm__ff ********** │ │ │ │ │ ALLEGRO_AUDIO_STREAM *al_play_audio_stream_f(ALLEGRO_FILE *fp, const char │ │ │ │ │ *ident) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Loads and plays an audio file from _A_L_L_E_G_R_O___F_I_L_E stream, streaming it is needed. │ │ │ │ │ This API can only play one audio stream at a time. This requires a default │ │ │ │ │ mixer to be set, which is typically done via _a_l___r_e_s_e_r_v_e___s_a_m_p_l_e_s, but can also │ │ │ │ │ @@ -371,14 +401,18 @@ │ │ │ │ │ typedef struct ALLEGRO_SAMPLE ALLEGRO_SAMPLE; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ An ALLEGRO_SAMPLE object stores the data necessary for playing pre-defined │ │ │ │ │ digital audio. It holds a user-specified PCM data buffer and information about │ │ │ │ │ its format (data length, depth, frequency, channel configuration). You can have │ │ │ │ │ the same ALLEGRO_SAMPLE playing multiple times simultaneously. │ │ │ │ │ See also: _A_L_L_E_G_R_O___S_A_M_P_L_E___I_N_S_T_A_N_C_E │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___g_l_e_x_t_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ ********** aall__ccrreeaattee__ssaammppllee ********** │ │ │ │ │ ALLEGRO_SAMPLE *al_create_sample(void *buf, unsigned int samples, │ │ │ │ │ unsigned int freq, ALLEGRO_AUDIO_DEPTH depth, │ │ │ │ │ ALLEGRO_CHANNEL_CONF chan_conf, bool free_buf) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Create a sample data structure from the supplied buffer. If free_buf is true │ │ │ │ │ then the buffer will be freed with _a_l___f_r_e_e when the sample data structure is │ │ │ │ │ @@ -392,26 +426,34 @@ │ │ │ │ │ A single sample, then, refers to the LR pair in this example. │ │ │ │ │ To allocate a buffer of the correct size, you can use something like this: │ │ │ │ │ int sample_size = al_get_channel_count(chan_conf) │ │ │ │ │ * al_get_audio_depth_size(depth); │ │ │ │ │ int bytes = samples * sample_size; │ │ │ │ │ void *buffer = al_malloc(bytes); │ │ │ │ │ See also: _a_l___d_e_s_t_r_o_y___s_a_m_p_l_e, _A_L_L_E_G_R_O___A_U_D_I_O___D_E_P_T_H, _A_L_L_E_G_R_O___C_H_A_N_N_E_L___C_O_N_F │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__llooaadd__ssaammppllee ********** │ │ │ │ │ ALLEGRO_SAMPLE *al_load_sample(const char *filename) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Loads a few different audio file formats based on their extension. │ │ │ │ │ Note that this stores the entire file in memory at once, which may be time │ │ │ │ │ consuming. To read the file as it is needed, use _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m or │ │ │ │ │ _a_l___p_l_a_y___a_u_d_i_o___s_t_r_e_a_m. │ │ │ │ │ Returns the sample on success, NULL on failure. │ │ │ │ │ NNoottee:: the allegro_audio library does not support any audio file │ │ │ │ │ formats by default. You must use the allegro_acodec addon, or │ │ │ │ │ register your own format handler. │ │ │ │ │ See also: _a_l___r_e_g_i_s_t_e_r___s_a_m_p_l_e___l_o_a_d_e_r, _a_l___i_n_i_t___a_c_o_d_e_c___a_d_d_o_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__llooaadd__ssaammppllee__ff ********** │ │ │ │ │ ALLEGRO_SAMPLE *al_load_sample_f(ALLEGRO_FILE* fp, const char *ident) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Loads an audio file from an _A_L_L_E_G_R_O___F_I_L_E stream into an _A_L_L_E_G_R_O___S_A_M_P_L_E. The │ │ │ │ │ file type is determined by the passed ‘ident’ parameter, which is a file name │ │ │ │ │ extension including the leading dot. │ │ │ │ │ Note that this stores the entire file in memory at once, which may be time │ │ │ │ │ @@ -447,14 +489,18 @@ │ │ │ │ │ void al_destroy_sample(ALLEGRO_SAMPLE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Free the sample data structure. If it was created with the free_buf parameter │ │ │ │ │ set to true, then the buffer will be freed with _a_l___f_r_e_e. │ │ │ │ │ This function will stop any sample instances which may be playing the buffer │ │ │ │ │ referenced by the _A_L_L_E_G_R_O___S_A_M_P_L_E. │ │ │ │ │ See also: _a_l___d_e_s_t_r_o_y___s_a_m_p_l_e___i_n_s_t_a_n_c_e, _a_l___s_t_o_p___s_a_m_p_l_e, _a_l___s_t_o_p___s_a_m_p_l_e_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__ggeett__ssaammppllee__cchhaannnneellss ********** │ │ │ │ │ ALLEGRO_CHANNEL_CONF al_get_sample_channels(const ALLEGRO_SAMPLE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the channel configuration of the sample. │ │ │ │ │ See also: _A_L_L_E_G_R_O___C_H_A_N_N_E_L___C_O_N_F, _a_l___g_e_t___s_a_m_p_l_e___d_e_p_t_h, _a_l___g_e_t___s_a_m_p_l_e___f_r_e_q_u_e_n_c_y, │ │ │ │ │ _a_l___g_e_t___s_a_m_p_l_e___l_e_n_g_t_h, _a_l___g_e_t___s_a_m_p_l_e___d_a_t_a │ │ │ │ │ ********** aall__ggeett__ssaammppllee__ddeepptthh ********** │ │ │ │ │ @@ -477,14 +523,16 @@ │ │ │ │ │ _a_l___g_e_t___s_a_m_p_l_e___d_a_t_a │ │ │ │ │ ********** aall__ggeett__ssaammppllee__ddaattaa ********** │ │ │ │ │ void *al_get_sample_data(const ALLEGRO_SAMPLE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return a pointer to the raw sample data. │ │ │ │ │ See also: _a_l___g_e_t___s_a_m_p_l_e___c_h_a_n_n_e_l_s, _a_l___g_e_t___s_a_m_p_l_e___d_e_p_t_h, _a_l___g_e_t___s_a_m_p_l_e___f_r_e_q_u_e_n_c_y, │ │ │ │ │ _a_l___g_e_t___s_a_m_p_l_e___l_e_n_g_t_h │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___t_i_m_e_r_._c │ │ │ │ │ ************ AAddvvaanncceedd AAuuddiioo ************ │ │ │ │ │ For more fine-grained control over audio output, here’s a short description of │ │ │ │ │ the basic concepts: │ │ │ │ │ Voices represent audio devices on the system. Basically, every audio output │ │ │ │ │ chain that you want to be heard needs to end up in a voice. As voices are on │ │ │ │ │ the hardware/driver side of things, there is only limited control over their │ │ │ │ │ parameters (frequency, sample format, channel configuration). The number of │ │ │ │ │ @@ -564,108 +612,154 @@ │ │ │ │ │ instance is currently playing or paused is also one of its properties. │ │ │ │ │ An instance uses the data from an _A_L_L_E_G_R_O___S_A_M_P_L_E object. Multiple instances may │ │ │ │ │ be created from the same ALLEGRO_SAMPLE. An ALLEGRO_SAMPLE must not be │ │ │ │ │ destroyed while there are instances which reference it. │ │ │ │ │ To actually produce audio output, an ALLEGRO_SAMPLE_INSTANCE must be attached │ │ │ │ │ to an _A_L_L_E_G_R_O___M_I_X_E_R which eventually reaches an _A_L_L_E_G_R_O___V_O_I_C_E object. │ │ │ │ │ See also: _A_L_L_E_G_R_O___S_A_M_P_L_E │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__ccrreeaattee__ssaammppllee__iinnssttaannccee ********** │ │ │ │ │ ALLEGRO_SAMPLE_INSTANCE *al_create_sample_instance(ALLEGRO_SAMPLE *sample_data) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Creates a sample instance, using the supplied sample data. The instance must be │ │ │ │ │ attached to a mixer (or voice) in order to actually produce output. │ │ │ │ │ The argument may be NULL. You can then set the sample data later with │ │ │ │ │ _a_l___s_e_t___s_a_m_p_l_e. │ │ │ │ │ See also: _a_l___d_e_s_t_r_o_y___s_a_m_p_l_e___i_n_s_t_a_n_c_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__ddeessttrrooyy__ssaammppllee__iinnssttaannccee ********** │ │ │ │ │ void al_destroy_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Detaches the sample instance from anything it may be attached to and frees it │ │ │ │ │ (the sample data, i.e. its ALLEGRO_SAMPLE, is nnoott freed!). │ │ │ │ │ See also: _a_l___c_r_e_a_t_e___s_a_m_p_l_e___i_n_s_t_a_n_c_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__ppllaayy__ssaammppllee__iinnssttaannccee ********** │ │ │ │ │ bool al_play_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Play the sample instance. Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___s_t_o_p___s_a_m_p_l_e___i_n_s_t_a_n_c_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__ssttoopp__ssaammppllee__iinnssttaannccee ********** │ │ │ │ │ bool al_stop_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Stop an sample instance playing. │ │ │ │ │ See also: _a_l___p_l_a_y___s_a_m_p_l_e___i_n_s_t_a_n_c_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__ggeett__ssaammppllee__iinnssttaannccee__cchhaannnneellss ********** │ │ │ │ │ ALLEGRO_CHANNEL_CONF al_get_sample_instance_channels( │ │ │ │ │ const ALLEGRO_SAMPLE_INSTANCE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the channel configuration of the sample instance’s sample data. │ │ │ │ │ See also: _A_L_L_E_G_R_O___C_H_A_N_N_E_L___C_O_N_F. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c_._c │ │ │ │ │ ********** aall__ggeett__ssaammppllee__iinnssttaannccee__ddeepptthh ********** │ │ │ │ │ ALLEGRO_AUDIO_DEPTH al_get_sample_instance_depth(const ALLEGRO_SAMPLE_INSTANCE │ │ │ │ │ *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the audio depth of the sample instance’s sample data. │ │ │ │ │ See also: _A_L_L_E_G_R_O___A_U_D_I_O___D_E_P_T_H. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ ********** aall__ggeett__ssaammppllee__iinnssttaannccee__ffrreeqquueennccyy ********** │ │ │ │ │ unsigned int al_get_sample_instance_frequency(const ALLEGRO_SAMPLE_INSTANCE │ │ │ │ │ *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the frequency (in Hz) of the sample instance’s sample data. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ ********** aall__ggeett__ssaammppllee__iinnssttaannccee__lleennggtthh ********** │ │ │ │ │ unsigned int al_get_sample_instance_length(const ALLEGRO_SAMPLE_INSTANCE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the length of the sample instance in sample values. This property may │ │ │ │ │ differ from the length of the instance’s sample data. │ │ │ │ │ See also: _a_l___s_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___l_e_n_g_t_h, _a_l___g_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___t_i_m_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___p_r_o_p_s_._c_p_p │ │ │ │ │ + * _e_x___a_u_d_i_o___s_i_m_p_l_e_._c │ │ │ │ │ ********** aall__sseett__ssaammppllee__iinnssttaannccee__lleennggtthh ********** │ │ │ │ │ bool al_set_sample_instance_length(ALLEGRO_SAMPLE_INSTANCE *spl, │ │ │ │ │ unsigned int val) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the length of the sample instance in sample values. This can be used to │ │ │ │ │ play only parts of the underlying sample. Be careful not to exceed the actual │ │ │ │ │ length of the sample data, though. │ │ │ │ │ Return true on success, false on failure. Will fail if the sample instance is │ │ │ │ │ currently playing. │ │ │ │ │ See also: _a_l___g_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___l_e_n_g_t_h │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___p_r_o_p_s_._c_p_p │ │ │ │ │ ********** aall__ggeett__ssaammppllee__iinnssttaannccee__ppoossiittiioonn ********** │ │ │ │ │ unsigned int al_get_sample_instance_position(const ALLEGRO_SAMPLE_INSTANCE │ │ │ │ │ *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get the playback position of a sample instance. │ │ │ │ │ See also: _a_l___s_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___p_o_s_i_t_i_o_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__sseett__ssaammppllee__iinnssttaannccee__ppoossiittiioonn ********** │ │ │ │ │ bool al_set_sample_instance_position(ALLEGRO_SAMPLE_INSTANCE *spl, │ │ │ │ │ unsigned int val) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the playback position of a sample instance. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___g_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___p_o_s_i_t_i_o_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___s_i_m_p_l_e_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__ggeett__ssaammppllee__iinnssttaannccee__ssppeeeedd ********** │ │ │ │ │ float al_get_sample_instance_speed(const ALLEGRO_SAMPLE_INSTANCE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the relative playback speed of the sample instance. │ │ │ │ │ See also: _a_l___s_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___s_p_e_e_d │ │ │ │ │ ********** aall__sseett__ssaammppllee__iinnssttaannccee__ssppeeeedd ********** │ │ │ │ │ bool al_set_sample_instance_speed(ALLEGRO_SAMPLE_INSTANCE *spl, float val) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the relative playback speed of the sample instance. 1.0 means normal speed. │ │ │ │ │ Return true on success, false on failure. Will fail if the sample instance is │ │ │ │ │ attached directly to a voice. │ │ │ │ │ See also: _a_l___g_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___s_p_e_e_d │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___p_r_o_p_s_._c_p_p │ │ │ │ │ + * _e_x___a_u_d_i_o___s_i_m_p_l_e_._c │ │ │ │ │ ********** aall__ggeett__ssaammppllee__iinnssttaannccee__ggaaiinn ********** │ │ │ │ │ float al_get_sample_instance_gain(const ALLEGRO_SAMPLE_INSTANCE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the playback gain of the sample instance. │ │ │ │ │ See also: _a_l___s_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___g_a_i_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__sseett__ssaammppllee__iinnssttaannccee__ggaaiinn ********** │ │ │ │ │ bool al_set_sample_instance_gain(ALLEGRO_SAMPLE_INSTANCE *spl, float val) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the playback gain of the sample instance. │ │ │ │ │ Returns true on success, false on failure. Will fail if the sample instance is │ │ │ │ │ attached directly to a voice. │ │ │ │ │ See also: _a_l___g_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___g_a_i_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___p_r_o_p_s_._c_p_p │ │ │ │ │ ********** aall__ggeett__ssaammppllee__iinnssttaannccee__ppaann ********** │ │ │ │ │ float al_get_sample_instance_pan(const ALLEGRO_SAMPLE_INSTANCE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get the pan value of the sample instance. │ │ │ │ │ See also: _a_l___s_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___p_a_n. │ │ │ │ │ ********** aall__sseett__ssaammppllee__iinnssttaannccee__ppaann ********** │ │ │ │ │ bool al_set_sample_instance_pan(ALLEGRO_SAMPLE_INSTANCE *spl, float val) │ │ │ │ │ @@ -675,69 +769,91 @@ │ │ │ │ │ speaker; 0.0 means the sample is centre balanced. A special value │ │ │ │ │ _A_L_L_E_G_R_O___A_U_D_I_O___P_A_N___N_O_N_E disables panning and plays the sample at its original │ │ │ │ │ level. This will be louder than a pan value of 0.0. │ │ │ │ │ Note: panning samples with more than two channels doesn’t work yet. │ │ │ │ │ Returns true on success, false on failure. Will fail if the sample instance is │ │ │ │ │ attached directly to a voice. │ │ │ │ │ See also: _a_l___g_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___p_a_n, _A_L_L_E_G_R_O___A_U_D_I_O___P_A_N___N_O_N_E │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___p_r_o_p_s_._c_p_p │ │ │ │ │ + * _e_x___a_u_d_i_o___s_i_m_p_l_e_._c │ │ │ │ │ ********** aall__ggeett__ssaammppllee__iinnssttaannccee__ttiimmee ********** │ │ │ │ │ float al_get_sample_instance_time(const ALLEGRO_SAMPLE_INSTANCE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the length of the sample instance in seconds, assuming a playback speed │ │ │ │ │ of 1.0. │ │ │ │ │ See also: _a_l___g_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___l_e_n_g_t_h │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__ggeett__ssaammppllee__iinnssttaannccee__ppllaayymmooddee ********** │ │ │ │ │ ALLEGRO_PLAYMODE al_get_sample_instance_playmode(const ALLEGRO_SAMPLE_INSTANCE │ │ │ │ │ *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the playback mode of the sample instance. │ │ │ │ │ See also: _A_L_L_E_G_R_O___P_L_A_Y_M_O_D_E, _a_l___s_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___p_l_a_y_m_o_d_e │ │ │ │ │ ********** aall__sseett__ssaammppllee__iinnssttaannccee__ppllaayymmooddee ********** │ │ │ │ │ bool al_set_sample_instance_playmode(ALLEGRO_SAMPLE_INSTANCE *spl, │ │ │ │ │ ALLEGRO_PLAYMODE val) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the playback mode of the sample instance. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _A_L_L_E_G_R_O___P_L_A_Y_M_O_D_E, _a_l___g_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___p_l_a_y_m_o_d_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c_._c │ │ │ │ │ ********** aall__ggeett__ssaammppllee__iinnssttaannccee__ppllaayyiinngg ********** │ │ │ │ │ bool al_get_sample_instance_playing(const ALLEGRO_SAMPLE_INSTANCE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return true if the sample instance is in the playing state. This may be true │ │ │ │ │ even if the instance is not attached to anything. │ │ │ │ │ See also: _a_l___s_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___p_l_a_y_i_n_g │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__sseett__ssaammppllee__iinnssttaannccee__ppllaayyiinngg ********** │ │ │ │ │ bool al_set_sample_instance_playing(ALLEGRO_SAMPLE_INSTANCE *spl, bool val) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Change whether the sample instance is playing. │ │ │ │ │ The instance does not need to be attached to anything (since: 5.1.8). │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___g_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___p_l_a_y_i_n_g │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___p_r_o_p_s_._c_p_p │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__ggeett__ssaammppllee__iinnssttaannccee__aattttaacchheedd ********** │ │ │ │ │ bool al_get_sample_instance_attached(const ALLEGRO_SAMPLE_INSTANCE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return whether the sample instance is attached to something. │ │ │ │ │ See also: _a_l___a_t_t_a_c_h___s_a_m_p_l_e___i_n_s_t_a_n_c_e___t_o___m_i_x_e_r, │ │ │ │ │ _a_l___a_t_t_a_c_h___s_a_m_p_l_e___i_n_s_t_a_n_c_e___t_o___v_o_i_c_e, _a_l___d_e_t_a_c_h___s_a_m_p_l_e___i_n_s_t_a_n_c_e │ │ │ │ │ ********** aall__ddeettaacchh__ssaammppllee__iinnssttaannccee ********** │ │ │ │ │ bool al_detach_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Detach the sample instance from whatever it’s attached to, if anything. │ │ │ │ │ Returns true on success. │ │ │ │ │ See also: _a_l___a_t_t_a_c_h___s_a_m_p_l_e___i_n_s_t_a_n_c_e___t_o___m_i_x_e_r, │ │ │ │ │ _a_l___a_t_t_a_c_h___s_a_m_p_l_e___i_n_s_t_a_n_c_e___t_o___v_o_i_c_e, _a_l___g_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___a_t_t_a_c_h_e_d │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__ggeett__ssaammppllee ********** │ │ │ │ │ ALLEGRO_SAMPLE *al_get_sample(ALLEGRO_SAMPLE_INSTANCE *spl) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the sample data that the sample instance plays. │ │ │ │ │ Note this returns a pointer to an internal structure, nnoott the _A_L_L_E_G_R_O___S_A_M_P_L_E │ │ │ │ │ that you may have passed to _a_l___s_e_t___s_a_m_p_l_e. However, the sample buffer of the │ │ │ │ │ returned ALLEGRO_SAMPLE will be the same as the one that was used to create the │ │ │ │ │ sample (passed to _a_l___c_r_e_a_t_e___s_a_m_p_l_e). You can use _a_l___g_e_t___s_a_m_p_l_e___d_a_t_a on the │ │ │ │ │ return value to retrieve and compare it. │ │ │ │ │ See also: _a_l___s_e_t___s_a_m_p_l_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__sseett__ssaammppllee ********** │ │ │ │ │ bool al_set_sample(ALLEGRO_SAMPLE_INSTANCE *spl, ALLEGRO_SAMPLE *data) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Change the sample data that a sample instance plays. This can be quite an │ │ │ │ │ involved process. │ │ │ │ │ First, the sample is stopped if it is not already. │ │ │ │ │ Next, if data is NULL, the sample is detached from its parent (if any). │ │ │ │ │ @@ -746,14 +862,18 @@ │ │ │ │ │ the same frequency, depth and channel configuration. Reattaching may not always │ │ │ │ │ succeed. │ │ │ │ │ On success, the sample remains stopped. The playback position and loop end │ │ │ │ │ points are reset to their default values. The loop mode remains unchanged. │ │ │ │ │ Returns true on success, false on failure. On failure, the sample will be │ │ │ │ │ stopped and detached from its parent. │ │ │ │ │ See also: _a_l___g_e_t___s_a_m_p_l_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c_._c │ │ │ │ │ ********** aall__sseett__ssaammppllee__iinnssttaannccee__cchhaannnneell__mmaattrriixx ********** │ │ │ │ │ bool al_set_sample_instance_channel_matrix(ALLEGRO_SAMPLE_INSTANCE *spl, const │ │ │ │ │ float *matrix) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the matrix used to mix the channels coming from this instance into the │ │ │ │ │ mixer it is attached to. Normally Allegro derives the values of this matrix │ │ │ │ │ from the gain and pan settings, as well as the channel configurations of this │ │ │ │ │ @@ -773,14 +893,16 @@ │ │ │ │ │ }; │ │ │ │ │ │ │ │ │ │ al_set_sample_instance_channel_matrix(instance, matrix); │ │ │ │ │ Returns true on success, false on failure (e.g. if this is not attached to a │ │ │ │ │ mixer). │ │ │ │ │ Since: 5.2.3 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: New API. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c_._c │ │ │ │ │ ************ AAuuddiioo ssttrreeaammss ************ │ │ │ │ │ ********** AALLLLEEGGRROO__AAUUDDIIOO__SSTTRREEAAMM ********** │ │ │ │ │ typedef struct ALLEGRO_AUDIO_STREAM ALLEGRO_AUDIO_STREAM; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ An ALLEGRO_AUDIO_STREAM object is used to stream generated audio to the sound │ │ │ │ │ device, in real-time. This is done by reading from a buffer, which is split │ │ │ │ │ into a number of fragments. Whenever a fragment has finished playing, the user │ │ │ │ │ @@ -811,14 +933,18 @@ │ │ │ │ │ while ((buf = al_get_audio_stream_fragment(stream))) { │ │ │ │ │ al_fill_silence(buf, samples_per_buffer, depth, channel_conf); │ │ │ │ │ al_set_audio_stream_fragment(stream, buf); │ │ │ │ │ } │ │ │ │ │ If the stream is created by _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m or _a_l___p_l_a_y___a_u_d_i_o___s_t_r_e_a_m then │ │ │ │ │ it will also generate an _A_L_L_E_G_R_O___E_V_E_N_T___A_U_D_I_O___S_T_R_E_A_M___F_I_N_I_S_H_E_D event if it │ │ │ │ │ reaches the end of the file and is not set to loop. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___r_e_s_a_m_p_l_e___t_e_s_t_._c │ │ │ │ │ ********** aall__ccrreeaattee__aauuddiioo__ssttrreeaamm ********** │ │ │ │ │ ALLEGRO_AUDIO_STREAM *al_create_audio_stream(size_t fragment_count, │ │ │ │ │ unsigned int frag_samples, unsigned int freq, ALLEGRO_AUDIO_DEPTH depth, │ │ │ │ │ ALLEGRO_CHANNEL_CONF chan_conf) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Creates an _A_L_L_E_G_R_O___A_U_D_I_O___S_T_R_E_A_M. The stream will be set to play by default. It │ │ │ │ │ will feed audio data from a buffer, which is split into a number of fragments. │ │ │ │ │ @@ -851,14 +977,18 @@ │ │ │ │ │ al_get_audio_depth_size(depth); │ │ │ │ │ samples = bytes_per_fragment / sample_size; │ │ │ │ │ The size of the complete buffer is: │ │ │ │ │ buffer_size = bytes_per_fragment * fragment_count │ │ │ │ │ NNoottee:: Unlike many Allegro objects, audio streams are not implicitly │ │ │ │ │ destroyed when Allegro is shut down. You must destroy them manually │ │ │ │ │ with _a_l___d_e_s_t_r_o_y___a_u_d_i_o___s_t_r_e_a_m before the audio system is shut down. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___r_e_s_a_m_p_l_e___t_e_s_t_._c │ │ │ │ │ + * _e_x___s_y_n_t_h_._c_p_p │ │ │ │ │ ********** aall__llooaadd__aauuddiioo__ssttrreeaamm ********** │ │ │ │ │ ALLEGRO_AUDIO_STREAM *al_load_audio_stream(const char *filename, │ │ │ │ │ size_t buffer_count, unsigned int samples) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Loads an audio file from disk as it is needed. │ │ │ │ │ Unlike regular streams, the one returned by this function need not be fed by │ │ │ │ │ the user; the library will automatically read more of the file as it is needed. │ │ │ │ │ @@ -868,14 +998,18 @@ │ │ │ │ │ details. │ │ │ │ │ Returns the stream on success, NULL on failure. │ │ │ │ │ NNoottee:: the allegro_audio library does not support any audio file │ │ │ │ │ formats by default. You must use the allegro_acodec addon, or │ │ │ │ │ register your own format handler. │ │ │ │ │ See also: _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m___f, _a_l___r_e_g_i_s_t_e_r___a_u_d_i_o___s_t_r_e_a_m___l_o_a_d_e_r, │ │ │ │ │ _a_l___i_n_i_t___a_c_o_d_e_c___a_d_d_o_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___p_p_._c │ │ │ │ │ + * _e_x___s_t_r_e_a_m___s_e_e_k_._c │ │ │ │ │ ********** aall__llooaadd__aauuddiioo__ssttrreeaamm__ff ********** │ │ │ │ │ ALLEGRO_AUDIO_STREAM *al_load_audio_stream_f(ALLEGRO_FILE* fp, const char │ │ │ │ │ *ident, │ │ │ │ │ size_t buffer_count, unsigned int samples) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Loads an audio file from _A_L_L_E_G_R_O___F_I_L_E stream as it is needed. │ │ │ │ │ Unlike regular streams, the one returned by this function need not be fed by │ │ │ │ │ @@ -898,35 +1032,49 @@ │ │ │ │ │ void al_destroy_audio_stream(ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Destroy an audio stream which was created with _a_l___c_r_e_a_t_e___a_u_d_i_o___s_t_r_e_a_m or │ │ │ │ │ _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m. │ │ │ │ │ NNoottee:: If the stream is still attached to a mixer or voice, │ │ │ │ │ _a_l___d_e_t_a_c_h___a_u_d_i_o___s_t_r_e_a_m is automatically called on it first. │ │ │ │ │ See also: _a_l___d_r_a_i_n___a_u_d_i_o___s_t_r_e_a_m. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___r_e_s_a_m_p_l_e___t_e_s_t_._c │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__eevveenntt__ssoouurrccee ********** │ │ │ │ │ ALLEGRO_EVENT_SOURCE *al_get_audio_stream_event_source( │ │ │ │ │ ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Retrieve the associated event source. │ │ │ │ │ See _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___f_r_a_g_m_e_n_t for a description of the │ │ │ │ │ _A_L_L_E_G_R_O___E_V_E_N_T___A_U_D_I_O___S_T_R_E_A_M___F_R_A_G_M_E_N_T event that audio streams emit. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___r_e_s_a_m_p_l_e___t_e_s_t_._c │ │ │ │ │ ********** aall__ddrraaiinn__aauuddiioo__ssttrreeaamm ********** │ │ │ │ │ void al_drain_audio_stream(ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ You should call this to finalise an audio stream that you will no longer be │ │ │ │ │ feeding, to wait for all pending buffers to finish playing. The stream’s │ │ │ │ │ playing state will change to false. │ │ │ │ │ See also: _a_l___d_e_s_t_r_o_y___a_u_d_i_o___s_t_r_e_a_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___r_e_s_a_m_p_l_e___t_e_s_t_._c │ │ │ │ │ + * _e_x___r_e_c_o_r_d_._c │ │ │ │ │ ********** aall__rreewwiinndd__aauuddiioo__ssttrreeaamm ********** │ │ │ │ │ bool al_rewind_audio_stream(ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the streaming file playing position to the beginning. Returns true on │ │ │ │ │ success. Currently this can only be called on streams created with │ │ │ │ │ _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m, _a_l___p_l_a_y___a_u_d_i_o___s_t_r_e_a_m, _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m___f or │ │ │ │ │ _a_l___p_l_a_y___a_u_d_i_o___s_t_r_e_a_m___f. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___s_e_e_k_._c │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__ffrreeqquueennccyy ********** │ │ │ │ │ unsigned int al_get_audio_stream_frequency(const ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the stream frequency (in Hz). │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__cchhaannnneellss ********** │ │ │ │ │ ALLEGRO_CHANNEL_CONF al_get_audio_stream_channels( │ │ │ │ │ const ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ @@ -939,14 +1087,16 @@ │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the stream audio depth. │ │ │ │ │ See also: _A_L_L_E_G_R_O___A_U_D_I_O___D_E_P_T_H. │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__lleennggtthh ********** │ │ │ │ │ unsigned int al_get_audio_stream_length(const ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the stream length in samples. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___s_e_e_k_._c │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__ssppeeeedd ********** │ │ │ │ │ float al_get_audio_stream_speed(const ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the relative playback speed of the stream. │ │ │ │ │ See also: _a_l___s_e_t___a_u_d_i_o___s_t_r_e_a_m___s_p_e_e_d. │ │ │ │ │ ********** aall__sseett__aauuddiioo__ssttrreeaamm__ssppeeeedd ********** │ │ │ │ │ bool al_set_audio_stream_speed(ALLEGRO_AUDIO_STREAM *stream, float val) │ │ │ │ │ @@ -956,21 +1106,26 @@ │ │ │ │ │ attached directly to a voice. │ │ │ │ │ See also: _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___s_p_e_e_d. │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__ggaaiinn ********** │ │ │ │ │ float al_get_audio_stream_gain(const ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the playback gain of the stream. │ │ │ │ │ See also: _a_l___s_e_t___a_u_d_i_o___s_t_r_e_a_m___g_a_i_n. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__sseett__aauuddiioo__ssttrreeaamm__ggaaiinn ********** │ │ │ │ │ bool al_set_audio_stream_gain(ALLEGRO_AUDIO_STREAM *stream, float val) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the playback gain of the stream. │ │ │ │ │ Returns true on success, false on failure. Will fail if the audio stream is │ │ │ │ │ attached directly to a voice. │ │ │ │ │ See also: _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___g_a_i_n. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_y_n_t_h_._c_p_p │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__ppaann ********** │ │ │ │ │ float al_get_audio_stream_pan(const ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get the pan value of the stream. │ │ │ │ │ See also: _a_l___s_e_t___a_u_d_i_o___s_t_r_e_a_m___p_a_n. │ │ │ │ │ ********** aall__sseett__aauuddiioo__ssttrreeaamm__ppaann ********** │ │ │ │ │ bool al_set_audio_stream_pan(ALLEGRO_AUDIO_STREAM *stream, float val) │ │ │ │ │ @@ -979,50 +1134,66 @@ │ │ │ │ │ only through the left speaker; +1.0 means only through the right speaker; 0.0 │ │ │ │ │ means the sample is centre balanced. A special value _A_L_L_E_G_R_O___A_U_D_I_O___P_A_N___N_O_N_E │ │ │ │ │ disables panning and plays the stream at its original level. This will be │ │ │ │ │ louder than a pan value of 0.0. │ │ │ │ │ Returns true on success, false on failure. Will fail if the audio stream is │ │ │ │ │ attached directly to a voice. │ │ │ │ │ See also: _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___p_a_n, _A_L_L_E_G_R_O___A_U_D_I_O___P_A_N___N_O_N_E │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_y_n_t_h_._c_p_p │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__ppllaayyiinngg ********** │ │ │ │ │ bool al_get_audio_stream_playing(const ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return true if the stream is playing. │ │ │ │ │ See also: _a_l___s_e_t___a_u_d_i_o___s_t_r_e_a_m___p_l_a_y_i_n_g. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___r_e_c_o_r_d_._c │ │ │ │ │ + * _e_x___s_t_r_e_a_m___s_e_e_k_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__sseett__aauuddiioo__ssttrreeaamm__ppllaayyiinngg ********** │ │ │ │ │ bool al_set_audio_stream_playing(ALLEGRO_AUDIO_STREAM *stream, bool val) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Change whether the stream is playing. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___p_l_a_y_i_n_g │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___s_i_m_p_l_e_._c │ │ │ │ │ + * _e_x___r_e_c_o_r_d_._c │ │ │ │ │ + * _e_x___s_t_r_e_a_m___s_e_e_k_._c │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__ppllaayymmooddee ********** │ │ │ │ │ ALLEGRO_PLAYMODE al_get_audio_stream_playmode( │ │ │ │ │ const ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the playback mode of the stream. │ │ │ │ │ See also: _A_L_L_E_G_R_O___P_L_A_Y_M_O_D_E, _a_l___s_e_t___a_u_d_i_o___s_t_r_e_a_m___p_l_a_y_m_o_d_e. │ │ │ │ │ ********** aall__sseett__aauuddiioo__ssttrreeaamm__ppllaayymmooddee ********** │ │ │ │ │ bool al_set_audio_stream_playmode(ALLEGRO_AUDIO_STREAM *stream, │ │ │ │ │ ALLEGRO_PLAYMODE val) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the playback mode of the stream. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _A_L_L_E_G_R_O___P_L_A_Y_M_O_D_E, _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___p_l_a_y_m_o_d_e. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___p_p_._c │ │ │ │ │ + * _e_x___s_t_r_e_a_m___s_e_e_k_._c │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__aattttaacchheedd ********** │ │ │ │ │ bool al_get_audio_stream_attached(const ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return whether the stream is attached to something. │ │ │ │ │ See also: _a_l___a_t_t_a_c_h___a_u_d_i_o___s_t_r_e_a_m___t_o___m_i_x_e_r, _a_l___a_t_t_a_c_h___a_u_d_i_o___s_t_r_e_a_m___t_o___v_o_i_c_e, │ │ │ │ │ _a_l___d_e_t_a_c_h___a_u_d_i_o___s_t_r_e_a_m. │ │ │ │ │ ********** aall__ddeettaacchh__aauuddiioo__ssttrreeaamm ********** │ │ │ │ │ bool al_detach_audio_stream(ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Detach the stream from whatever it’s attached to, if anything. │ │ │ │ │ See also: _a_l___a_t_t_a_c_h___a_u_d_i_o___s_t_r_e_a_m___t_o___m_i_x_e_r, _a_l___a_t_t_a_c_h___a_u_d_i_o___s_t_r_e_a_m___t_o___v_o_i_c_e, │ │ │ │ │ _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___a_t_t_a_c_h_e_d. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__ppllaayyeedd__ssaammpplleess ********** │ │ │ │ │ uint64_t al_get_audio_stream_played_samples(const ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get the number of samples consumed by the parent since the audio stream was │ │ │ │ │ started. │ │ │ │ │ Since: 5.1.8 │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__ffrraaggmmeenntt ********** │ │ │ │ │ @@ -1040,21 +1211,29 @@ │ │ │ │ │ _A_L_L_E_G_R_O___E_V_E_N_T___A_U_D_I_O___S_T_R_E_A_M___F_R_A_G_M_E_N_T event will be generated whenever │ │ │ │ │ a new fragment is ready. However, getting an event is nnoott a guarantee │ │ │ │ │ that _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___f_r_a_g_m_e_n_t will not return NULL, so you still │ │ │ │ │ must check for it. │ │ │ │ │ See also: _a_l___s_e_t___a_u_d_i_o___s_t_r_e_a_m___f_r_a_g_m_e_n_t, _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___e_v_e_n_t___s_o_u_r_c_e, │ │ │ │ │ _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___f_r_e_q_u_e_n_c_y, _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___c_h_a_n_n_e_l_s, │ │ │ │ │ _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___d_e_p_t_h, _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___l_e_n_g_t_h │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___r_e_s_a_m_p_l_e___t_e_s_t_._c │ │ │ │ │ + * _e_x___s_y_n_t_h_._c_p_p │ │ │ │ │ ********** aall__sseett__aauuddiioo__ssttrreeaamm__ffrraaggmmeenntt ********** │ │ │ │ │ bool al_set_audio_stream_fragment(ALLEGRO_AUDIO_STREAM *stream, void *val) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This function needs to be called for every successful call of │ │ │ │ │ _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___f_r_a_g_m_e_n_t to indicate that the buffer (pointed to by val) is │ │ │ │ │ filled with new data. │ │ │ │ │ See also: _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___f_r_a_g_m_e_n_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___r_e_s_a_m_p_l_e___t_e_s_t_._c │ │ │ │ │ + * _e_x___s_y_n_t_h_._c_p_p │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__ffrraaggmmeennttss ********** │ │ │ │ │ unsigned int al_get_audio_stream_fragments(const ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the number of fragments this stream uses. This is the same value as │ │ │ │ │ passed to _a_l___c_r_e_a_t_e___a_u_d_i_o___s_t_r_e_a_m when a new stream is created. │ │ │ │ │ See also: _a_l___g_e_t___a_v_a_i_l_a_b_l_e___a_u_d_i_o___s_t_r_e_a_m___f_r_a_g_m_e_n_t_s │ │ │ │ │ ********** aall__ggeett__aavvaaiillaabbllee__aauuddiioo__ssttrreeaamm__ffrraaggmmeennttss ********** │ │ │ │ │ @@ -1067,35 +1246,43 @@ │ │ │ │ │ ********** aall__sseeeekk__aauuddiioo__ssttrreeaamm__sseeccss ********** │ │ │ │ │ bool al_seek_audio_stream_secs(ALLEGRO_AUDIO_STREAM *stream, double time) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the streaming file playing position to time. Returns true on success. │ │ │ │ │ Currently this can only be called on streams created with _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m, │ │ │ │ │ _a_l___p_l_a_y___a_u_d_i_o___s_t_r_e_a_m, _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m___f or _a_l___p_l_a_y___a_u_d_i_o___s_t_r_e_a_m___f. │ │ │ │ │ See also: _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___p_o_s_i_t_i_o_n___s_e_c_s, _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___l_e_n_g_t_h___s_e_c_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___s_e_e_k_._c │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__ppoossiittiioonn__sseeccss ********** │ │ │ │ │ double al_get_audio_stream_position_secs(ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the position of the stream in seconds. Currently this can only be called │ │ │ │ │ on streams created with _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m, _a_l___p_l_a_y___a_u_d_i_o___s_t_r_e_a_m, │ │ │ │ │ _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m___f or _a_l___p_l_a_y___a_u_d_i_o___s_t_r_e_a_m___f. │ │ │ │ │ See also: _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___l_e_n_g_t_h___s_e_c_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___s_e_e_k_._c │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ssttrreeaamm__lleennggtthh__sseeccss ********** │ │ │ │ │ double al_get_audio_stream_length_secs(ALLEGRO_AUDIO_STREAM *stream) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the length of the stream in seconds, if known. Otherwise returns zero. │ │ │ │ │ Currently this can only be called on streams created with _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m, │ │ │ │ │ _a_l___p_l_a_y___a_u_d_i_o___s_t_r_e_a_m, _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m___f or _a_l___p_l_a_y___a_u_d_i_o___s_t_r_e_a_m___f. │ │ │ │ │ See also: _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___p_o_s_i_t_i_o_n___s_e_c_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___s_e_e_k_._c │ │ │ │ │ ********** aall__sseett__aauuddiioo__ssttrreeaamm__lloooopp__sseeccss ********** │ │ │ │ │ bool al_set_audio_stream_loop_secs(ALLEGRO_AUDIO_STREAM *stream, │ │ │ │ │ double start, double end) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Sets the loop points for the stream in seconds. Currently this can only be │ │ │ │ │ called on streams created with _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m, _a_l___p_l_a_y___a_u_d_i_o___s_t_r_e_a_m, │ │ │ │ │ _a_l___l_o_a_d___a_u_d_i_o___s_t_r_e_a_m___f or _a_l___p_l_a_y___a_u_d_i_o___s_t_r_e_a_m___f. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___s_e_e_k_._c │ │ │ │ │ ********** aall__sseett__aauuddiioo__ssttrreeaamm__cchhaannnneell__mmaattrriixx ********** │ │ │ │ │ Source Code │ │ │ │ │ Like _a_l___s_e_t___s_a_m_p_l_e___i_n_s_t_a_n_c_e___c_h_a_n_n_e_l___m_a_t_r_i_x but for streams. │ │ │ │ │ Since: 5.2.3 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: New API. │ │ │ │ │ ************ AAddvvaanncceedd aauuddiioo ffiillee II//OO ************ │ │ │ │ │ ********** aall__rreeggiisstteerr__ssaammppllee__llooaaddeerr ********** │ │ │ │ │ @@ -1225,26 +1412,32 @@ │ │ │ │ │ drivers. Enumerating or choosing other recording devices is not yet supported. │ │ │ │ │ ********** AALLLLEEGGRROO__AAUUDDIIOO__RREECCOORRDDEERR ********** │ │ │ │ │ typedef struct ALLEGRO_AUDIO_RECORDER ALLEGRO_AUDIO_RECORDER; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ An opaque datatype that represents a recording device. │ │ │ │ │ Since: 5.1.1 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: The API may need a slight redesign. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___r_e_c_o_r_d___n_a_m_e_._c │ │ │ │ │ + * _e_x___r_e_c_o_r_d_._c │ │ │ │ │ ********** AALLLLEEGGRROO__AAUUDDIIOO__RREECCOORRDDEERR__EEVVEENNTT ********** │ │ │ │ │ typedef struct ALLEGRO_AUDIO_RECORDER_EVENT ALLEGRO_AUDIO_RECORDER_EVENT; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Structure that holds the audio recorder event data. Every event type will │ │ │ │ │ contain: │ │ │ │ │ * .source: pointer to the audio recorder │ │ │ │ │ The following will be available depending on the event type: │ │ │ │ │ * .buffer: pointer to buffer containing the audio samples │ │ │ │ │ * .samples: number of samples (not bytes) that are available │ │ │ │ │ Since 5.1.1 │ │ │ │ │ See also: _a_l___g_e_t___a_u_d_i_o___r_e_c_o_r_d_e_r___e_v_e_n_t │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: The API may need a slight redesign. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___r_e_c_o_r_d___n_a_m_e_._c │ │ │ │ │ + * _e_x___r_e_c_o_r_d_._c │ │ │ │ │ ********** aall__ccrreeaattee__aauuddiioo__rreeccoorrddeerr ********** │ │ │ │ │ ALLEGRO_AUDIO_RECORDER *al_create_audio_recorder(size_t fragment_count, │ │ │ │ │ unsigned int samples, unsigned int frequency, │ │ │ │ │ ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Creates an audio recorder using the system’s default recording device. (So if │ │ │ │ │ the returned device does not work, try updating the system’s default recording │ │ │ │ │ @@ -1267,23 +1460,29 @@ │ │ │ │ │ * 44100 - CD quality music (if 16-bit, stereo) │ │ │ │ │ For maximum compatibility, use a depth of ALLEGRO_AUDIO_DEPTH_UINT8 or │ │ │ │ │ ALLEGRO_AUDIO_DEPTH_INT16, and a single (mono) channel. │ │ │ │ │ The recorder will not record until you start it with _a_l___s_t_a_r_t___a_u_d_i_o___r_e_c_o_r_d_e_r. │ │ │ │ │ On failure, returns NULL. │ │ │ │ │ Since: 5.1.1 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: The API may need a slight redesign. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___r_e_c_o_r_d___n_a_m_e_._c │ │ │ │ │ + * _e_x___r_e_c_o_r_d_._c │ │ │ │ │ ********** aall__ssttaarrtt__aauuddiioo__rreeccoorrddeerr ********** │ │ │ │ │ bool al_start_audio_recorder(ALLEGRO_AUDIO_RECORDER *r) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Begin recording into the fragment buffer. Once a complete fragment has been │ │ │ │ │ captured (as specified in _a_l___c_r_e_a_t_e___a_u_d_i_o___r_e_c_o_r_d_e_r), an │ │ │ │ │ _A_L_L_E_G_R_O___E_V_E_N_T___A_U_D_I_O___R_E_C_O_R_D_E_R___F_R_A_G_M_E_N_T event will be triggered. │ │ │ │ │ Returns true if it was able to begin recording. │ │ │ │ │ Since: 5.1.1 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: The API may need a slight redesign. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___r_e_c_o_r_d___n_a_m_e_._c │ │ │ │ │ + * _e_x___r_e_c_o_r_d_._c │ │ │ │ │ ********** aall__ssttoopp__aauuddiioo__rreeccoorrddeerr ********** │ │ │ │ │ void al_stop_audio_recorder(ALLEGRO_AUDIO_RECORDER *r) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Stop capturing audio data. Note that the audio recorder is still active and │ │ │ │ │ consuming resources, so if you are finished recording you should destroy it │ │ │ │ │ with _a_l___d_e_s_t_r_o_y___a_u_d_i_o___r_e_c_o_r_d_e_r. │ │ │ │ │ You may still receive a few events after you call this function as the device │ │ │ │ │ @@ -1301,60 +1500,81 @@ │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: The API may need a slight redesign. │ │ │ │ │ ********** aall__ggeett__aauuddiioo__rreeccoorrddeerr__eevveenntt ********** │ │ │ │ │ ALLEGRO_AUDIO_RECORDER_EVENT *al_get_audio_recorder_event(ALLEGRO_EVENT *event) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the event as an _A_L_L_E_G_R_O___A_U_D_I_O___R_E_C_O_R_D_E_R___E_V_E_N_T. │ │ │ │ │ Since: 5.1.1 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: The API may need a slight redesign. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___r_e_c_o_r_d___n_a_m_e_._c │ │ │ │ │ + * _e_x___r_e_c_o_r_d_._c │ │ │ │ │ ********** aall__ggeett__aauuddiioo__rreeccoorrddeerr__eevveenntt__ssoouurrccee ********** │ │ │ │ │ ALLEGRO_EVENT_SOURCE *al_get_audio_recorder_event_source(ALLEGRO_AUDIO_RECORDER │ │ │ │ │ *r) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the event source for the recorder that generates the various recording │ │ │ │ │ events. │ │ │ │ │ Since: 5.1.1 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: The API may need a slight redesign. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___r_e_c_o_r_d___n_a_m_e_._c │ │ │ │ │ + * _e_x___r_e_c_o_r_d_._c │ │ │ │ │ ********** aall__ddeessttrrooyy__aauuddiioo__rreeccoorrddeerr ********** │ │ │ │ │ void al_destroy_audio_recorder(ALLEGRO_AUDIO_RECORDER *r) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Destroys the audio recorder and frees all resources associated with it. It is │ │ │ │ │ safe to destroy a recorder that is recording. │ │ │ │ │ You may receive events after the recorder has been destroyed. They must be │ │ │ │ │ ignored, as the fragment buffer will no longer be valid. │ │ │ │ │ Since: 5.1.1 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: The API may need a slight redesign. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___r_e_c_o_r_d___n_a_m_e_._c │ │ │ │ │ + * _e_x___r_e_c_o_r_d_._c │ │ │ │ │ ************ AAuuddiioo ddeevviicceess ************ │ │ │ │ │ ********** AALLLLEEGGRROO__AAUUDDIIOO__DDEEVVIICCEE ********** │ │ │ │ │ typedef struct ALLEGRO_AUDIO_DEVICE ALLEGRO_AUDIO_DEVICE; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ An opaque datatype that represents an audio device. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___d_e_v_i_c_e_s_._c │ │ │ │ │ ********** aall__ggeett__nnuumm__aauuddiioo__oouuttppuutt__ddeevviicceess ********** │ │ │ │ │ int al_get_num_audio_output_devices() │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get the number of available audio output devices on the system. │ │ │ │ │ Since: 5.2.8 │ │ │ │ │ return -1 for unsupported drivers. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___d_e_v_i_c_e_s_._c │ │ │ │ │ ********** aall__ggeett__aauuddiioo__oouuttppuutt__ddeevviiccee ********** │ │ │ │ │ const ALLEGRO_AUDIO_DEVICE* al_get_audio_output_device(int index) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get the output audio device of the specified index. │ │ │ │ │ Since: 5.2.8 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___d_e_v_i_c_e_s_._c │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ddeevviiccee__nnaammee ********** │ │ │ │ │ const char* al_get_audio_device_name(const ALLEGRO_AUDIO_DEVICE * device) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get the user friendly display name of the device. │ │ │ │ │ Since: 5.2.8 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___d_e_v_i_c_e_s_._c │ │ │ │ │ ************ VVooiicceess ************ │ │ │ │ │ ********** AALLLLEEGGRROO__VVOOIICCEE ********** │ │ │ │ │ typedef struct ALLEGRO_VOICE ALLEGRO_VOICE; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ A voice represents an audio device on the system, which may be a real device, │ │ │ │ │ or an abstract device provided by the operating system. To play back audio, you │ │ │ │ │ would attach a mixer, sample instance or audio stream to a voice. │ │ │ │ │ See also: _A_L_L_E_G_R_O___M_I_X_E_R, _A_L_L_E_G_R_O___S_A_M_P_L_E, _A_L_L_E_G_R_O___A_U_D_I_O___S_T_R_E_A_M │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ ********** aall__ccrreeaattee__vvooiiccee ********** │ │ │ │ │ ALLEGRO_VOICE *al_create_voice(unsigned int freq, │ │ │ │ │ ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Creates a voice structure and allocates a voice from the digital sound driver. │ │ │ │ │ The passed frequency (in Hz), sample format and channel configuration are used │ │ │ │ │ as a hint to what kind of data will be sent to the voice. However, the │ │ │ │ │ @@ -1364,20 +1584,28 @@ │ │ │ │ │ all its input streams to the voice format and care does not have to be taken │ │ │ │ │ for this. However if you access the voice directly, make sure to not rely on │ │ │ │ │ the parameters passed to this function, but instead query the returned voice │ │ │ │ │ for the actual settings. │ │ │ │ │ Reasonable default arguments are: │ │ │ │ │ al_create_voice(44100, ALLEGRO_AUDIO_DEPTH_INT16, ALLEGRO_CHANNEL_CONF_2) │ │ │ │ │ See also: _a_l___d_e_s_t_r_o_y___v_o_i_c_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ ********** aall__ddeessttrrooyy__vvooiiccee ********** │ │ │ │ │ void al_destroy_voice(ALLEGRO_VOICE *voice) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Destroys the voice and deallocates it from the digital driver. Does nothing if │ │ │ │ │ the voice is NULL. │ │ │ │ │ See also: _a_l___c_r_e_a_t_e___v_o_i_c_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ ********** aall__ddeettaacchh__vvooiiccee ********** │ │ │ │ │ void al_detach_voice(ALLEGRO_VOICE *voice) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Detaches the mixer, sample instance or audio stream from the voice. │ │ │ │ │ See also: _a_l___a_t_t_a_c_h___m_i_x_e_r___t_o___v_o_i_c_e, _a_l___a_t_t_a_c_h___s_a_m_p_l_e___i_n_s_t_a_n_c_e___t_o___v_o_i_c_e, │ │ │ │ │ _a_l___a_t_t_a_c_h___a_u_d_i_o___s_t_r_e_a_m___t_o___v_o_i_c_e │ │ │ │ │ ********** aall__aattttaacchh__aauuddiioo__ssttrreeaamm__ttoo__vvooiiccee ********** │ │ │ │ │ @@ -1389,34 +1617,44 @@ │ │ │ │ │ create a voice with the buffer count and buffer size the stream uses. │ │ │ │ │ An audio stream attached directly to a voice has a number of limitations: The │ │ │ │ │ audio stream plays immediately and cannot be stopped. The stream position, │ │ │ │ │ speed, gain and panning cannot be changed. At this time, we don’t recommend │ │ │ │ │ attaching audio streams directly to voices. Use a mixer inbetween. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___d_e_t_a_c_h___v_o_i_c_e, _a_l___v_o_i_c_e___h_a_s___a_t_t_a_c_h_m_e_n_t_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__aattttaacchh__mmiixxeerr__ttoo__vvooiiccee ********** │ │ │ │ │ bool al_attach_mixer_to_voice(ALLEGRO_MIXER *mixer, ALLEGRO_VOICE *voice) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Attaches a mixer to a voice. It must have the same frequency and channel │ │ │ │ │ configuration, but the depth may be different. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___d_e_t_a_c_h___v_o_i_c_e, _a_l___v_o_i_c_e___h_a_s___a_t_t_a_c_h_m_e_n_t_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__aattttaacchh__ssaammppllee__iinnssttaannccee__ttoo__vvooiiccee ********** │ │ │ │ │ bool al_attach_sample_instance_to_voice(ALLEGRO_SAMPLE_INSTANCE *spl, │ │ │ │ │ ALLEGRO_VOICE *voice) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Attaches a sample instance to a voice, and allows it to play. The instance’s │ │ │ │ │ gain and loop mode will be ignored, and it must have the same frequency, │ │ │ │ │ channel configuration and depth (including signed-ness) as the voice. This │ │ │ │ │ function may fail if the selected driver doesn’t support preloading sample │ │ │ │ │ data. │ │ │ │ │ At this time, we don’t recommend attaching sample instances directly to voices. │ │ │ │ │ Use a mixer inbetween. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___d_e_t_a_c_h___v_o_i_c_e, _a_l___v_o_i_c_e___h_a_s___a_t_t_a_c_h_m_e_n_t_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__ggeett__vvooiiccee__ffrreeqquueennccyy ********** │ │ │ │ │ unsigned int al_get_voice_frequency(const ALLEGRO_VOICE *voice) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the frequency of the voice (in Hz), e.g. 44100. │ │ │ │ │ ********** aall__ggeett__vvooiiccee__cchhaannnneellss ********** │ │ │ │ │ ALLEGRO_CHANNEL_CONF al_get_voice_channels(const ALLEGRO_VOICE *voice) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ @@ -1428,22 +1666,26 @@ │ │ │ │ │ Return the audio depth of the voice. │ │ │ │ │ See also: _A_L_L_E_G_R_O___A_U_D_I_O___D_E_P_T_H. │ │ │ │ │ ********** aall__ggeett__vvooiiccee__ppllaayyiinngg ********** │ │ │ │ │ bool al_get_voice_playing(const ALLEGRO_VOICE *voice) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return true if the voice is currently playing. │ │ │ │ │ See also: _a_l___s_e_t___v_o_i_c_e___p_l_a_y_i_n_g │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__sseett__vvooiiccee__ppllaayyiinngg ********** │ │ │ │ │ bool al_set_voice_playing(ALLEGRO_VOICE *voice, bool val) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Change whether a voice is playing or not. This can only work if the voice has a │ │ │ │ │ non-streaming object attached to it, e.g. a sample instance. On success the │ │ │ │ │ voice’s current sample position is reset. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___g_e_t___v_o_i_c_e___p_l_a_y_i_n_g │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__ggeett__vvooiiccee__ppoossiittiioonn ********** │ │ │ │ │ unsigned int al_get_voice_position(const ALLEGRO_VOICE *voice) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ When the voice has a non-streaming object attached to it, e.g. a sample, │ │ │ │ │ returns the voice’s current sample position. Otherwise, returns zero. │ │ │ │ │ See also: _a_l___s_e_t___v_o_i_c_e___p_o_s_i_t_i_o_n. │ │ │ │ │ ********** aall__sseett__vvooiiccee__ppoossiittiioonn ********** │ │ │ │ │ @@ -1468,14 +1710,18 @@ │ │ │ │ │ it converts channel configurations, sample frequencies and audio depths of the │ │ │ │ │ attached sample instances and audio streams accordingly. You can control the │ │ │ │ │ quality of this conversion using ALLEGRO_MIXER_QUALITY. │ │ │ │ │ When going from mono to stereo (and above), the mixer reduces the volume of │ │ │ │ │ both channels by sqrt(2). When going from stereo (and above) to mono, the mixer │ │ │ │ │ reduces the volume of the left and right channels by sqrt(2) before adding them │ │ │ │ │ to the center channel (if present). │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** AALLLLEEGGRROO__MMIIXXEERR__QQUUAALLIITTYY ********** │ │ │ │ │ enum ALLEGRO_MIXER_QUALITY │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ * ALLEGRO_MIXER_QUALITY_POINT - point sampling │ │ │ │ │ * ALLEGRO_MIXER_QUALITY_LINEAR - linear interpolation │ │ │ │ │ * ALLEGRO_MIXER_QUALITY_CUBIC - cubic interpolation (since: 5.0.8, 5.1.4) │ │ │ │ │ ********** aall__ccrreeaattee__mmiixxeerr ********** │ │ │ │ │ @@ -1488,28 +1734,40 @@ │ │ │ │ │ ALLEGRO_AUDIO_DEPTH_INT16 (not yet complete). │ │ │ │ │ To actually produce any output, the mixer will have to be attached to a voice │ │ │ │ │ using _a_l___a_t_t_a_c_h___m_i_x_e_r___t_o___v_o_i_c_e. │ │ │ │ │ Reasonable default arguments are: │ │ │ │ │ al_create_mixer(44100, ALLEGRO_AUDIO_DEPTH_FLOAT32, ALLEGRO_CHANNEL_CONF_2) │ │ │ │ │ Returns true on success, false on error. │ │ │ │ │ See also: _a_l___d_e_s_t_r_o_y___m_i_x_e_r, _A_L_L_E_G_R_O___A_U_D_I_O___D_E_P_T_H, _A_L_L_E_G_R_O___C_H_A_N_N_E_L___C_O_N_F │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__ddeessttrrooyy__mmiixxeerr ********** │ │ │ │ │ void al_destroy_mixer(ALLEGRO_MIXER *mixer) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Destroys the mixer. │ │ │ │ │ See also: _a_l___c_r_e_a_t_e___m_i_x_e_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** aall__ggeett__ddeeffaauulltt__mmiixxeerr ********** │ │ │ │ │ ALLEGRO_MIXER *al_get_default_mixer(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the default mixer, or NULL if one has not been set. Although different │ │ │ │ │ configurations of mixers and voices can be used, in most cases a single mixer │ │ │ │ │ attached to a voice is what you want. The default mixer is used by │ │ │ │ │ _a_l___p_l_a_y___s_a_m_p_l_e. │ │ │ │ │ See also: _a_l___r_e_s_e_r_v_e___s_a_m_p_l_e_s, _a_l___p_l_a_y___s_a_m_p_l_e, _a_l___s_e_t___d_e_f_a_u_l_t___m_i_x_e_r, │ │ │ │ │ _a_l___r_e_s_t_o_r_e___d_e_f_a_u_l_t___m_i_x_e_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___p_r_o_p_s_._c_p_p │ │ │ │ │ + * _e_x___r_e_s_a_m_p_l_e___t_e_s_t_._c │ │ │ │ │ ********** aall__sseett__ddeeffaauulltt__mmiixxeerr ********** │ │ │ │ │ bool al_set_default_mixer(ALLEGRO_MIXER *mixer) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Sets the default mixer. All samples started with _a_l___p_l_a_y___s_a_m_p_l_e will be stopped │ │ │ │ │ and all sample instances returned by _a_l___l_o_c_k___s_a_m_p_l_e___i_d will be invalidated. If │ │ │ │ │ you are using your own mixer, this should be called before _a_l___r_e_s_e_r_v_e___s_a_m_p_l_e_s. │ │ │ │ │ Returns true on success, false on error. │ │ │ │ │ @@ -1545,30 +1803,41 @@ │ │ │ │ │ Attaches the mixer passed as the first argument onto the mixer passed as the │ │ │ │ │ second argument. The first mixer (that is going to be attached) must not │ │ │ │ │ already be attached to anything. Both mixers must use the same frequency, audio │ │ │ │ │ depth and channel configuration. │ │ │ │ │ Returns true on success, false on error. │ │ │ │ │ It is invalid to attach a mixer to itself. │ │ │ │ │ See also: _a_l___d_e_t_a_c_h___m_i_x_e_r. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__aattttaacchh__ssaammppllee__iinnssttaannccee__ttoo__mmiixxeerr ********** │ │ │ │ │ bool al_attach_sample_instance_to_mixer(ALLEGRO_SAMPLE_INSTANCE *spl, │ │ │ │ │ ALLEGRO_MIXER *mixer) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Attach a sample instance to a mixer. The instance must not already be attached │ │ │ │ │ to anything. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___d_e_t_a_c_h___s_a_m_p_l_e___i_n_s_t_a_n_c_e. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c_._c │ │ │ │ │ ********** aall__aattttaacchh__aauuddiioo__ssttrreeaamm__ttoo__mmiixxeerr ********** │ │ │ │ │ bool al_attach_audio_stream_to_mixer(ALLEGRO_AUDIO_STREAM *stream, │ │ │ │ │ ALLEGRO_MIXER *mixer) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Attach an audio stream to a mixer. The stream must not already be attached to │ │ │ │ │ anything. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___d_e_t_a_c_h___a_u_d_i_o___s_t_r_e_a_m. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___r_e_s_a_m_p_l_e___t_e_s_t_._c │ │ │ │ │ ********** aall__ggeett__mmiixxeerr__ffrreeqquueennccyy ********** │ │ │ │ │ unsigned int al_get_mixer_frequency(const ALLEGRO_MIXER *mixer) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the mixer frequency (in Hz). │ │ │ │ │ See also: _a_l___s_e_t___m_i_x_e_r___f_r_e_q_u_e_n_c_y │ │ │ │ │ ********** aall__sseett__mmiixxeerr__ffrreeqquueennccyy ********** │ │ │ │ │ bool al_set_mixer_frequency(ALLEGRO_MIXER *mixer, unsigned int val) │ │ │ │ │ @@ -1578,32 +1847,41 @@ │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___g_e_t___m_i_x_e_r___f_r_e_q_u_e_n_c_y │ │ │ │ │ ********** aall__ggeett__mmiixxeerr__cchhaannnneellss ********** │ │ │ │ │ ALLEGRO_CHANNEL_CONF al_get_mixer_channels(const ALLEGRO_MIXER *mixer) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the mixer channel configuration. │ │ │ │ │ See also: _A_L_L_E_G_R_O___C_H_A_N_N_E_L___C_O_N_F. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_y_n_t_h_._c_p_p │ │ │ │ │ ********** aall__ggeett__mmiixxeerr__ddeepptthh ********** │ │ │ │ │ ALLEGRO_AUDIO_DEPTH al_get_mixer_depth(const ALLEGRO_MIXER *mixer) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the mixer audio depth. │ │ │ │ │ See also: _A_L_L_E_G_R_O___A_U_D_I_O___D_E_P_T_H. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_y_n_t_h_._c_p_p │ │ │ │ │ ********** aall__ggeett__mmiixxeerr__ggaaiinn ********** │ │ │ │ │ float al_get_mixer_gain(const ALLEGRO_MIXER *mixer) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the mixer gain (amplification factor). The default is 1.0. │ │ │ │ │ Since: 5.0.6, 5.1.0 │ │ │ │ │ See also: _a_l___s_e_t___m_i_x_e_r___g_a_i_n. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__sseett__mmiixxeerr__ggaaiinn ********** │ │ │ │ │ bool al_set_mixer_gain(ALLEGRO_MIXER *mixer, float new_gain) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the mixer gain (amplification factor). │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ Since: 5.0.6, 5.1.0 │ │ │ │ │ See also: _a_l___g_e_t___m_i_x_e_r___g_a_i_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___p_r_o_p_s_._c_p_p │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__ggeett__mmiixxeerr__qquuaalliittyy ********** │ │ │ │ │ ALLEGRO_MIXER_QUALITY al_get_mixer_quality(const ALLEGRO_MIXER *mixer) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the mixer quality. │ │ │ │ │ See also: _A_L_L_E_G_R_O___M_I_X_E_R___Q_U_A_L_I_T_Y, _a_l___s_e_t___m_i_x_e_r___q_u_a_l_i_t_y │ │ │ │ │ ********** aall__sseett__mmiixxeerr__qquuaalliittyy ********** │ │ │ │ │ bool al_set_mixer_quality(ALLEGRO_MIXER *mixer, ALLEGRO_MIXER_QUALITY │ │ │ │ │ @@ -1614,20 +1892,24 @@ │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _A_L_L_E_G_R_O___M_I_X_E_R___Q_U_A_L_I_T_Y, _a_l___g_e_t___m_i_x_e_r___q_u_a_l_i_t_y │ │ │ │ │ ********** aall__ggeett__mmiixxeerr__ppllaayyiinngg ********** │ │ │ │ │ bool al_get_mixer_playing(const ALLEGRO_MIXER *mixer) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return true if the mixer is playing. │ │ │ │ │ See also: _a_l___s_e_t___m_i_x_e_r___p_l_a_y_i_n_g. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__sseett__mmiixxeerr__ppllaayyiinngg ********** │ │ │ │ │ bool al_set_mixer_playing(ALLEGRO_MIXER *mixer, bool val) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Change whether the mixer is playing. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___g_e_t___m_i_x_e_r___p_l_a_y_i_n_g. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__ggeett__mmiixxeerr__aattttaacchheedd ********** │ │ │ │ │ bool al_get_mixer_attached(const ALLEGRO_MIXER *mixer) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return true if the mixer is attached to something. │ │ │ │ │ See also: _a_l___m_i_x_e_r___h_a_s___a_t_t_a_c_h_m_e_n_t_s, _a_l___a_t_t_a_c_h___s_a_m_p_l_e___i_n_s_t_a_n_c_e___t_o___m_i_x_e_r, │ │ │ │ │ _a_l___a_t_t_a_c_h___a_u_d_i_o___s_t_r_e_a_m___t_o___m_i_x_e_r, _a_l___a_t_t_a_c_h___m_i_x_e_r___t_o___m_i_x_e_r, _a_l___d_e_t_a_c_h___m_i_x_e_r │ │ │ │ │ ********** aall__mmiixxeerr__hhaass__aattttaacchhmmeennttss ********** │ │ │ │ │ @@ -1638,23 +1920,29 @@ │ │ │ │ │ _a_l___a_t_t_a_c_h___a_u_d_i_o___s_t_r_e_a_m___t_o___m_i_x_e_r, _a_l___a_t_t_a_c_h___m_i_x_e_r___t_o___m_i_x_e_r, _a_l___d_e_t_a_c_h___m_i_x_e_r │ │ │ │ │ Since: 5.2.9 │ │ │ │ │ ********** aall__ddeettaacchh__mmiixxeerr ********** │ │ │ │ │ bool al_detach_mixer(ALLEGRO_MIXER *mixer) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Detach the mixer from whatever it is attached to, if anything. │ │ │ │ │ See also: _a_l___a_t_t_a_c_h___m_i_x_e_r___t_o___m_i_x_e_r. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__sseett__mmiixxeerr__ppoossttpprroocceessss__ccaallllbbaacckk ********** │ │ │ │ │ bool al_set_mixer_postprocess_callback(ALLEGRO_MIXER *mixer, │ │ │ │ │ void (*pp_callback)(void *buf, unsigned int samples, void *data), │ │ │ │ │ void *pp_callback_userdata) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Sets a post-processing filter function that’s called after the attached streams │ │ │ │ │ have been mixed. The buffer’s format will be whatever the mixer was created │ │ │ │ │ with. The sample count and user-data pointer is also passed. │ │ │ │ │ NNoottee:: The callback is called from a dedicated audio thread. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___r_e_s_a_m_p_l_e___t_e_s_t_._c │ │ │ │ │ + * _e_x___s_y_n_t_h_._c_p_p │ │ │ │ │ + * _e_x___m_i_x_e_r___p_p_._c │ │ │ │ │ ************ MMiisscceellaanneeoouuss ************ │ │ │ │ │ ********** AALLLLEEGGRROO__AAUUDDIIOO__DDEEPPTTHH ********** │ │ │ │ │ enum ALLEGRO_AUDIO_DEPTH │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Sample depth and type as well as signedness. Mixers only use 32-bit signed │ │ │ │ │ float (-1..+1), or 16-bit signed integers. Signedness is determined by an │ │ │ │ │ “unsigned” bit-flag applied to the depth value. │ │ │ │ │ @@ -1663,37 +1951,47 @@ │ │ │ │ │ * ALLEGRO_AUDIO_DEPTH_INT24 │ │ │ │ │ * ALLEGRO_AUDIO_DEPTH_FLOAT32 │ │ │ │ │ * ALLEGRO_AUDIO_DEPTH_UNSIGNED │ │ │ │ │ For convenience: │ │ │ │ │ * ALLEGRO_AUDIO_DEPTH_UINT8 │ │ │ │ │ * ALLEGRO_AUDIO_DEPTH_UINT16 │ │ │ │ │ * ALLEGRO_AUDIO_DEPTH_UINT24 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ ********** AALLLLEEGGRROO__AAUUDDIIOO__PPAANN__NNOONNEE ********** │ │ │ │ │ #define ALLEGRO_AUDIO_PAN_NONE (-1000.0f) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ A special value for the pan property of sample instances and audio streams. Use │ │ │ │ │ this value to disable panning on sample instances and audio streams, and play │ │ │ │ │ them without attentuation implied by panning support. │ │ │ │ │ ALLEGRO_AUDIO_PAN_NONE is different from a pan value of 0.0 (centered) because, │ │ │ │ │ when panning is enabled, we try to maintain a constant sound power level as a │ │ │ │ │ sample is panned from left to right. A sound coming out of one speaker should │ │ │ │ │ sound as loud as it does when split over two speakers. As a consequence, a │ │ │ │ │ sample with pan value 0.0 will be 3 dB softer than the original level. │ │ │ │ │ (Please correct us if this is wrong.) │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___p_r_o_p_s_._c_p_p │ │ │ │ │ ********** AALLLLEEGGRROO__CCHHAANNNNEELL__CCOONNFF ********** │ │ │ │ │ enum ALLEGRO_CHANNEL_CONF │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Speaker configuration (mono, stereo, 2.1, etc). │ │ │ │ │ * ALLEGRO_CHANNEL_CONF_1 │ │ │ │ │ * ALLEGRO_CHANNEL_CONF_2 │ │ │ │ │ * ALLEGRO_CHANNEL_CONF_3 │ │ │ │ │ * ALLEGRO_CHANNEL_CONF_4 │ │ │ │ │ * ALLEGRO_CHANNEL_CONF_5_1 │ │ │ │ │ * ALLEGRO_CHANNEL_CONF_6_1 │ │ │ │ │ * ALLEGRO_CHANNEL_CONF_7_1 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___a_c_o_d_e_c___m_u_l_t_i_._c │ │ │ │ │ ********** AALLLLEEGGRROO__PPLLAAYYMMOODDEE ********** │ │ │ │ │ enum ALLEGRO_PLAYMODE │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Sample and stream playback mode. │ │ │ │ │ * ALLEGRO_PLAYMODE_ONCE - the sample/stream is played from start to finish │ │ │ │ │ an then it stops. │ │ │ │ │ * ALLEGRO_PLAYMODE_LOOP - the sample/stream is played from start to finish │ │ │ │ │ @@ -1702,14 +2000,18 @@ │ │ │ │ │ * ALLEGRO_PLAYMODE_LOOP_ONCE - just like ALLEGRO_PLAYMODE_ONCE, but │ │ │ │ │ respects the loop end point. │ │ │ │ │ * ALLEGRO_PLAYMODE_BIDIR - the sample is played from start to finish (or │ │ │ │ │ between the two loop points). When it reaches the end, it reverses the │ │ │ │ │ playback direction and plays until it reaches the beginning when it │ │ │ │ │ reverses the direction back to normal. This is mode is rarely supported │ │ │ │ │ for streams. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_t_r_e_a_m___f_i_l_e_._c │ │ │ │ │ + * _e_x___k_c_m___d_i_r_e_c_t_._c │ │ │ │ │ + * _e_x___m_i_x_e_r___c_h_a_i_n_._c │ │ │ │ │ ********** AALLLLEEGGRROO__AAUUDDIIOO__EEVVEENNTT__TTYYPPEE ********** │ │ │ │ │ enum ALLEGRO_AUDIO_EVENT_TYPE │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Events sent by _a_l___g_e_t___a_u_d_i_o___s_t_r_e_a_m___e_v_e_n_t___s_o_u_r_c_e or │ │ │ │ │ _a_l___g_e_t___a_u_d_i_o___r_e_c_o_r_d_e_r___e_v_e_n_t___s_o_u_r_c_e. │ │ │ │ │ ******** AALLLLEEGGRROO__EEVVEENNTT__AAUUDDIIOO__SSTTRREEAAMM__FFRRAAGGMMEENNTT ******** │ │ │ │ │ Sent when a stream fragment is ready to be filled in. See │ │ │ │ │ @@ -1729,21 +2031,28 @@ │ │ │ │ │ Returns the (compiled) version of the addon, in the same format as │ │ │ │ │ _a_l___g_e_t___a_l_l_e_g_r_o___v_e_r_s_i_o_n. │ │ │ │ │ ********** aall__ggeett__aauuddiioo__ddeepptthh__ssiizzee ********** │ │ │ │ │ size_t al_get_audio_depth_size(ALLEGRO_AUDIO_DEPTH depth) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the size of a sample, in bytes, for the given format. The format is one │ │ │ │ │ of the values listed under _A_L_L_E_G_R_O___A_U_D_I_O___D_E_P_T_H. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_y_n_t_h_._c_p_p │ │ │ │ │ ********** aall__ggeett__cchhaannnneell__ccoouunntt ********** │ │ │ │ │ size_t al_get_channel_count(ALLEGRO_CHANNEL_CONF conf) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the number of channels for the given channel configuration, which is one │ │ │ │ │ of the values listed under _A_L_L_E_G_R_O___C_H_A_N_N_E_L___C_O_N_F. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_c_o_d_e_c_._c │ │ │ │ │ ********** aall__ffiillll__ssiilleennccee ********** │ │ │ │ │ void al_fill_silence(void *buf, unsigned int samples, │ │ │ │ │ ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Fill a buffer with silence, for the given format and channel configuration. The │ │ │ │ │ buffer must have enough space for the given number of samples, and be properly │ │ │ │ │ aligned. │ │ │ │ │ Since: 5.1.8 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___s_y_n_t_h_._c_p_p │ │ │ │ │ Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/color.html │ │ │ │ @@ -272,23 +272,33 @@ │ │ │ │ href="https://github.com/liballeg/allegro5/blob/master/addons/color/color.c#L480">Source │ │ │ │ Code

    │ │ │ │

    Return an ALLEGRO_COLOR │ │ │ │ structure from CMYK values (cyan, magenta, yellow, black).

    │ │ │ │

    See also: al_color_cmyk_to_rgb, al_color_rgb_to_cmyk

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_color_cmyk_to_rgb

    │ │ │ │ 
    void al_color_cmyk_to_rgb(float cyan, float magenta, float yellow,
│ │ │ │      float key, float *red, float *green, float *blue)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Convert CMYK values to RGB values.

    │ │ │ │

    See also: al_color_cmyk, al_color_rgb_to_cmyk

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_color_hsl

    │ │ │ │ 
    ALLEGRO_COLOR al_color_hsl(float h, float s, float l)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return an ALLEGRO_COLOR │ │ │ │ structure from HSL (hue, saturation, lightness) values.

    │ │ │ │ @@ -297,14 +307,23 @@ │ │ │ │
  • hue - Color hue angle in the range 0..360
    • │ │ │ │
  • saturation - Color saturation in the range 0..1
    • │ │ │ │
  • lightness - Color lightness in the range 0..1
    • │ │ │ │ │ │ │ │

    See also: al_color_hsl_to_rgb, al_color_hsv

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_color_hsl_to_rgb

    │ │ │ │ 
    void al_color_hsl_to_rgb(float hue, float saturation, float lightness,
│ │ │ │     float *red, float *green, float *blue)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Convert values in HSL color model to RGB color model.

    │ │ │ │ @@ -315,14 +334,21 @@ │ │ │ │
  • lightness - Color lightness in the range 0..1
    • │ │ │ │
  • red, green, blue - returned RGB values in the range 0..1
    • │ │ │ │ │ │ │ │

    See also: al_color_rgb_to_hsl, al_color_hsl, al_color_hsv_to_rgb

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_color_hsv

    │ │ │ │ 
    ALLEGRO_COLOR al_color_hsv(float h, float s, float v)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return an ALLEGRO_COLOR │ │ │ │ structure from HSV (hue, saturation, value) values.

    │ │ │ │ @@ -331,14 +357,23 @@ │ │ │ │
  • hue - Color hue angle in the range 0..360
    • │ │ │ │
  • saturation - Color saturation in the range 0..1
    • │ │ │ │
  • value - Color value in the range 0..1
    • │ │ │ │ │ │ │ │

    See also: al_color_hsv_to_rgb, al_color_hsl

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_color_hsv_to_rgb

    │ │ │ │ 
    void al_color_hsv_to_rgb(float hue, float saturation, float value,
│ │ │ │     float *red, float *green, float *blue)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Convert values in HSV color model to RGB color model.

    │ │ │ │ @@ -349,14 +384,19 @@ │ │ │ │
  • value - Color value in the range 0..1
    • │ │ │ │
  • red, green, blue - returned RGB values in the range 0..1
    • │ │ │ │ │ │ │ │

    See also: al_color_rgb_to_hsv, al_color_hsv, al_color_hsl_to_rgb

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_color_html

    │ │ │ │ 
    ALLEGRO_COLOR al_color_html(char const *string)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Interprets an HTML-style hex number (e.g. #00faff) as a color. The │ │ │ │ accepted format is the same as │ │ │ │

    Example:

    │ │ │ │ 
    char html[8];
│ │ │ │  al_color_rgb_to_html(1, 0, 0, html);
    │ │ │ │

    Now html will contain “#ff0000”.

    │ │ │ │

    See also: al_color_html, al_color_html_to_rgb

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_color_name

    │ │ │ │ 
    ALLEGRO_COLOR al_color_name(char const *name)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return an ALLEGRO_COLOR │ │ │ │ with the given name. If the color is not found then black is │ │ │ │ returned.

    │ │ │ │

    See al_color_name_to_rgb for the │ │ │ │ list of names.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_color_name_to_rgb

    │ │ │ │ 
    bool al_color_name_to_rgb(char const *name, float *r, float *g, float *b)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Parameters:

    │ │ │ │ │ │ │ │

    Note that glyphs may go to the left and upwards of the X, in which │ │ │ │ case x and y will have negative values.

    │ │ │ │

    See also: al_get_text_width, al_get_font_line_height, al_get_ustr_dimensions

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_ustr_dimensions

    │ │ │ │ 
    void al_get_ustr_dimensions(const ALLEGRO_FONT *f,
│ │ │ │     ALLEGRO_USTR const *ustr,
│ │ │ │     int *bbx, int *bby, int *bbw, int *bbh)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -643,27 +756,37 @@ │ │ │ │ unicode point in a range, the odd integers the last unicode point in a │ │ │ │ range.

    │ │ │ │

    Returns the number of ranges contained in the font (even if it is │ │ │ │ bigger than ranges_count).

    │ │ │ │

    Since: 5.1.4

    │ │ │ │

    See also: al_grab_font_from_bitmap

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_fallback_font

    │ │ │ │ 
    void al_set_fallback_font(ALLEGRO_FONT *font, ALLEGRO_FONT *fallback)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Sets a font which is used instead if a character is not present. Can │ │ │ │ be chained, but make sure there is no loop as that would crash the │ │ │ │ application! Pass NULL to remove a fallback font again.

    │ │ │ │

    Since: 5.1.12

    │ │ │ │

    See also: al_get_fallback_font, al_draw_glyph, al_draw_text

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_fallback_font

    │ │ │ │ 
    ALLEGRO_FONT *al_get_fallback_font(ALLEGRO_FONT *font)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Retrieves the fallback font for this font or NULL.

    │ │ │ │

    Since: 5.1.12

    │ │ │ │ @@ -703,14 +826,21 @@ │ │ │ │ again with false as a parameter when done drawing the glyphs to further │ │ │ │ enhance performance.

    │ │ │ │

    Since: 5.1.12

    │ │ │ │

    See also: al_get_glyph_width, al_get_glyph_dimensions, al_get_glyph_advance.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_glyph_width

    │ │ │ │ 
    int al_get_glyph_width(const ALLEGRO_FONT *f, int codepoint)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    This function returns the width in pixels of the glyph that │ │ │ │ corresponds with codepoint in the font font. │ │ │ │ @@ -773,14 +903,19 @@ │ │ │ │ | | * *| │ │ │ │ v | **** | │ │ │ │ +---+-------+ │ │ │ │

    Since: 5.1.12

    │ │ │ │

    See also: al_draw_glyph, al_get_glyph_width, al_get_glyph_advance.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_glyph_advance

    │ │ │ │ 
    int al_get_glyph_advance(const ALLEGRO_FONT *f, int codepoint1, int codepoint2)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    This function returns by how much the x position should be advanced │ │ │ │ for left to right text drawing when the glyph that corresponds to │ │ │ │ @@ -842,14 +977,21 @@ │ │ │ │ / \ | │ │ │ │ / \ \_ │ │ │ │ --------------- │ │ │ │

    Since: 5.1.12

    │ │ │ │

    See also: al_draw_glyph, al_get_glyph_width, al_get_glyph_dimensions.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Multiline text drawing

    │ │ │ │

    al_draw_multiline_text

    │ │ │ │ 
    void al_draw_multiline_text(const ALLEGRO_FONT *font,
│ │ │ │       ALLEGRO_COLOR color, float x, float y, float max_width, float line_height,
│ │ │ │       int flags, const char *text)
    │ │ │ │

    Source │ │ │ │ @@ -896,14 +1038,21 @@ │ │ │ │ layout, you can use al_do_multiline_text.

    │ │ │ │

    Since: 5.1.9

    │ │ │ │

    See also: al_do_multiline_text, al_draw_multiline_ustr, al_draw_multiline_textf

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_multiline_ustr

    │ │ │ │ 
    void al_draw_multiline_ustr(const ALLEGRO_FONT *font,
│ │ │ │       ALLEGRO_COLOR color, float x, float y, float max_width, float line_height,
│ │ │ │       int flags, const ALLEGRO_USTR *ustr)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -928,14 +1077,19 @@ │ │ │ │ href="font.html#al_draw_multiline_text">al_draw_multiline_text │ │ │ │ otherwise.

    │ │ │ │

    Since: 5.1.9

    │ │ │ │

    See also: al_draw_multiline_text, al_draw_multiline_ustr, al_do_multiline_text

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_do_multiline_text

    │ │ │ │ 
    void al_do_multiline_text(const ALLEGRO_FONT *font,
│ │ │ │     float max_width, const char *text,
│ │ │ │     bool (*cb)(int line_num, const char *line, int size, void *extra),
│ │ │ │     void *extra)
    │ │ │ │

    Source │ │ │ │ @@ -970,14 +1124,19 @@ │ │ │ │ guaranteed to be valid after that.

    │ │ │ │

    If the callback cb returns false, al_do_multiline_text │ │ │ │ will stop immediately, otherwise it will continue on to the next │ │ │ │ line.

    │ │ │ │

    Since: 5.1.9

    │ │ │ │

    See also: al_draw_multiline_text

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_do_multiline_ustr

    │ │ │ │ 
    void al_do_multiline_ustr(const ALLEGRO_FONT *font, float max_width,
│ │ │ │     const ALLEGRO_USTR *ustr,
│ │ │ │     bool (*cb)(int line_num, const ALLEGRO_USTR * line, void *extra),
│ │ │ │     void *extra)
    │ │ │ │

    Source │ │ │ │ @@ -1044,14 +1203,21 @@ │ │ │ │ glyphs found in the bitmap to ASCII range, the next 95 glyphs to Latin │ │ │ │ 1, the next 128 glyphs to Extended-A, and the last glyph to the Euro │ │ │ │ character. (This is just the characters found in the Allegro 4 │ │ │ │ font.)

    │ │ │ │

    See also: al_load_bitmap, │ │ │ │ al_grab_font_from_bitmap

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_load_bitmap_font

    │ │ │ │ 
    ALLEGRO_FONT *al_load_bitmap_font(const char *fname)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Load a bitmap font from a file. This is done by first calling al_load_bitmap_flags and │ │ │ │ @@ -1062,14 +1228,23 @@ │ │ │ │ href="graphics.html#al_convert_mask_to_alpha">al_convert_mask_to_alpha │ │ │ │ on it before passing it to al_grab_font_from_bitmap.

    │ │ │ │

    See also: al_load_bitmap_font_flags, │ │ │ │ al_load_font, al_load_bitmap_flags

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_load_bitmap_font_flags

    │ │ │ │ 
    ALLEGRO_FONT *al_load_bitmap_font_flags(const char *fname, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Like al_load_bitmap_font │ │ │ │ but additionally takes a flags parameter which is a bitfield containing │ │ │ │ @@ -1101,14 +1276,23 @@ │ │ │ │

    Returns NULL on an error.

    │ │ │ │

    The font memory must be freed the same way as for any other font, │ │ │ │ using al_destroy_font.

    │ │ │ │

    Since: 5.0.8, 5.1.3

    │ │ │ │

    See also: al_load_bitmap_font, al_destroy_font

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    TTF fonts

    │ │ │ │

    These functions are declared in the following header file. Link with │ │ │ │ allegro_ttf.

    │ │ │ │ 
     #include <allegro5/allegro_ttf.h>
    │ │ │ │

    al_init_ttf_addon

    │ │ │ │ 
    bool al_init_ttf_addon(void)
    │ │ │ │

    │ │ │ │

    Call this after al_init_font_addon to make al_load_font recognize “.ttf” and │ │ │ │ other formats supported by al_load_ttf_font.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_is_ttf_addon_initialized

    │ │ │ │ 
    bool al_is_ttf_addon_initialized(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true if the TTF addon is initialized, otherwise returns │ │ │ │ false.

    │ │ │ │ @@ -1165,14 +1358,23 @@ │ │ │ │

  • ALLEGRO_TTF_NO_AUTOHINT - Disable the Auto Hinter which is │ │ │ │ enabled by default in newer versions of FreeType. Since: 5.0.6, │ │ │ │ 5.1.2

    • │ │ │ │ │ │ │ │

    See also: al_init_ttf_addon, al_load_ttf_font_f

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_load_ttf_font_f

    │ │ │ │ 
    ALLEGRO_FONT *al_load_ttf_font_f(ALLEGRO_FILE *file,
│ │ │ │      char const *filename, int size, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Like al_load_ttf_font, but │ │ │ │ @@ -1242,14 +1444,21 @@ │ │ │ │ compatibility.

    │ │ │ │

    Since: 5.2.1

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: This API is new and subject to refinement.

    │ │ │ │
    │ │ │ │

    See also: ALLEGRO_GLYPH

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    │ │ │ │ Allegro version 5.2.10 │ │ │ │ - Last updated: 2025-01-09 13:52:42 UTC │ │ │ │

    │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -103,14 +103,18 @@ │ │ │ │ │ typedef struct ALLEGRO_FONT ALLEGRO_FONT; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ A handle identifying any kind of font. Usually you will create it with │ │ │ │ │ _a_l___l_o_a_d___f_o_n_t which supports loading all kinds of TrueType fonts supported by │ │ │ │ │ the FreeType library. If you instead pass the filename of a bitmap file, it │ │ │ │ │ will be loaded with _a_l___l_o_a_d___b_i_t_m_a_p and a font in Allegro’s bitmap font format │ │ │ │ │ will be created from it with _a_l___g_r_a_b___f_o_n_t___f_r_o_m___b_i_t_m_a_p. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_i_s_a_b_l_e___s_c_r_e_e_n_s_a_v_e_r_._c │ │ │ │ │ + * _e_x___f_o_n_t___j_u_s_t_i_f_y_._c_p_p │ │ │ │ │ + * _e_x___t_i_m_e_d_w_a_i_t_._c │ │ │ │ │ ********** AALLLLEEGGRROO__GGLLYYPPHH ********** │ │ │ │ │ typedef struct ALLEGRO_GLYPH ALLEGRO_GLYPH; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ A structure containing the properties of a character in a font. │ │ │ │ │ typedef struct ALLEGRO_GLYPH { │ │ │ │ │ ALLEGRO_BITMAP *bitmap; // the bitmap the character is on │ │ │ │ │ int x; // the x position of the glyph on bitmap │ │ │ │ │ @@ -131,27 +135,33 @@ │ │ │ │ │ Glyphs are tightly packed onto the bitmap, so you need to add offset_x and │ │ │ │ │ offset_y to your draw position for the text to look right. │ │ │ │ │ advance is the number of pixels to add to your x position to advance to the │ │ │ │ │ next character in a string and includes kerning. │ │ │ │ │ Since: 5.2.1 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: This API is new and subject to refinement. │ │ │ │ │ See also: _a_l___g_e_t___g_l_y_p_h │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ********** aall__iinniitt__ffoonntt__aaddddoonn ********** │ │ │ │ │ bool al_init_font_addon(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Initialise the font addon. │ │ │ │ │ Note that if you intend to load bitmap fonts, you will need to initialise │ │ │ │ │ allegro_image separately (unless you are using another library to load images). │ │ │ │ │ Similarly, if you wish to load truetype-fonts, do not forget to also call │ │ │ │ │ _a_l___i_n_i_t___t_t_f___a_d_d_o_n. │ │ │ │ │ Returns true on success, false on failure. On the 5.0 branch, this function has │ │ │ │ │ no return value. You may wish to avoid checking the return value if your code │ │ │ │ │ needs to be compatible with Allegro 5.0. Currently, the function will never │ │ │ │ │ return false. │ │ │ │ │ See also: _a_l___i_n_i_t___i_m_a_g_e___a_d_d_o_n, _a_l___i_n_i_t___t_t_f___a_d_d_o_n, _a_l___s_h_u_t_d_o_w_n___f_o_n_t___a_d_d_o_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_i_s_a_b_l_e___s_c_r_e_e_n_s_a_v_e_r_._c │ │ │ │ │ + * _e_x___f_o_n_t___j_u_s_t_i_f_y_._c_p_p │ │ │ │ │ + * _e_x___t_i_m_e_d_w_a_i_t_._c │ │ │ │ │ ********** aall__iiss__ffoonntt__aaddddoonn__iinniittiiaalliizzeedd ********** │ │ │ │ │ bool al_is_font_addon_initialized(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true if the font addon is initialized, otherwise returns false. │ │ │ │ │ Since: 5.2.6 │ │ │ │ │ See also: _a_l___i_n_i_t___f_o_n_t___a_d_d_o_n, _a_l___s_h_u_t_d_o_w_n___f_o_n_t___a_d_d_o_n │ │ │ │ │ ********** aall__sshhuuttddoowwnn__ffoonntt__aaddddoonn ********** │ │ │ │ │ @@ -166,19 +176,27 @@ │ │ │ │ │ Loads a font from disk. This will use _a_l___l_o_a_d___b_i_t_m_a_p___f_o_n_t___f_l_a_g_s if you pass the │ │ │ │ │ name of a known bitmap format, or else _a_l___l_o_a_d___t_t_f___f_o_n_t. │ │ │ │ │ The flags parameter is passed through to either of those functions. Bitmap and │ │ │ │ │ TTF fonts are also affected by the current _b_i_t_m_a_p_ _f_l_a_g_s at the time the font is │ │ │ │ │ loaded. │ │ │ │ │ See also: _a_l___d_e_s_t_r_o_y___f_o_n_t, _a_l___i_n_i_t___f_o_n_t___a_d_d_o_n, _a_l___r_e_g_i_s_t_e_r___f_o_n_t___l_o_a_d_e_r, │ │ │ │ │ _a_l___l_o_a_d___b_i_t_m_a_p___f_o_n_t___f_l_a_g_s, _a_l___l_o_a_d___t_t_f___f_o_n_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t___j_u_s_t_i_f_y_._c_p_p │ │ │ │ │ + * _e_x___m_e_m_b_m_p_._c │ │ │ │ │ + * _e_x___w_i_n_d_o_w___t_i_t_l_e_._c │ │ │ │ │ ********** aall__ddeessttrrooyy__ffoonntt ********** │ │ │ │ │ void al_destroy_font(ALLEGRO_FONT *f) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Frees the memory being used by a font structure. Does nothing if passed NULL. │ │ │ │ │ See also: _a_l___l_o_a_d___f_o_n_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_i_s_a_b_l_e___s_c_r_e_e_n_s_a_v_e_r_._c │ │ │ │ │ + * _e_x___f_o_n_t___j_u_s_t_i_f_y_._c_p_p │ │ │ │ │ + * _e_x___c_p_u_._c │ │ │ │ │ ********** aall__rreeggiisstteerr__ffoonntt__llooaaddeerr ********** │ │ │ │ │ bool al_register_font_loader(char const *extension, │ │ │ │ │ ALLEGRO_FONT *(*load_font)(char const *filename, int size, int flags)) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Informs Allegro of a new font file type, telling it how to load files of this │ │ │ │ │ format. │ │ │ │ │ The extension should include the leading dot (‘.’) character. It will be │ │ │ │ │ @@ -204,34 +222,48 @@ │ │ │ │ │ / \ | height │ │ │ │ │ ---------------- | │ │ │ │ │ | | │ │ │ │ │ descent | │ │ │ │ │ | | │ │ │ │ │ ------------------------- │ │ │ │ │ See also: _a_l___g_e_t___t_e_x_t___w_i_d_t_h, _a_l___g_e_t___t_e_x_t___d_i_m_e_n_s_i_o_n_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t___j_u_s_t_i_f_y_._c_p_p │ │ │ │ │ + * _e_x___m_e_m_b_m_p_._c │ │ │ │ │ + * _e_x___m_o_u_s_e___w_a_r_p_._c │ │ │ │ │ ********** aall__ggeett__ffoonntt__aasscceenntt ********** │ │ │ │ │ int al_get_font_ascent(const ALLEGRO_FONT *f) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the ascent of the specified font. │ │ │ │ │ See also: _a_l___g_e_t___f_o_n_t___d_e_s_c_e_n_t, _a_l___g_e_t___f_o_n_t___l_i_n_e___h_e_i_g_h_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ********** aall__ggeett__ffoonntt__ddeesscceenntt ********** │ │ │ │ │ int al_get_font_descent(const ALLEGRO_FONT *f) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the descent of the specified font. │ │ │ │ │ See also: _a_l___g_e_t___f_o_n_t___a_s_c_e_n_t, _a_l___g_e_t___f_o_n_t___l_i_n_e___h_e_i_g_h_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ********** aall__ggeett__tteexxtt__wwiiddtthh ********** │ │ │ │ │ int al_get_text_width(const ALLEGRO_FONT *f, const char *str) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Calculates the length of a string in a particular font, in pixels. │ │ │ │ │ See also: _a_l___g_e_t___u_s_t_r___w_i_d_t_h, _a_l___g_e_t___f_o_n_t___l_i_n_e___h_e_i_g_h_t, _a_l___g_e_t___t_e_x_t___d_i_m_e_n_s_i_o_n_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_i_s_p_l_a_y___o_p_t_i_o_n_s_._c │ │ │ │ │ + * _e_x___r_e_c_o_r_d___n_a_m_e_._c │ │ │ │ │ + * _e_x___c_o_l_o_r___g_r_a_d_i_e_n_t_._c │ │ │ │ │ ********** aall__ggeett__uussttrr__wwiiddtthh ********** │ │ │ │ │ int al_get_ustr_width(const ALLEGRO_FONT *f, ALLEGRO_USTR const *ustr) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___g_e_t___t_e_x_t___w_i_d_t_h but expects an ALLEGRO_USTR. │ │ │ │ │ See also: _a_l___g_e_t___t_e_x_t___w_i_d_t_h, _a_l___g_e_t___u_s_t_r___d_i_m_e_n_s_i_o_n_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ ********** aall__ddrraaww__tteexxtt ********** │ │ │ │ │ void al_draw_text(const ALLEGRO_FONT *font, │ │ │ │ │ ALLEGRO_COLOR color, float x, float y, int flags, │ │ │ │ │ char const *text) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Writes the NUL-terminated string text onto the target bitmap at position x, y, │ │ │ │ │ using the specified font. │ │ │ │ │ @@ -242,35 +274,45 @@ │ │ │ │ │ It can also be combined with this flag: │ │ │ │ │ * ALLEGRO_ALIGN_INTEGER - Always draw text aligned to an integer pixel │ │ │ │ │ position. This was formerly the default behaviour. Since: 5.0.8, 5.1.4 │ │ │ │ │ This function does not support newline characters (\n), but you can use │ │ │ │ │ _a_l___d_r_a_w___m_u_l_t_i_l_i_n_e___t_e_x_t for multi line text output. │ │ │ │ │ See also: _a_l___d_r_a_w___u_s_t_r, _a_l___d_r_a_w___t_e_x_t_f, _a_l___d_r_a_w___j_u_s_t_i_f_i_e_d___t_e_x_t, │ │ │ │ │ _a_l___d_r_a_w___m_u_l_t_i_l_i_n_e___t_e_x_t. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_i_s_a_b_l_e___s_c_r_e_e_n_s_a_v_e_r_._c │ │ │ │ │ + * _e_x___t_i_m_e_d_w_a_i_t_._c │ │ │ │ │ + * _e_x___d_i_s_p_l_a_y___e_v_e_n_t_s_._c │ │ │ │ │ ********** aall__ddrraaww__uussttrr ********** │ │ │ │ │ void al_draw_ustr(const ALLEGRO_FONT *font, │ │ │ │ │ ALLEGRO_COLOR color, float x, float y, int flags, │ │ │ │ │ const ALLEGRO_USTR *ustr) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___d_r_a_w___t_e_x_t, except the text is passed as an ALLEGRO_USTR instead of a │ │ │ │ │ NUL-terminated char array. │ │ │ │ │ See also: _a_l___d_r_a_w___t_e_x_t, _a_l___d_r_a_w___j_u_s_t_i_f_i_e_d___u_s_t_r, _a_l___d_r_a_w___m_u_l_t_i_l_i_n_e___u_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t___m_u_l_t_i_l_i_n_e_._c_p_p │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ + * _e_x___b_l_e_n_d_._c │ │ │ │ │ ********** aall__ddrraaww__jjuussttiiffiieedd__tteexxtt ********** │ │ │ │ │ void al_draw_justified_text(const ALLEGRO_FONT *font, │ │ │ │ │ ALLEGRO_COLOR color, float x1, float x2, │ │ │ │ │ float y, float diff, int flags, const char *text) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___d_r_a_w___t_e_x_t, but justifies the string to the region x1-x2. │ │ │ │ │ The diff parameter is the maximum amount of horizontal space to allow between │ │ │ │ │ words. If justisfying the text would exceed diff pixels, or the string contains │ │ │ │ │ less than two words, then the string will be drawn left aligned. │ │ │ │ │ The flags parameter can be 0 or one of the following flags: │ │ │ │ │ * ALLEGRO_ALIGN_INTEGER - Draw text aligned to integer pixel positions. │ │ │ │ │ Since: 5.0.8, 5.1.5 │ │ │ │ │ See also: _a_l___d_r_a_w___j_u_s_t_i_f_i_e_d___t_e_x_t_f, _a_l___d_r_a_w___j_u_s_t_i_f_i_e_d___u_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t___j_u_s_t_i_f_y_._c_p_p │ │ │ │ │ ********** aall__ddrraaww__jjuussttiiffiieedd__uussttrr ********** │ │ │ │ │ void al_draw_justified_ustr(const ALLEGRO_FONT *font, │ │ │ │ │ ALLEGRO_COLOR color, float x1, float x2, │ │ │ │ │ float y, float diff, int flags, const ALLEGRO_USTR *ustr) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___d_r_a_w___j_u_s_t_i_f_i_e_d___t_e_x_t, except the text is passed as an ALLEGRO_USTR │ │ │ │ │ instead of a NUL-terminated char array. │ │ │ │ │ @@ -279,14 +321,18 @@ │ │ │ │ │ void al_draw_textf(const ALLEGRO_FONT *font, ALLEGRO_COLOR color, │ │ │ │ │ float x, float y, int flags, │ │ │ │ │ const char *format, ...) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Formatted text output, using a printf() style format string. All parameters │ │ │ │ │ have the same meaning as with _a_l___d_r_a_w___t_e_x_t otherwise. │ │ │ │ │ See also: _a_l___d_r_a_w___t_e_x_t, _a_l___d_r_a_w___u_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_i_s_a_b_l_e___s_c_r_e_e_n_s_a_v_e_r_._c │ │ │ │ │ + * _e_x___t_i_m_e_d_w_a_i_t_._c │ │ │ │ │ + * _e_x___d_i_s_p_l_a_y___e_v_e_n_t_s_._c │ │ │ │ │ ********** aall__ddrraaww__jjuussttiiffiieedd__tteexxttff ********** │ │ │ │ │ void al_draw_justified_textf(const ALLEGRO_FONT *f, │ │ │ │ │ ALLEGRO_COLOR color, float x1, float x2, float y, │ │ │ │ │ float diff, int flags, const char *format, ...) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Formatted text output, using a printf() style format string. All parameters │ │ │ │ │ have the same meaning as with _a_l___d_r_a_w___j_u_s_t_i_f_i_e_d___t_e_x_t otherwise. │ │ │ │ │ @@ -301,14 +347,17 @@ │ │ │ │ │ information. │ │ │ │ │ Returned variables (all in pixels): │ │ │ │ │ * x, y - Offset to upper left corner of bounding box. │ │ │ │ │ * w, h - Dimensions of bounding box. │ │ │ │ │ Note that glyphs may go to the left and upwards of the X, in which case x and y │ │ │ │ │ will have negative values. │ │ │ │ │ See also: _a_l___g_e_t___t_e_x_t___w_i_d_t_h, _a_l___g_e_t___f_o_n_t___l_i_n_e___h_e_i_g_h_t, _a_l___g_e_t___u_s_t_r___d_i_m_e_n_s_i_o_n_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ + * _e_x___l_o_g_o_._c │ │ │ │ │ ********** aall__ggeett__uussttrr__ddiimmeennssiioonnss ********** │ │ │ │ │ void al_get_ustr_dimensions(const ALLEGRO_FONT *f, │ │ │ │ │ ALLEGRO_USTR const *ustr, │ │ │ │ │ int *bbx, int *bby, int *bbw, int *bbh) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___g_e_t___t_e_x_t___d_i_m_e_n_s_i_o_n_s, except the text is passed as an ALLEGRO_USTR │ │ │ │ │ instead of a NUL-terminated char array. │ │ │ │ │ @@ -327,22 +376,26 @@ │ │ │ │ │ ranges should be an array with room for ranges_count * 2 elements. The even │ │ │ │ │ integers are the first unicode point in a range, the odd integers the last │ │ │ │ │ unicode point in a range. │ │ │ │ │ Returns the number of ranges contained in the font (even if it is bigger than │ │ │ │ │ ranges_count). │ │ │ │ │ Since: 5.1.4 │ │ │ │ │ See also: _a_l___g_r_a_b___f_o_n_t___f_r_o_m___b_i_t_m_a_p │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ********** aall__sseett__ffaallllbbaacckk__ffoonntt ********** │ │ │ │ │ void al_set_fallback_font(ALLEGRO_FONT *font, ALLEGRO_FONT *fallback) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Sets a font which is used instead if a character is not present. Can be │ │ │ │ │ chained, but make sure there is no loop as that would crash the application! │ │ │ │ │ Pass NULL to remove a fallback font again. │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ See also: _a_l___g_e_t___f_a_l_l_b_a_c_k___f_o_n_t, _a_l___d_r_a_w___g_l_y_p_h, _a_l___d_r_a_w___t_e_x_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ********** aall__ggeett__ffaallllbbaacckk__ffoonntt ********** │ │ │ │ │ ALLEGRO_FONT *al_get_fallback_font(ALLEGRO_FONT *font) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Retrieves the fallback font for this font or NULL. │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ See also: _a_l___s_e_t___f_a_l_l_b_a_c_k___f_o_n_t │ │ │ │ │ ************ PPeerr ggllyypphh tteexxtt hhaannddlliinngg ************ │ │ │ │ │ @@ -369,14 +422,17 @@ │ │ │ │ │ to determine the size and position of each glyph. │ │ │ │ │ If you have to draw many glyphs at the same time, use _a_l___h_o_l_d___b_i_t_m_a_p___d_r_a_w_i_n_g │ │ │ │ │ with true as the parameter, before drawing the glyphs, and then call │ │ │ │ │ _a_l___h_o_l_d___b_i_t_m_a_p___d_r_a_w_i_n_g again with false as a parameter when done drawing the │ │ │ │ │ glyphs to further enhance performance. │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ See also: _a_l___g_e_t___g_l_y_p_h___w_i_d_t_h, _a_l___g_e_t___g_l_y_p_h___d_i_m_e_n_s_i_o_n_s, _a_l___g_e_t___g_l_y_p_h___a_d_v_a_n_c_e. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t_._c │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ********** aall__ggeett__ggllyypphh__wwiiddtthh ********** │ │ │ │ │ int al_get_glyph_width(const ALLEGRO_FONT *f, int codepoint) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This function returns the width in pixels of the glyph that corresponds with │ │ │ │ │ codepoint in the font font. Returns zero if the font does not have such a │ │ │ │ │ glyph. │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ @@ -423,14 +479,16 @@ │ │ │ │ │ +---+--------+ | | ***** | │ │ │ │ │ | | *| │ │ │ │ │ | | * *| │ │ │ │ │ v | **** | │ │ │ │ │ +---+-------+ │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ See also: _a_l___d_r_a_w___g_l_y_p_h, _a_l___g_e_t___g_l_y_p_h___w_i_d_t_h, _a_l___g_e_t___g_l_y_p_h___a_d_v_a_n_c_e. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ********** aall__ggeett__ggllyypphh__aaddvvaannccee ********** │ │ │ │ │ int al_get_glyph_advance(const ALLEGRO_FONT *f, int codepoint1, int codepoint2) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This function returns by how much the x position should be advanced for left to │ │ │ │ │ right text drawing when the glyph that corresponds to codepoint1 has been │ │ │ │ │ drawn, and the glyph that corresponds to codepoint2 will be the next to be │ │ │ │ │ drawn. This takes into consideration the horizontal advance width of the glyph │ │ │ │ │ @@ -482,14 +540,17 @@ │ │ │ │ │ / \ | │ │ │ │ │ /____\ | │ │ │ │ │ / \ | │ │ │ │ │ / \ \_ │ │ │ │ │ --------------- │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ See also: _a_l___d_r_a_w___g_l_y_p_h, _a_l___g_e_t___g_l_y_p_h___w_i_d_t_h, _a_l___g_e_t___g_l_y_p_h___d_i_m_e_n_s_i_o_n_s. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t_._c │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ************ MMuullttiilliinnee tteexxtt ddrraawwiinngg ************ │ │ │ │ │ ********** aall__ddrraaww__mmuullttiilliinnee__tteexxtt ********** │ │ │ │ │ void al_draw_multiline_text(const ALLEGRO_FONT *font, │ │ │ │ │ ALLEGRO_COLOR color, float x, float y, float max_width, float line_height, │ │ │ │ │ int flags, const char *text) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___d_r_a_w___t_e_x_t, but this function supports drawing multiple lines of text. │ │ │ │ │ @@ -516,14 +577,17 @@ │ │ │ │ │ The flags ALLEGRO_ALIGN_LEFT, ALLEGRO_ALIGN_CENTRE, ALLEGRO_ALIGN_RIGHT and │ │ │ │ │ ALLEGRO_ALIGN_INTEGER will be honoured by this function. │ │ │ │ │ If you want to calculate the size of what this function will draw without │ │ │ │ │ actually drawing it, or if you need a complex and/or custom layout, you can use │ │ │ │ │ _a_l___d_o___m_u_l_t_i_l_i_n_e___t_e_x_t. │ │ │ │ │ Since: 5.1.9 │ │ │ │ │ See also: _a_l___d_o___m_u_l_t_i_l_i_n_e___t_e_x_t, _a_l___d_r_a_w___m_u_l_t_i_l_i_n_e___u_s_t_r, _a_l___d_r_a_w___m_u_l_t_i_l_i_n_e___t_e_x_t_f │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t___m_u_l_t_i_l_i_n_e_._c_p_p │ │ │ │ │ + * _e_x___r_e_s_i_z_e_2_._c │ │ │ │ │ ********** aall__ddrraaww__mmuullttiilliinnee__uussttrr ********** │ │ │ │ │ void al_draw_multiline_ustr(const ALLEGRO_FONT *font, │ │ │ │ │ ALLEGRO_COLOR color, float x, float y, float max_width, float line_height, │ │ │ │ │ int flags, const ALLEGRO_USTR *ustr) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___d_r_a_w___m_u_l_t_i_l_i_n_e___t_e_x_t, except the text is passed as an ALLEGRO_USTR │ │ │ │ │ instead of a NUL-terminated char array. │ │ │ │ │ @@ -534,14 +598,16 @@ │ │ │ │ │ ALLEGRO_COLOR color, float x, float y, float max_width, float line_height, │ │ │ │ │ int flags, const char *format, ...) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Formatted text output, using a printf() style format string. All parameters │ │ │ │ │ have the same meaning as with _a_l___d_r_a_w___m_u_l_t_i_l_i_n_e___t_e_x_t otherwise. │ │ │ │ │ Since: 5.1.9 │ │ │ │ │ See also: _a_l___d_r_a_w___m_u_l_t_i_l_i_n_e___t_e_x_t, _a_l___d_r_a_w___m_u_l_t_i_l_i_n_e___u_s_t_r, _a_l___d_o___m_u_l_t_i_l_i_n_e___t_e_x_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___r_e_s_i_z_e_2_._c │ │ │ │ │ ********** aall__ddoo__mmuullttiilliinnee__tteexxtt ********** │ │ │ │ │ void al_do_multiline_text(const ALLEGRO_FONT *font, │ │ │ │ │ float max_width, const char *text, │ │ │ │ │ bool (*cb)(int line_num, const char *line, int size, void *extra), │ │ │ │ │ void *extra) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This function processes the text and splits it into lines as │ │ │ │ │ @@ -561,14 +627,16 @@ │ │ │ │ │ buffer and NUL-terminate it yourself. You will also have to make your own copy │ │ │ │ │ if you need the contents of line after cb has returned, as line is nnoott │ │ │ │ │ guaranteed to be valid after that. │ │ │ │ │ If the callback cb returns false, al_do_multiline_text will stop immediately, │ │ │ │ │ otherwise it will continue on to the next line. │ │ │ │ │ Since: 5.1.9 │ │ │ │ │ See also: _a_l___d_r_a_w___m_u_l_t_i_l_i_n_e___t_e_x_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t___m_u_l_t_i_l_i_n_e_._c_p_p │ │ │ │ │ ********** aall__ddoo__mmuullttiilliinnee__uussttrr ********** │ │ │ │ │ void al_do_multiline_ustr(const ALLEGRO_FONT *font, float max_width, │ │ │ │ │ const ALLEGRO_USTR *ustr, │ │ │ │ │ bool (*cb)(int line_num, const ALLEGRO_USTR * line, void *extra), │ │ │ │ │ void *extra) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___d_o___m_u_l_t_i_l_i_n_e___t_e_x_t, but using ALLEGRO_USTR instead of a NUL-terminated │ │ │ │ │ @@ -621,23 +689,30 @@ │ │ │ │ │ The first example will grab glyphs for the 95 standard printable ASCII │ │ │ │ │ characters, beginning with the space character (32) and ending with the tilde │ │ │ │ │ character (126). The second example will map the first 96 glyphs found in the │ │ │ │ │ bitmap to ASCII range, the next 95 glyphs to Latin 1, the next 128 glyphs to │ │ │ │ │ Extended-A, and the last glyph to the Euro character. (This is just the │ │ │ │ │ characters found in the Allegro 4 font.) │ │ │ │ │ See also: _a_l___l_o_a_d___b_i_t_m_a_p, _a_l___g_r_a_b___f_o_n_t___f_r_o_m___b_i_t_m_a_p │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t_._c │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ********** aall__llooaadd__bbiittmmaapp__ffoonntt ********** │ │ │ │ │ ALLEGRO_FONT *al_load_bitmap_font(const char *fname) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Load a bitmap font from a file. This is done by first calling │ │ │ │ │ _a_l___l_o_a_d___b_i_t_m_a_p___f_l_a_g_s and then _a_l___g_r_a_b___f_o_n_t___f_r_o_m___b_i_t_m_a_p. │ │ │ │ │ If you wanted to load an old A4 font, for example, it would be better to load │ │ │ │ │ the bitmap yourself in order to call _a_l___c_o_n_v_e_r_t___m_a_s_k___t_o___a_l_p_h_a on it before │ │ │ │ │ passing it to _a_l___g_r_a_b___f_o_n_t___f_r_o_m___b_i_t_m_a_p. │ │ │ │ │ See also: _a_l___l_o_a_d___b_i_t_m_a_p___f_o_n_t___f_l_a_g_s, _a_l___l_o_a_d___f_o_n_t, _a_l___l_o_a_d___b_i_t_m_a_p___f_l_a_g_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___b_i_t_m_a_p___f_l_i_p_._c │ │ │ │ │ + * _e_x___m_o_u_s_e___c_u_r_s_o_r_._c │ │ │ │ │ + * _e_x___r_e_c_o_r_d___n_a_m_e_._c │ │ │ │ │ ********** aall__llooaadd__bbiittmmaapp__ffoonntt__ffllaaggss ********** │ │ │ │ │ ALLEGRO_FONT *al_load_bitmap_font_flags(const char *fname, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___l_o_a_d___b_i_t_m_a_p___f_o_n_t but additionally takes a flags parameter which is a │ │ │ │ │ bitfield containing a combination of the following: │ │ │ │ │ ALLEGRO_NO_PREMULTIPLIED_ALPHA │ │ │ │ │ The same meaning as for _a_l___l_o_a_d___b_i_t_m_a_p___f_l_a_g_s. │ │ │ │ │ @@ -655,24 +730,32 @@ │ │ │ │ │ 0x0100 to 0x017F (Extended A) │ │ │ │ │ 0x20AC to 0x20AC (euro currency symbol) │ │ │ │ │ Returns NULL on an error. │ │ │ │ │ The font memory must be freed the same way as for any other font, using │ │ │ │ │ _a_l___d_e_s_t_r_o_y___f_o_n_t. │ │ │ │ │ Since: 5.0.8, 5.1.3 │ │ │ │ │ See also: _a_l___l_o_a_d___b_i_t_m_a_p___f_o_n_t, _a_l___d_e_s_t_r_o_y___f_o_n_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_i_s_a_b_l_e___s_c_r_e_e_n_s_a_v_e_r_._c │ │ │ │ │ + * _e_x___t_i_m_e_d_w_a_i_t_._c │ │ │ │ │ + * _e_x___d_i_s_p_l_a_y___e_v_e_n_t_s_._c │ │ │ │ │ ************ TTTTFF ffoonnttss ************ │ │ │ │ │ These functions are declared in the following header file. Link with │ │ │ │ │ allegro_ttf. │ │ │ │ │ #include │ │ │ │ │ ********** aall__iinniitt__ttttff__aaddddoonn ********** │ │ │ │ │ bool al_init_ttf_addon(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Call this after _a_l___i_n_i_t___f_o_n_t___a_d_d_o_n to make _a_l___l_o_a_d___f_o_n_t recognize “.ttf” and │ │ │ │ │ other formats supported by _a_l___l_o_a_d___t_t_f___f_o_n_t. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t___j_u_s_t_i_f_y_._c_p_p │ │ │ │ │ + * _e_x___f_o_n_t___m_u_l_t_i_l_i_n_e_._c_p_p │ │ │ │ │ + * _e_x___c_o_l_o_r_._c_p_p │ │ │ │ │ ********** aall__iiss__ttttff__aaddddoonn__iinniittiiaalliizzeedd ********** │ │ │ │ │ bool al_is_ttf_addon_initialized(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true if the TTF addon is initialized, otherwise returns false. │ │ │ │ │ Since: 5.2.6 │ │ │ │ │ See also: _a_l___i_n_i_t___t_t_f___a_d_d_o_n, _a_l___s_h_u_t_d_o_w_n___t_t_f___a_d_d_o_n │ │ │ │ │ ********** aall__sshhuuttddoowwnn__ttttff__aaddddoonn ********** │ │ │ │ │ @@ -695,14 +778,18 @@ │ │ │ │ │ * ALLEGRO_TTF_NO_KERNING - Do not use any kerning even if the font file │ │ │ │ │ supports it. │ │ │ │ │ * ALLEGRO_TTF_MONOCHROME - Load as a monochrome font (which means no anti- │ │ │ │ │ aliasing of the font is done). │ │ │ │ │ * ALLEGRO_TTF_NO_AUTOHINT - Disable the Auto Hinter which is enabled by │ │ │ │ │ default in newer versions of FreeType. Since: 5.0.6, 5.1.2 │ │ │ │ │ See also: _a_l___i_n_i_t___t_t_f___a_d_d_o_n, _a_l___l_o_a_d___t_t_f___f_o_n_t___f │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___b_i_t_m_a_p___f_l_i_p_._c │ │ │ │ │ + * _e_x___s_y_n_t_h_._c_p_p │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ********** aall__llooaadd__ttttff__ffoonntt__ff ********** │ │ │ │ │ ALLEGRO_FONT *al_load_ttf_font_f(ALLEGRO_FILE *file, │ │ │ │ │ char const *filename, int size, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___l_o_a_d___t_t_f___f_o_n_t, but the font is read from the file handle. The filename │ │ │ │ │ is only used to find possible additional files next to a font file. │ │ │ │ │ NNoottee:: The file handle is owned by the returned ALLEGRO_FONT object │ │ │ │ │ @@ -747,8 +834,11 @@ │ │ │ │ │ yourself. prev_codepoint is the codepoint in the string before the one you want │ │ │ │ │ to draw and is used for kerning. codepoint is the character you want to get │ │ │ │ │ info about. You should clear the ‘glyph’ structure to 0 with memset before │ │ │ │ │ passing it to this function for future compatibility. │ │ │ │ │ Since: 5.2.1 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: This API is new and subject to refinement. │ │ │ │ │ See also: _A_L_L_E_G_R_O___G_L_Y_P_H │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t_._c │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/fshook.html │ │ │ │ @@ -250,14 +250,21 @@ │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Opaque filesystem entry object. Represents a file or a directory │ │ │ │ (check with al_get_fs_entry_mode). There │ │ │ │ are no user accessible member variables.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_FILE_MODE

    │ │ │ │ 
    typedef enum ALLEGRO_FILE_MODE
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Filesystem modes/types

    │ │ │ │ │ │ │ │

    See also: al_lock_bitmap, │ │ │ │ al_lock_bitmap_region, │ │ │ │ al_unlock_bitmap, ALLEGRO_PIXEL_FORMAT

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_PIXEL_FORMAT

    │ │ │ │ 
    typedef enum ALLEGRO_PIXEL_FORMAT
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Pixel formats. Each pixel format specifies the exact size and bit │ │ │ │ layout of a pixel in memory. Components are specified from high bits to │ │ │ │ @@ -754,14 +838,23 @@ │ │ │ │ bytes, resulting in 4x compression ratio. This format supports smooth │ │ │ │ alpha transitions. Since 5.1.9. │ │ │ │ │ │ │ │

    See also: al_set_new_bitmap_format, │ │ │ │ al_get_bitmap_format

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_pixel_size

    │ │ │ │ 
    int al_get_pixel_size(int format)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the number of bytes that a pixel of the given format occupies. │ │ │ │ For blocked pixel formats (e.g. compressed formats), this returns 0.

    │ │ │ │ @@ -799,26 +892,36 @@ │ │ │ │

    Return the width of the the pixel block for this format.

    │ │ │ │

    Since: 5.1.9.

    │ │ │ │

    See also: ALLEGRO_PIXEL_FORMAT, al_get_pixel_block_size, │ │ │ │ al_get_pixel_block_height

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_pixel_block_height

    │ │ │ │ 
    int al_get_pixel_block_height(int format)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the height of the the pixel block for this format.

    │ │ │ │

    Since: 5.1.9.

    │ │ │ │

    See also: ALLEGRO_PIXEL_FORMAT, al_get_pixel_block_size, │ │ │ │ al_get_pixel_block_width

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_lock_bitmap

    │ │ │ │ 
    ALLEGRO_LOCKED_REGION *al_lock_bitmap(ALLEGRO_BITMAP *bitmap,
│ │ │ │     int format, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Lock an entire bitmap for reading or writing. If the bitmap is a │ │ │ │ @@ -871,15 +974,15 @@ │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_lock_bitmap_region

    │ │ │ │ 
    ALLEGRO_LOCKED_REGION *al_lock_bitmap_region(ALLEGRO_BITMAP *bitmap,
│ │ │ │     int x, int y, int width, int height, int format, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -904,17 +1007,17 @@ │ │ │ │ href="graphics.html#allegro_pixel_format">ALLEGRO_PIXEL_FORMAT, al_unlock_bitmap

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_unlock_bitmap

    │ │ │ │ 
    void al_unlock_bitmap(ALLEGRO_BITMAP *bitmap)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Unlock a previously locked bitmap or bitmap region. If the bitmap is │ │ │ │ @@ -927,17 +1030,17 @@ │ │ │ │ al_lock_bitmap_region_blocked

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_lock_bitmap_blocked

    │ │ │ │ 
    ALLEGRO_LOCKED_REGION *al_lock_bitmap_blocked(ALLEGRO_BITMAP *bitmap,
│ │ │ │     int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -985,14 +1088,23 @@ │ │ │ │

    Bitmap creation

    │ │ │ │

    ALLEGRO_BITMAP

    │ │ │ │ 
    typedef struct ALLEGRO_BITMAP ALLEGRO_BITMAP;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Abstract type representing a bitmap (2D image).

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_create_bitmap

    │ │ │ │ 
    ALLEGRO_BITMAP *al_create_bitmap(int w, int h)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Creates a new bitmap using the bitmap format and flags for the │ │ │ │ current thread. Blitting between bitmaps of differing formats, or │ │ │ │ @@ -1051,19 +1163,19 @@ │ │ │ │ al_clone_bitmap, al_create_sub_bitmap, al_convert_memory_bitmaps, │ │ │ │ al_destroy_bitmap

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_create_sub_bitmap

    │ │ │ │ 
    ALLEGRO_BITMAP *al_create_sub_bitmap(ALLEGRO_BITMAP *parent,
│ │ │ │     int x, int y, int w, int h)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -1089,19 +1201,19 @@ │ │ │ │ does not matter whether you destroy a sub-bitmap before or after its │ │ │ │ parent otherwise.

    │ │ │ │

    See also: al_create_bitmap

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_clone_bitmap

    │ │ │ │ 
    ALLEGRO_BITMAP *al_clone_bitmap(ALLEGRO_BITMAP *bitmap)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Create a new bitmap with al_set_new_bitmap_format, │ │ │ │ al_set_new_bitmap_flags, │ │ │ │ al_convert_bitmap

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_convert_bitmap

    │ │ │ │ 
    void al_convert_bitmap(ALLEGRO_BITMAP *bitmap)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Converts the bitmap to the current bitmap flags and format. The │ │ │ │ @@ -1197,14 +1309,19 @@ │ │ │ │ 

    int al_get_new_bitmap_flags(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the flags used for newly created bitmaps.

    │ │ │ │

    See also: al_set_new_bitmap_flags

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_new_bitmap_format

    │ │ │ │ 
    int al_get_new_bitmap_format(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the format used for newly created bitmaps.

    │ │ │ │

    See also: │ │ │ │ │ │ │ │ │ │ │ │

    See also: al_get_new_bitmap_flags, │ │ │ │ al_get_bitmap_flags

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_add_new_bitmap_flag

    │ │ │ │ 
    void al_add_new_bitmap_flag(int flag)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    A convenience function which does the same as

    │ │ │ │ 
    al_set_new_bitmap_flags(al_get_new_bitmap_flags() | flag);
    │ │ │ │

    See also: al_set_new_bitmap_flags, │ │ │ │ al_get_new_bitmap_flags, │ │ │ │ al_get_bitmap_flags

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_new_bitmap_format

    │ │ │ │ 
    void al_set_new_bitmap_format(int format)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Sets the pixel format (ALLEGRO_PIXEL_FORMAT) for │ │ │ │ newly created bitmaps. The default format is 0 and means the display │ │ │ │ driver will choose the best format.

    │ │ │ │

    See also: ALLEGRO_PIXEL_FORMAT, al_get_new_bitmap_format, │ │ │ │ al_get_bitmap_format

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_new_bitmap_depth

    │ │ │ │ 
    void al_set_new_bitmap_depth(int depth)
│ │ │ │  SETTER(new_bitmap_depth, depth)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Sets the depthbuffer depth used by newly created bitmaps (on the │ │ │ │ @@ -1340,14 +1480,19 @@ │ │ │ │ which is the default.

    │ │ │ │

    Since: 5.2.1

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: This is an experimental feature and currently only works │ │ │ │ for the OpenGL backend.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_new_bitmap_depth

    │ │ │ │ 
    int al_get_new_bitmap_depth(void)
│ │ │ │  GETTER(new_bitmap_depth, 0)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the value currently set with │ │ │ │

    Since: 5.2.1

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: This is an experimental feature and currently only works │ │ │ │ for the OpenGL backend.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_new_bitmap_samples

    │ │ │ │ 
    int al_get_new_bitmap_samples(void)
│ │ │ │  GETTER(new_bitmap_samples, 0)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the value currently set with Since: 5.2.8

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: This is an experimental feature.

    │ │ │ │
    │ │ │ │

    See also: ALLEGRO_BITMAP_WRAP

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_new_bitmap_wrap

    │ │ │ │

    Source Code

    │ │ │ │

    Returns the value currently set with al_set_new_bitmap_wrap │ │ │ │ on the current thread.

    │ │ │ │

    Since: 5.2.8

    │ │ │ │
    │ │ │ │ @@ -1463,14 +1622,21 @@ │ │ │ │

  • ALLEGRO_BITMAP_WRAP_REPEAT - The texture coordinates get shifted │ │ │ │ to the opposite edge that they go past.

    • │ │ │ │

  • ALLEGRO_BITMAP_WRAP_CLAMP - The texture coordinates get clamped │ │ │ │ to the edges that they go past.

    • │ │ │ │

  • ALLEGRO_BITMAP_WRAP_MIRROR - The texture coordinates get mirrored │ │ │ │ across the edges that they go past.

    • │ │ │ │ │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Bitmap properties

    │ │ │ │

    al_get_bitmap_flags

    │ │ │ │ 
    int al_get_bitmap_flags(ALLEGRO_BITMAP *bitmap)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the flags used to create the bitmap.

    │ │ │ │ @@ -1504,34 +1670,34 @@ │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the height of a bitmap in pixels.

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_get_bitmap_width

    │ │ │ │ 
    int al_get_bitmap_width(ALLEGRO_BITMAP *bitmap)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the width of a bitmap in pixels.

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_get_bitmap_depth

    │ │ │ │ 
    int al_get_bitmap_depth(ALLEGRO_BITMAP *bitmap)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the depthbuffer depth used by this bitmap if it is used with │ │ │ │ @@ -1569,17 +1735,17 @@ │ │ │ │ href="graphics.html#al_put_pixel">al_put_pixel, al_lock_bitmap

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_is_bitmap_locked

    │ │ │ │ 
    bool al_is_bitmap_locked(ALLEGRO_BITMAP *bitmap)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns whether or not a bitmap is already locked.

    │ │ │ │ @@ -1683,17 +1849,17 @@ │ │ │ │

    See also: al_create_sub_bitmap, al_get_parent_bitmap

    │ │ │ │

    Since: 5.1.12

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_get_bitmap_blender

    │ │ │ │ 
    void al_get_bitmap_blender(int *op, int *src, int *dst)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the current blender being used by the target bitmap. You can │ │ │ │ @@ -1836,19 +2002,19 @@ │ │ │ │

    See also: ALLEGRO_COLOR, al_set_clipping_rectangle, │ │ │ │ al_clear_depth_buffer

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_clear_depth_buffer

    │ │ │ │ 
    void al_clear_depth_buffer(float z)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Clear the depth buffer (confined by the clipping rectangle) to the │ │ │ │ @@ -1869,19 +2035,19 @@ │ │ │ │ href="graphics.html#al_clear_to_color">al_clear_to_color, al_set_clipping_rectangle, │ │ │ │ al_set_render_state, al_set_new_display_option

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_draw_bitmap

    │ │ │ │ 
    void al_draw_bitmap(ALLEGRO_BITMAP *bitmap, float dx, float dy, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws an unscaled, unrotated bitmap at the given position to the │ │ │ │ @@ -1911,19 +2077,19 @@ │ │ │ │ href="graphics.html#al_draw_scaled_bitmap">al_draw_scaled_bitmap, al_draw_rotated_bitmap, │ │ │ │ al_draw_scaled_rotated_bitmap

    │ │ │ │

    Examples:

    │ │ │ │
      │ │ │ │
    • ex_mouse.c
      • │ │ │ │ +href="https://github.com/liballeg/allegro5/blob/master/examples/ex_nodisplay.c#L42">ex_nodisplay.c │ │ │ │
    • ex_opengl_pixel_shader.c
      • │ │ │ │
    • ex_shader.cpp
      • │ │ │ │ +href="https://github.com/liballeg/allegro5/blob/master/examples/ex_blend_bench.c#L42">ex_blend_bench.c │ │ │ │
    │ │ │ │

    al_draw_tinted_bitmap

    │ │ │ │ 
    void al_draw_tinted_bitmap(ALLEGRO_BITMAP *bitmap, ALLEGRO_COLOR tint,
│ │ │ │     float dx, float dy, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -1941,15 +2107,15 @@ │ │ │ │

    See also: al_draw_bitmap

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_draw_bitmap_region

    │ │ │ │ 
    void al_draw_bitmap_region(ALLEGRO_BITMAP *bitmap,
│ │ │ │     float sx, float sy, float sw, float sh, float dx, float dy, int flags)
    │ │ │ │

    al_draw_rotated_bitmap, │ │ │ │ al_draw_scaled_rotated_bitmap

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_draw_tinted_bitmap_region

    │ │ │ │ 
    void al_draw_tinted_bitmap_region(ALLEGRO_BITMAP *bitmap,
│ │ │ │     ALLEGRO_COLOR tint,
│ │ │ │     float sx, float sy, float sw, float sh, float dx, float dy,
│ │ │ │     int flags)
    │ │ │ │ @@ -1997,17 +2163,17 @@ │ │ │ │

    See al_draw_bitmap for a │ │ │ │ note on restrictions on which bitmaps can be drawn where.

    │ │ │ │

    See also: al_draw_tinted_bitmap

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_draw_pixel

    │ │ │ │ 
    void al_draw_pixel(float x, float y, ALLEGRO_COLOR color)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws a single pixel at x, y. This function, unlike See also: ALLEGRO_COLOR, al_put_pixel

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_draw_rotated_bitmap

    │ │ │ │ 
    void al_draw_rotated_bitmap(ALLEGRO_BITMAP *bitmap,
│ │ │ │     float cx, float cy, float dx, float dy, float angle, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -2076,17 +2242,17 @@ │ │ │ │ al_draw_scaled_rotated_bitmap

    │ │ │ │

    Examples:

    │ │ │ │
      │ │ │ │
    • ex_blend2.cpp
      • │ │ │ │
    • ex_multisample_target.c
      • │ │ │ │ +href="https://github.com/liballeg/allegro5/blob/master/examples/ex_multisample.c#L103">ex_multisample.c │ │ │ │
    • ex_palette.c
      • │ │ │ │ +href="https://github.com/liballeg/allegro5/blob/master/examples/ex_multisample_target.c#L111">ex_multisample_target.c │ │ │ │
    │ │ │ │

    al_draw_tinted_rotated_bitmap

    │ │ │ │ 
    void al_draw_tinted_rotated_bitmap(ALLEGRO_BITMAP *bitmap,
│ │ │ │     ALLEGRO_COLOR tint,
│ │ │ │     float cx, float cy, float dx, float dy, float angle, int flags)
    │ │ │ │

    al_draw_rotated_bitmap

    │ │ │ │

    Examples:

    │ │ │ │
      │ │ │ │
    • ex_blend_bench.c
      • │ │ │ │
    • ex_premulalpha.c
      • │ │ │ │ +href="https://github.com/liballeg/allegro5/blob/master/examples/ex_bitmap.c#L151">ex_bitmap.c │ │ │ │
    • ex_shader_multitex.c
      • │ │ │ │ +href="https://github.com/liballeg/allegro5/blob/master/examples/ex_bitmap_file.c#L160">ex_bitmap_file.c │ │ │ │
    │ │ │ │

    al_draw_tinted_scaled_rotated_bitmap

    │ │ │ │ 
    void al_draw_tinted_scaled_rotated_bitmap(ALLEGRO_BITMAP *bitmap,
│ │ │ │     ALLEGRO_COLOR tint,
│ │ │ │     float cx, float cy, float dx, float dy, float xscale, float yscale,
│ │ │ │     float angle, int flags)
    │ │ │ │ @@ -2227,15 +2393,15 @@ │ │ │ │

    Examples:

    │ │ │ │
      │ │ │ │
    • ex_blend_bench.c
      • │ │ │ │
    • ex_dualies.c
      • │ │ │ │
    • ex_membmp.c
      • │ │ │ │ +href="https://github.com/liballeg/allegro5/blob/master/examples/ex_multiwin.c#L107">ex_multiwin.c │ │ │ │
    │ │ │ │

    al_draw_tinted_scaled_bitmap

    │ │ │ │ 
    void al_draw_tinted_scaled_bitmap(ALLEGRO_BITMAP *bitmap,
│ │ │ │     ALLEGRO_COLOR tint,
│ │ │ │     float sx, float sy, float sw, float sh,
│ │ │ │     float dx, float dy, float dw, float dh, int flags)
    │ │ │ │ 

    ALLEGRO_BITMAP *al_get_target_bitmap(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the target bitmap of the calling thread.

    │ │ │ │

    See also: al_set_target_bitmap

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_put_pixel

    │ │ │ │ 
    void al_put_pixel(int x, int y, ALLEGRO_COLOR color)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draw a single pixel on the target bitmap. This operation is slow on │ │ │ │ non-memory bitmaps. Consider locking the bitmap if you are going to use │ │ │ │ @@ -2279,17 +2454,17 @@ │ │ │ │ href="graphics.html#al_put_blended_pixel">al_put_blended_pixel, al_lock_bitmap

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_put_blended_pixel

    │ │ │ │ 
    void al_put_blended_pixel(int x, int y, ALLEGRO_COLOR color)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Like al_put_pixel, but the │ │ │ │ @@ -2361,33 +2536,60 @@ │ │ │ │ 

    al_set_target_bitmap(bitmap);
│ │ │ │  al_draw_line(x1, y1, x2, y2, color, 0);
    │ │ │ │

    An OpenGL command will be used to directly draw the line into the │ │ │ │ bitmap’s associated texture.

    │ │ │ │

    See also: al_get_target_bitmap, al_set_target_backbuffer

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_target_backbuffer

    │ │ │ │ 
    void al_set_target_backbuffer(ALLEGRO_DISPLAY *display)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Same as │ │ │ │ al_set_target_bitmap(al_get_backbuffer(display));

    │ │ │ │

    See also: al_set_target_bitmap, al_get_backbuffer

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_current_display

    │ │ │ │ 
    ALLEGRO_DISPLAY *al_get_current_display(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the display that is “current” for the calling thread, or NULL │ │ │ │ if there is none.

    │ │ │ │

    See also: al_set_target_bitmap

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Blending modes

    │ │ │ │

    al_get_blender

    │ │ │ │ 
    void al_get_blender(int *op, int *src, int *dst)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the active blender for the current thread. You can pass NULL │ │ │ │ @@ -2519,14 +2721,23 @@ │ │ │ │ g = d.g * 0 + s.g * d.g │ │ │ │ b = d.b * 0 + s.b * d.b │ │ │ │ a = d.a * 0 + s.a * d.a │ │ │ │

    See also: al_set_separate_blender, │ │ │ │ al_set_blend_color, al_get_blender

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_separate_blender

    │ │ │ │ 
    void al_set_separate_blender(int op, int src, int dst,
│ │ │ │     int alpha_op, int alpha_src, int alpha_dst)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -2534,27 +2745,41 @@ │ │ │ │ allows specifying a separate blending operation for the alpha channel. │ │ │ │ This is useful if your target bitmap also has an alpha channel and the │ │ │ │ two alpha channels need to be combined in a different way than the color │ │ │ │ components.

    │ │ │ │

    See also: al_set_blender, │ │ │ │ al_get_blender, al_get_separate_blender

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_blend_color

    │ │ │ │ 
    void al_set_blend_color(ALLEGRO_COLOR color)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Sets the color to use for blending when using the ALLEGRO_CONST_COLOR │ │ │ │ or ALLEGRO_INVERSE_CONST_COLOR blend functions. See al_set_blender for more │ │ │ │ information.

    │ │ │ │

    See also: al_set_blender, │ │ │ │ al_get_blend_color

    │ │ │ │

    Since: 5.1.12

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Clipping

    │ │ │ │

    al_get_clipping_rectangle

    │ │ │ │ 
    void al_get_clipping_rectangle(int *x, int *y, int *w, int *h)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -2581,19 +2806,19 @@ │ │ │ │

    See also: al_get_clipping_rectangle, │ │ │ │ al_reset_clipping_rectangle

    │ │ │ │

    Examples:

    │ │ │ │
      │ │ │ │
    • nihgui.cpp
      • │ │ │ │ +href="https://github.com/liballeg/allegro5/blob/master/examples/ex_rotate.c#L139">ex_rotate.c │ │ │ │
    • ex_lines.c
      • │ │ │ │ +href="https://github.com/liballeg/allegro5/blob/master/examples/ex_scale.c#L145">ex_scale.c │ │ │ │
    • ex_rotate.c
      • │ │ │ │ +href="https://github.com/liballeg/allegro5/blob/master/examples/ex_lines.c#L45">ex_lines.c │ │ │ │
    │ │ │ │

    al_reset_clipping_rectangle

    │ │ │ │ 
    void al_reset_clipping_rectangle(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -2614,17 +2839,17 @@ │ │ │ │

    Convert the given mask color to an alpha channel in the bitmap. Can │ │ │ │ be used to convert older 4.2-style bitmaps with magic pink to │ │ │ │ alpha-ready bitmaps.

    │ │ │ │

    See also: ALLEGRO_COLOR

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    Deferred drawing

    │ │ │ │

    al_hold_bitmap_drawing

    │ │ │ │ 
    void al_hold_bitmap_drawing(bool hold)
    │ │ │ │

    Source │ │ │ │ @@ -2650,17 +2875,17 @@ │ │ │ │

    See also: al_is_bitmap_drawing_held

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_is_bitmap_drawing_held

    │ │ │ │ 
    bool al_is_bitmap_drawing_held(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -2779,17 +3004,17 @@ │ │ │ │ href="graphics.html#al_set_new_bitmap_flags">al_set_new_bitmap_flags, │ │ │ │ al_init_image_addon

    │ │ │ │

    Examples:

    │ │ │ │
      │ │ │ │
    • ex_convert.c
      • │ │ │ │
    • ex_mouse.c
      • │ │ │ │ +href="https://github.com/liballeg/allegro5/blob/master/examples/ex_nodisplay.c#L25">ex_nodisplay.c │ │ │ │
    • ex_opengl_pixel_shader.c
      • │ │ │ │ +href="https://github.com/liballeg/allegro5/blob/master/examples/ex_file_slice.c#L65">ex_file_slice.c │ │ │ │
    │ │ │ │

    al_load_bitmap_flags

    │ │ │ │ 
    ALLEGRO_BITMAP *al_load_bitmap_flags(const char *filename, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -2925,17 +3150,17 @@ │ │ │ │ href="graphics.html#al_register_bitmap_loader_f">al_register_bitmap_loader_f, │ │ │ │ al_init_image_addon

    │ │ │ │

    Examples:

    │ │ │ │
      │ │ │ │
    • ex_convert.c
      • │ │ │ │
    • ex_record_name.c
      • │ │ │ │ +href="https://github.com/liballeg/allegro5/blob/master/examples/ex_file_slice.c#L65">ex_file_slice.c │ │ │ │
    • ex_bitmap_flip.c
      • │ │ │ │ +href="https://github.com/liballeg/allegro5/blob/master/examples/ex_bitmap_file.c#L83">ex_bitmap_file.c │ │ │ │
    │ │ │ │

    al_load_bitmap_flags_f

    │ │ │ │ 
    ALLEGRO_BITMAP *al_load_bitmap_flags_f(ALLEGRO_FILE *fp,
│ │ │ │     const char *ident, int flags)
    │ │ │ │

    Source │ │ │ │ @@ -3071,15 +3296,19 @@ │ │ │ │

    Since: 5.1.12

    │ │ │ │

    See also: al_init_image_addon, al_identify_bitmap, al_register_bitmap_identifier

    │ │ │ │

    Render State

    │ │ │ │

    ALLEGRO_RENDER_STATE

    │ │ │ │ -

    Source Code

    │ │ │ │ +
    typedef enum ALLEGRO_RENDER_STATE {
    │ │ │ │ +

    Source │ │ │ │ +Code

    │ │ │ │

    Possible render states which can be set with al_set_render_state:

    │ │ │ │
    │ │ │ │
    ALLEGRO_ALPHA_TEST
    │ │ │ │
    │ │ │ │ If this is set to 1, the values of ALLEGRO_ALPHA_FUNCTION and │ │ │ │ ALLEGRO_ALPHA_TEST_VALUE define a comparison function which is performed │ │ │ │ @@ -3123,15 +3352,19 @@ │ │ │ │

    Since: 5.1.2

    │ │ │ │

    See also: al_set_render_state, ALLEGRO_RENDER_FUNCTION, │ │ │ │ ALLEGRO_WRITE_MASK_FLAGS

    │ │ │ │

    ALLEGRO_RENDER_FUNCTION

    │ │ │ │ -

    Source Code

    │ │ │ │ +
    typedef enum ALLEGRO_RENDER_FUNCTION {
    │ │ │ │ +

    Source │ │ │ │ +Code

    │ │ │ │

    Possible functions are:

    │ │ │ │
      │ │ │ │
    • ALLEGRO_RENDER_NEVER
      • │ │ │ │
    • ALLEGRO_RENDER_ALWAYS
      • │ │ │ │
    • ALLEGRO_RENDER_LESS
      • │ │ │ │
    • ALLEGRO_RENDER_EQUAL
      • │ │ │ │
    • ALLEGRO_RENDER_LESS_EQUAL
      │ │ │ │ @@ -3141,15 +3374,19 @@ │ │ │ │
    • ALLEGRO_RENDER_NOT_EQUAL
      • │ │ │ │
    • ALLEGRO_RENDER_GREATER_EQUAL
      • │ │ │ │
    │ │ │ │

    Since: 5.1.2

    │ │ │ │

    See also: al_set_render_state

    │ │ │ │

    ALLEGRO_WRITE_MASK_FLAGS

    │ │ │ │ -

    Source Code

    │ │ │ │ +
    typedef enum ALLEGRO_WRITE_MASK_FLAGS {
    │ │ │ │ +

    Source │ │ │ │ +Code

    │ │ │ │

    Each enabled bit means the corresponding value is written, a disabled │ │ │ │ bit means it is not.

    │ │ │ │
      │ │ │ │
    • ALLEGRO_MASK_RED
      • │ │ │ │
    • ALLEGRO_MASK_GREEN
      • │ │ │ │
    • ALLEGRO_MASK_BLUE
      • │ │ │ │
    • ALLEGRO_MASK_ALPHA
      • │ │ │ │ @@ -3157,16 +3394,16 @@ │ │ │ │
    • ALLEGRO_MASK_RGB - Same as RED | GREEN | BLUE.
      • │ │ │ │
    • ALLEGRO_MASK_RGBA - Same as RGB | ALPHA.
      • │ │ │ │
    │ │ │ │

    Since: 5.1.2

    │ │ │ │

    See also: al_set_render_state

    │ │ │ │

    al_get_render_state

    │ │ │ │ -
    int al_get_render_state(ALLEGRO_RENDER_STATE state)
    │ │ │ │ +
    int al_get_render_state(ALLEGRO_RENDER_STATE state)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns one of several render attributes; see ALLEGRO_RENDER_STATE for │ │ │ │ details.

    │ │ │ │

    This function will return -1 when there is no current display.

    │ │ │ │ @@ -3174,16 +3411,16 @@ │ │ │ │

    See also: al_set_render_state, ALLEGRO_RENDER_STATE, ALLEGRO_RENDER_FUNCTION, │ │ │ │ ALLEGRO_WRITE_MASK_FLAGS

    │ │ │ │

    al_set_render_state

    │ │ │ │ -
    void al_set_render_state(ALLEGRO_RENDER_STATE state, int value)
    │ │ │ │ +
    void al_set_render_state(ALLEGRO_RENDER_STATE state, int value)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Set one of several render attributes; see ALLEGRO_RENDER_STATE for │ │ │ │ details.

    │ │ │ │

    This function does nothing if the target bitmap is a memory │ │ │ │ @@ -3194,23 +3431,23 @@ │ │ │ │ href="graphics.html#allegro_render_state">ALLEGRO_RENDER_STATE, ALLEGRO_RENDER_FUNCTION, │ │ │ │ ALLEGRO_WRITE_MASK_FLAGS

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_backup_dirty_bitmap

    │ │ │ │ -
    void al_backup_dirty_bitmap(ALLEGRO_BITMAP *bitmap)
    │ │ │ │ +
    void al_backup_dirty_bitmap(ALLEGRO_BITMAP *bitmap)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    On some platforms, notably Windows Direct3D and Android, textures may │ │ │ │ be lost at any time for events such as display resize or switching out │ │ │ │ of the app. On those platforms, bitmaps created without the │ │ │ │ ALLEGRO_NO_PRESERVE_TEXTURE flag automatically get backed up to system │ │ │ │ @@ -3224,16 +3461,16 @@ │ │ │ │

    Unstable │ │ │ │ API: This API is new and subject to refinement.

    │ │ │ │
    │ │ │ │

    See also: al_backup_dirty_bitmaps, │ │ │ │ al_create_bitmap

    │ │ │ │

    al_backup_dirty_bitmaps

    │ │ │ │ -
    void al_backup_dirty_bitmaps(ALLEGRO_DISPLAY *display)
    │ │ │ │ +
    void al_backup_dirty_bitmaps(ALLEGRO_DISPLAY *display)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Backs up all of a display’s bitmaps to system memory.

    │ │ │ │

    Since: 5.2.1

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -175,36 +175,52 @@ │ │ │ │ │ ************ CCoolloorrss ************ │ │ │ │ │ ********** AALLLLEEGGRROO__CCOOLLOORR ********** │ │ │ │ │ typedef struct ALLEGRO_COLOR ALLEGRO_COLOR; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ An ALLEGRO_COLOR structure describes a color in a device independent way. Use │ │ │ │ │ _a_l___m_a_p___r_g_b et al. and _a_l___u_n_m_a_p___r_g_b et al. to translate from and to various │ │ │ │ │ color representations. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___k_e_y_b_o_a_r_d___f_o_c_u_s_._c │ │ │ │ │ + * _e_x___n_o_d_i_s_p_l_a_y_._c │ │ │ │ │ + * _e_x___m_o_u_s_e___f_o_c_u_s_._c │ │ │ │ │ ********** aall__mmaapp__rrggbb ********** │ │ │ │ │ ALLEGRO_COLOR al_map_rgb( │ │ │ │ │ unsigned char r, unsigned char g, unsigned char b) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Convert r, g, b (ranging from 0-255) into an _A_L_L_E_G_R_O___C_O_L_O_R, using 255 for │ │ │ │ │ alpha. │ │ │ │ │ This function can be called before Allegro is initialized. │ │ │ │ │ See also: _a_l___m_a_p___r_g_b_a, _a_l___m_a_p___r_g_b_a___f, _a_l___m_a_p___r_g_b___f │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___e_n_e_t___s_e_r_v_e_r_._c │ │ │ │ │ + * _e_x___k_e_y_b_o_a_r_d___f_o_c_u_s_._c │ │ │ │ │ + * _e_x___n_o_d_i_s_p_l_a_y_._c │ │ │ │ │ ********** aall__mmaapp__rrggbb__ff ********** │ │ │ │ │ ALLEGRO_COLOR al_map_rgb_f(float r, float g, float b) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Convert r, g, b, (ranging from 0.0f-1.0f) into an _A_L_L_E_G_R_O___C_O_L_O_R, using 1.0f for │ │ │ │ │ alpha. │ │ │ │ │ This function can be called before Allegro is initialized. │ │ │ │ │ See also: _a_l___m_a_p___r_g_b_a, _a_l___m_a_p___r_g_b, _a_l___m_a_p___r_g_b_a___f │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___e_n_e_t___s_e_r_v_e_r_._c │ │ │ │ │ + * _e_x___k_e_y_b_o_a_r_d___e_v_e_n_t_s_._c │ │ │ │ │ + * _e_x___d_r_a_w_p_i_x_e_l_s_._c │ │ │ │ │ ********** aall__mmaapp__rrggbbaa ********** │ │ │ │ │ ALLEGRO_COLOR al_map_rgba( │ │ │ │ │ unsigned char r, unsigned char g, unsigned char b, unsigned char a) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Convert r, g, b, a (ranging from 0-255) into an _A_L_L_E_G_R_O___C_O_L_O_R. │ │ │ │ │ This function can be called before Allegro is initialized. │ │ │ │ │ See also: _a_l___m_a_p___r_g_b, _a_l___p_r_e_m_u_l___r_g_b_a, _a_l___m_a_p___r_g_b___f │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___n_o_d_i_s_p_l_a_y_._c │ │ │ │ │ + * _e_x___d_r_a_w_p_i_x_e_l_s_._c │ │ │ │ │ + * _e_x___t_i_m_e_d_w_a_i_t_._c │ │ │ │ │ ********** aall__pprreemmuull__rrggbbaa ********** │ │ │ │ │ ALLEGRO_COLOR al_premul_rgba( │ │ │ │ │ unsigned char r, unsigned char g, unsigned char b, unsigned char a) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This is a shortcut for _a_l___m_a_p___r_g_b_a(r * a / 255, g * a / 255, b * a / 255, a). │ │ │ │ │ By default Allegro uses pre-multiplied alpha for transparent blending of │ │ │ │ │ bitmaps and primitives (see _a_l___l_o_a_d___b_i_t_m_a_p___f_l_a_g_s for a discussion of that │ │ │ │ │ @@ -223,14 +239,18 @@ │ │ │ │ │ See also: _a_l___m_a_p___r_g_b_a, _a_l___p_r_e_m_u_l___r_g_b_a___f │ │ │ │ │ ********** aall__mmaapp__rrggbbaa__ff ********** │ │ │ │ │ ALLEGRO_COLOR al_map_rgba_f(float r, float g, float b, float a) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Convert r, g, b, a (ranging from 0.0f-1.0f) into an _A_L_L_E_G_R_O___C_O_L_O_R. │ │ │ │ │ This function can be called before Allegro is initialized. │ │ │ │ │ See also: _a_l___m_a_p___r_g_b_a, _a_l___p_r_e_m_u_l___r_g_b_a___f, _a_l___m_a_p___r_g_b___f │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___t_i_m_e_d_w_a_i_t_._c │ │ │ │ │ + * _e_x___r_e_s_i_z_e_._c │ │ │ │ │ + * _e_x___r_o_t_a_t_e_._c │ │ │ │ │ ********** aall__pprreemmuull__rrggbbaa__ff ********** │ │ │ │ │ ALLEGRO_COLOR al_premul_rgba_f(float r, float g, float b, float a) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This is a shortcut for _a_l___m_a_p___r_g_b_a___f(r * a, g * a, b * a, a). │ │ │ │ │ By default Allegro uses pre-multiplied alpha for transparent blending of │ │ │ │ │ bitmaps and primitives (see _a_l___l_o_a_d___b_i_t_m_a_p___f_l_a_g_s for a discussion of that │ │ │ │ │ feature). This means that if you want to tint a bitmap or primitive to be │ │ │ │ │ @@ -250,35 +270,48 @@ │ │ │ │ │ void al_unmap_rgb(ALLEGRO_COLOR color, │ │ │ │ │ unsigned char *r, unsigned char *g, unsigned char *b) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Retrieves components of an ALLEGRO_COLOR, ignoring alpha. Components will range │ │ │ │ │ from 0-255. │ │ │ │ │ This function can be called before Allegro is initialized. │ │ │ │ │ See also: _a_l___u_n_m_a_p___r_g_b_a, _a_l___u_n_m_a_p___r_g_b_a___f, _a_l___u_n_m_a_p___r_g_b___f │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___b_l_e_n_d___t_e_s_t_._c │ │ │ │ │ + * _e_x___h_a_i_k_u_._c │ │ │ │ │ + * _e_x___c_o_l_o_r___g_r_a_d_i_e_n_t_._c │ │ │ │ │ ********** aall__uunnmmaapp__rrggbb__ff ********** │ │ │ │ │ void al_unmap_rgb_f(ALLEGRO_COLOR color, float *r, float *g, float *b) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Retrieves components of an _A_L_L_E_G_R_O___C_O_L_O_R, ignoring alpha. Components will range │ │ │ │ │ from 0.0f-1.0f. │ │ │ │ │ This function can be called before Allegro is initialized. │ │ │ │ │ See also: _a_l___u_n_m_a_p___r_g_b_a, _a_l___u_n_m_a_p___r_g_b, _a_l___u_n_m_a_p___r_g_b_a___f │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___h_a_i_k_u_._c │ │ │ │ │ + * _e_x___c_o_l_o_r___g_r_a_d_i_e_n_t_._c │ │ │ │ │ ********** aall__uunnmmaapp__rrggbbaa ********** │ │ │ │ │ void al_unmap_rgba(ALLEGRO_COLOR color, │ │ │ │ │ unsigned char *r, unsigned char *g, unsigned char *b, unsigned char *a) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Retrieves components of an _A_L_L_E_G_R_O___C_O_L_O_R. Components will range from 0-255. │ │ │ │ │ This function can be called before Allegro is initialized. │ │ │ │ │ See also: _a_l___u_n_m_a_p___r_g_b, _a_l___u_n_m_a_p___r_g_b_a___f, _a_l___u_n_m_a_p___r_g_b___f │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___b_l_e_n_d___t_e_s_t_._c │ │ │ │ │ + * _e_x___l_o_g_o_._c │ │ │ │ │ ********** aall__uunnmmaapp__rrggbbaa__ff ********** │ │ │ │ │ void al_unmap_rgba_f(ALLEGRO_COLOR color, │ │ │ │ │ float *r, float *g, float *b, float *a) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Retrieves components of an _A_L_L_E_G_R_O___C_O_L_O_R. Components will range from 0.0f-1.0f. │ │ │ │ │ This function can be called before Allegro is initialized. │ │ │ │ │ See also: _a_l___u_n_m_a_p___r_g_b_a, _a_l___u_n_m_a_p___r_g_b, _a_l___u_n_m_a_p___r_g_b___f │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___b_l_e_n_d___t_e_s_t_._c │ │ │ │ │ + * _e_x___l_o_g_o_._c │ │ │ │ │ ************ LLoocckkiinngg aanndd ppiixxeell ffoorrmmaattss ************ │ │ │ │ │ ********** AALLLLEEGGRROO__LLOOCCKKEEDD__RREEGGIIOONN ********** │ │ │ │ │ typedef struct ALLEGRO_LOCKED_REGION ALLEGRO_LOCKED_REGION; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Users who wish to manually edit or read from a bitmap are required to lock it │ │ │ │ │ first. The ALLEGRO_LOCKED_REGION structure represents the locked region of the │ │ │ │ │ bitmap. This call will work with any bitmap, including memory bitmaps. │ │ │ │ │ @@ -300,14 +333,18 @@ │ │ │ │ │ * ppiixxeell__ssiizzee is the number of bytes used to represent a single block of │ │ │ │ │ pixels for the pixel format of this locked region. For most formats (and │ │ │ │ │ historically, this used to be true for all formats), this is just the │ │ │ │ │ size of a single pixel, but for blocked pixel formats this value is │ │ │ │ │ different. │ │ │ │ │ See also: _a_l___l_o_c_k___b_i_t_m_a_p, _a_l___l_o_c_k___b_i_t_m_a_p___r_e_g_i_o_n, _a_l___u_n_l_o_c_k___b_i_t_m_a_p, │ │ │ │ │ _A_L_L_E_G_R_O___P_I_X_E_L___F_O_R_M_A_T │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___l_o_c_k_b_i_t_m_a_p_._c │ │ │ │ │ + * _e_x___p_r_e_m_u_l_a_l_p_h_a_._c │ │ │ │ │ + * _e_x___m_u_l_t_i_s_a_m_p_l_e_._c │ │ │ │ │ ********** AALLLLEEGGRROO__PPIIXXEELL__FFOORRMMAATT ********** │ │ │ │ │ typedef enum ALLEGRO_PIXEL_FORMAT │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Pixel formats. Each pixel format specifies the exact size and bit layout of a │ │ │ │ │ pixel in memory. Components are specified from high bits to low bits, so for │ │ │ │ │ example a fully opaque red pixel in ARGB_8888 format is 0xFFFF0000. │ │ │ │ │ NNoottee:: │ │ │ │ │ @@ -403,14 +440,18 @@ │ │ │ │ │ resulting in 4x compression ratio. This format supports sharp alpha │ │ │ │ │ transitions. Since 5.1.9. │ │ │ │ │ * ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT5 - Compressed using the DXT5 │ │ │ │ │ compression algorithm. Each 4x4 pixel block is encoded in 128 bytes, │ │ │ │ │ resulting in 4x compression ratio. This format supports smooth alpha │ │ │ │ │ transitions. Since 5.1.9. │ │ │ │ │ See also: _a_l___s_e_t___n_e_w___b_i_t_m_a_p___f_o_r_m_a_t, _a_l___g_e_t___b_i_t_m_a_p___f_o_r_m_a_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___c_o_n_v_e_r_t_._c │ │ │ │ │ + * _e_x___d_r_a_w_p_i_x_e_l_s_._c │ │ │ │ │ + * _e_x___l_o_c_k_b_i_t_m_a_p_._c │ │ │ │ │ ********** aall__ggeett__ppiixxeell__ssiizzee ********** │ │ │ │ │ int al_get_pixel_size(int format) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the number of bytes that a pixel of the given format occupies. For │ │ │ │ │ blocked pixel formats (e.g. compressed formats), this returns 0. │ │ │ │ │ See also: _A_L_L_E_G_R_O___P_I_X_E_L___F_O_R_M_A_T, _a_l___g_e_t___p_i_x_e_l___f_o_r_m_a_t___b_i_t_s │ │ │ │ │ ********** aall__ggeett__ppiixxeell__ffoorrmmaatt__bbiittss ********** │ │ │ │ │ @@ -429,21 +470,25 @@ │ │ │ │ │ ********** aall__ggeett__ppiixxeell__bblloocckk__wwiiddtthh ********** │ │ │ │ │ int al_get_pixel_block_width(int format) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the width of the the pixel block for this format. │ │ │ │ │ Since: 5.1.9. │ │ │ │ │ See also: _A_L_L_E_G_R_O___P_I_X_E_L___F_O_R_M_A_T, _a_l___g_e_t___p_i_x_e_l___b_l_o_c_k___s_i_z_e, │ │ │ │ │ _a_l___g_e_t___p_i_x_e_l___b_l_o_c_k___h_e_i_g_h_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___c_o_m_p_r_e_s_s_e_d_._c │ │ │ │ │ ********** aall__ggeett__ppiixxeell__bblloocckk__hheeiigghhtt ********** │ │ │ │ │ int al_get_pixel_block_height(int format) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the height of the the pixel block for this format. │ │ │ │ │ Since: 5.1.9. │ │ │ │ │ See also: _A_L_L_E_G_R_O___P_I_X_E_L___F_O_R_M_A_T, _a_l___g_e_t___p_i_x_e_l___b_l_o_c_k___s_i_z_e, │ │ │ │ │ _a_l___g_e_t___p_i_x_e_l___b_l_o_c_k___w_i_d_t_h │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___c_o_m_p_r_e_s_s_e_d_._c │ │ │ │ │ ********** aall__lloocckk__bbiittmmaapp ********** │ │ │ │ │ ALLEGRO_LOCKED_REGION *al_lock_bitmap(ALLEGRO_BITMAP *bitmap, │ │ │ │ │ int format, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Lock an entire bitmap for reading or writing. If the bitmap is a display bitmap │ │ │ │ │ it will be updated from system memory after the bitmap is unlocked (unless │ │ │ │ │ locked read only). Returns NULL if the bitmap cannot be locked, e.g. the bitmap │ │ │ │ │ @@ -475,15 +520,15 @@ │ │ │ │ │ operations on it (with the sole exception of _a_l___p_u_t___p_i_x_e_l and │ │ │ │ │ _a_l___p_u_t___b_l_e_n_d_e_d___p_i_x_e_l). │ │ │ │ │ See also: _A_L_L_E_G_R_O___L_O_C_K_E_D___R_E_G_I_O_N, _A_L_L_E_G_R_O___P_I_X_E_L___F_O_R_M_A_T, _a_l___u_n_l_o_c_k___b_i_t_m_a_p, │ │ │ │ │ _a_l___l_o_c_k___b_i_t_m_a_p___r_e_g_i_o_n, _a_l___l_o_c_k___b_i_t_m_a_p___b_l_o_c_k_e_d, _a_l___l_o_c_k___b_i_t_m_a_p___r_e_g_i_o_n___b_l_o_c_k_e_d │ │ │ │ │ Examples: │ │ │ │ │ * _e_x___d_r_a_w_p_i_x_e_l_s_._c │ │ │ │ │ * _e_x___m_e_m_b_m_p_._c │ │ │ │ │ - * _e_x___b_l_e_n_d_._c │ │ │ │ │ + * _e_x___l_o_c_k_b_i_t_m_a_p_._c │ │ │ │ │ ********** aall__lloocckk__bbiittmmaapp__rreeggiioonn ********** │ │ │ │ │ ALLEGRO_LOCKED_REGION *al_lock_bitmap_region(ALLEGRO_BITMAP *bitmap, │ │ │ │ │ int x, int y, int width, int height, int format, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___l_o_c_k___b_i_t_m_a_p, but only locks a specific area of the bitmap. If the │ │ │ │ │ bitmap is a video bitmap, only that area of the texture will be updated when it │ │ │ │ │ is unlocked. Locking only the region you indend to modify will be faster than │ │ │ │ │ @@ -494,28 +539,28 @@ │ │ │ │ │ region be aligned to the block width for optimal performance. If it │ │ │ │ │ is not, then the function will have to lock the region with the │ │ │ │ │ ALLEGRO_LOCK_READWRITE instead in order to pad this region with valid │ │ │ │ │ data. │ │ │ │ │ See also: _A_L_L_E_G_R_O___L_O_C_K_E_D___R_E_G_I_O_N, _A_L_L_E_G_R_O___P_I_X_E_L___F_O_R_M_A_T, _a_l___u_n_l_o_c_k___b_i_t_m_a_p │ │ │ │ │ Examples: │ │ │ │ │ * _e_x___l_o_c_k_b_i_t_m_a_p_._c │ │ │ │ │ + * _e_x___c_o_m_p_r_e_s_s_e_d_._c │ │ │ │ │ * _e_x___t_h_r_e_a_d_s_2_._c │ │ │ │ │ - * _e_x___b_l_i_t_._c │ │ │ │ │ ********** aall__uunnlloocckk__bbiittmmaapp ********** │ │ │ │ │ void al_unlock_bitmap(ALLEGRO_BITMAP *bitmap) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Unlock a previously locked bitmap or bitmap region. If the bitmap is a video │ │ │ │ │ bitmap, the texture will be updated to match the system memory copy (unless it │ │ │ │ │ was locked read only). │ │ │ │ │ See also: _a_l___l_o_c_k___b_i_t_m_a_p, _a_l___l_o_c_k___b_i_t_m_a_p___r_e_g_i_o_n, _a_l___l_o_c_k___b_i_t_m_a_p___b_l_o_c_k_e_d, │ │ │ │ │ _a_l___l_o_c_k___b_i_t_m_a_p___r_e_g_i_o_n___b_l_o_c_k_e_d │ │ │ │ │ Examples: │ │ │ │ │ * _e_x___d_r_a_w_p_i_x_e_l_s_._c │ │ │ │ │ - * _e_x___b_l_e_n_d_._c │ │ │ │ │ * _e_x___l_o_c_k_b_i_t_m_a_p_._c │ │ │ │ │ + * _e_x___p_r_e_m_u_l_a_l_p_h_a_._c │ │ │ │ │ ********** aall__lloocckk__bbiittmmaapp__bblloocckkeedd ********** │ │ │ │ │ ALLEGRO_LOCKED_REGION *al_lock_bitmap_blocked(ALLEGRO_BITMAP *bitmap, │ │ │ │ │ int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___l_o_c_k___b_i_t_m_a_p, but allows locking bitmaps with a blocked pixel format │ │ │ │ │ (i.e. a format for which _a_l___g_e_t___p_i_x_e_l___b_l_o_c_k___w_i_d_t_h or _a_l___g_e_t___p_i_x_e_l___b_l_o_c_k___h_e_i_g_h_t │ │ │ │ │ do not return 1) in that format. To that end, this function also does not allow │ │ │ │ │ @@ -538,14 +583,18 @@ │ │ │ │ │ Examples: │ │ │ │ │ * _e_x___c_o_m_p_r_e_s_s_e_d_._c │ │ │ │ │ ************ BBiittmmaapp ccrreeaattiioonn ************ │ │ │ │ │ ********** AALLLLEEGGRROO__BBIITTMMAAPP ********** │ │ │ │ │ typedef struct ALLEGRO_BITMAP ALLEGRO_BITMAP; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Abstract type representing a bitmap (2D image). │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___c_o_n_v_e_r_t_._c │ │ │ │ │ + * _e_x___n_o_d_i_s_p_l_a_y_._c │ │ │ │ │ + * _e_x___o_p_e_n_g_l___p_i_x_e_l___s_h_a_d_e_r_._c │ │ │ │ │ ********** aall__ccrreeaattee__bbiittmmaapp ********** │ │ │ │ │ ALLEGRO_BITMAP *al_create_bitmap(int w, int h) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Creates a new bitmap using the bitmap format and flags for the current thread. │ │ │ │ │ Blitting between bitmaps of differing formats, or blitting between memory │ │ │ │ │ bitmaps and display bitmaps may be slow. │ │ │ │ │ Unless you set the ALLEGRO_MEMORY_BITMAP flag, the bitmap is created for the │ │ │ │ │ @@ -586,17 +635,17 @@ │ │ │ │ │ NNoottee: The contents of a newly created bitmap are undefined - you need to clear │ │ │ │ │ the bitmap or make sure all pixels get overwritten before drawing it. │ │ │ │ │ When you are done with using the bitmap you must call _a_l___d_e_s_t_r_o_y___b_i_t_m_a_p on it │ │ │ │ │ to free any resources allocated for it. │ │ │ │ │ See also: _a_l___s_e_t___n_e_w___b_i_t_m_a_p___f_o_r_m_a_t, _a_l___s_e_t___n_e_w___b_i_t_m_a_p___f_l_a_g_s, _a_l___c_l_o_n_e___b_i_t_m_a_p, │ │ │ │ │ _a_l___c_r_e_a_t_e___s_u_b___b_i_t_m_a_p, _a_l___c_o_n_v_e_r_t___m_e_m_o_r_y___b_i_t_m_a_p_s, _a_l___d_e_s_t_r_o_y___b_i_t_m_a_p │ │ │ │ │ Examples: │ │ │ │ │ - * _e_x___o_p_e_n_g_l___p_i_x_e_l___s_h_a_d_e_r_._c │ │ │ │ │ * _e_x___n_o_d_i_s_p_l_a_y_._c │ │ │ │ │ - * _e_x___l_i_n_e_s_._c │ │ │ │ │ + * _e_x___o_p_e_n_g_l___p_i_x_e_l___s_h_a_d_e_r_._c │ │ │ │ │ + * _e_x___i_c_o_n_2_._c │ │ │ │ │ ********** aall__ccrreeaattee__ssuubb__bbiittmmaapp ********** │ │ │ │ │ ALLEGRO_BITMAP *al_create_sub_bitmap(ALLEGRO_BITMAP *parent, │ │ │ │ │ int x, int y, int w, int h) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Creates a sub-bitmap of the parent, at the specified coordinates and of the │ │ │ │ │ specified size. A sub-bitmap is a bitmap that shares drawing memory with a pre- │ │ │ │ │ existing (parent) bitmap, but possibly with a different size and clipping │ │ │ │ │ @@ -610,31 +659,31 @@ │ │ │ │ │ it to free any resources allocated for it. │ │ │ │ │ Note that destroying parents of sub-bitmaps will not destroy the sub-bitmaps; │ │ │ │ │ instead the sub-bitmaps become invalid and should no longer be used for drawing │ │ │ │ │ - they still must be destroyed with _a_l___d_e_s_t_r_o_y___b_i_t_m_a_p however. It does not │ │ │ │ │ matter whether you destroy a sub-bitmap before or after its parent otherwise. │ │ │ │ │ See also: _a_l___c_r_e_a_t_e___b_i_t_m_a_p │ │ │ │ │ Examples: │ │ │ │ │ - * _e_x___s_h_a_d_e_r___t_a_r_g_e_t_._c │ │ │ │ │ * _e_x___b_l_e_n_d___t_a_r_g_e_t_._c │ │ │ │ │ - * _e_x___m_u_l_t_i_s_a_m_p_l_e___t_a_r_g_e_t_._c │ │ │ │ │ + * _e_x___s_u_b_b_i_t_m_a_p_._c │ │ │ │ │ + * _e_x___s_h_a_d_e_r___t_a_r_g_e_t_._c │ │ │ │ │ ********** aall__cclloonnee__bbiittmmaapp ********** │ │ │ │ │ ALLEGRO_BITMAP *al_clone_bitmap(ALLEGRO_BITMAP *bitmap) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Create a new bitmap with _a_l___c_r_e_a_t_e___b_i_t_m_a_p, and copy the pixel data from the old │ │ │ │ │ bitmap across. The newly created bitmap will be created with the current new │ │ │ │ │ bitmap flags, and not the ones that were used to create the original bitmap. If │ │ │ │ │ the new bitmap is a memory bitmap, its projection bitmap is reset to be │ │ │ │ │ orthographic. │ │ │ │ │ See also: _a_l___c_r_e_a_t_e___b_i_t_m_a_p, _a_l___s_e_t___n_e_w___b_i_t_m_a_p___f_o_r_m_a_t, _a_l___s_e_t___n_e_w___b_i_t_m_a_p___f_l_a_g_s, │ │ │ │ │ _a_l___c_o_n_v_e_r_t___b_i_t_m_a_p │ │ │ │ │ Examples: │ │ │ │ │ - * _e_x___p_r_e_m_u_l_a_l_p_h_a_._c │ │ │ │ │ - * _e_x___b_l_e_n_d_2_._c_p_p │ │ │ │ │ + * _e_x___s_u_b_b_i_t_m_a_p_._c │ │ │ │ │ * _e_x___f_o_n_t_._c │ │ │ │ │ + * _e_x___p_r_e_m_u_l_a_l_p_h_a_._c │ │ │ │ │ ********** aall__ccoonnvveerrtt__bbiittmmaapp ********** │ │ │ │ │ void al_convert_bitmap(ALLEGRO_BITMAP *bitmap) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Converts the bitmap to the current bitmap flags and format. The bitmap will be │ │ │ │ │ as if it was created anew with _a_l___c_r_e_a_t_e___b_i_t_m_a_p but retain its contents. All of │ │ │ │ │ this bitmap’s sub-bitmaps are also converted. If the new bitmap type is memory, │ │ │ │ │ then the bitmap’s projection bitmap is reset to be orthographic. │ │ │ │ │ @@ -675,14 +724,16 @@ │ │ │ │ │ * _e_x___n_o_d_i_s_p_l_a_y_._c │ │ │ │ │ * _e_x___b_l_e_n_d___b_e_n_c_h_._c │ │ │ │ │ ********** aall__ggeett__nneeww__bbiittmmaapp__ffllaaggss ********** │ │ │ │ │ int al_get_new_bitmap_flags(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the flags used for newly created bitmaps. │ │ │ │ │ See also: _a_l___s_e_t___n_e_w___b_i_t_m_a_p___f_l_a_g_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_r_i_m_._c │ │ │ │ │ ********** aall__ggeett__nneeww__bbiittmmaapp__ffoorrmmaatt ********** │ │ │ │ │ int al_get_new_bitmap_format(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the format used for newly created bitmaps. │ │ │ │ │ See also: _A_L_L_E_G_R_O___P_I_X_E_L___F_O_R_M_A_T, _a_l___s_e_t___n_e_w___b_i_t_m_a_p___f_o_r_m_a_t │ │ │ │ │ ********** aall__sseett__nneeww__bbiittmmaapp__ffllaaggss ********** │ │ │ │ │ void al_set_new_bitmap_flags(int flags) │ │ │ │ │ @@ -746,36 +797,48 @@ │ │ │ │ │ ALLEGRO_MIPMAP │ │ │ │ │ This can only be used for bitmaps whose width and height is a power of │ │ │ │ │ two. In that case, it will generate mipmaps and use them when drawing │ │ │ │ │ scaled down versions. For example if the bitmap is 64x64, then extra │ │ │ │ │ bitmaps of sizes 32x32, 16x16, 8x8, 4x4, 2x2 and 1x1 will be created │ │ │ │ │ always containing a scaled down version of the original. │ │ │ │ │ See also: _a_l___g_e_t___n_e_w___b_i_t_m_a_p___f_l_a_g_s, _a_l___g_e_t___b_i_t_m_a_p___f_l_a_g_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___c_o_n_v_e_r_t_._c │ │ │ │ │ + * _e_x___b_l_e_n_d___b_e_n_c_h_._c │ │ │ │ │ + * _e_x___i_c_o_n_2_._c │ │ │ │ │ ********** aall__aadddd__nneeww__bbiittmmaapp__ffllaagg ********** │ │ │ │ │ void al_add_new_bitmap_flag(int flag) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ A convenience function which does the same as │ │ │ │ │ al_set_new_bitmap_flags(al_get_new_bitmap_flags() | flag); │ │ │ │ │ See also: _a_l___s_e_t___n_e_w___b_i_t_m_a_p___f_l_a_g_s, _a_l___g_e_t___n_e_w___b_i_t_m_a_p___f_l_a_g_s, _a_l___g_e_t___b_i_t_m_a_p___f_l_a_g_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___b_l_e_n_d_2_._c_p_p │ │ │ │ │ ********** aall__sseett__nneeww__bbiittmmaapp__ffoorrmmaatt ********** │ │ │ │ │ void al_set_new_bitmap_format(int format) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Sets the pixel format (_A_L_L_E_G_R_O___P_I_X_E_L___F_O_R_M_A_T) for newly created bitmaps. The │ │ │ │ │ default format is 0 and means the display driver will choose the best format. │ │ │ │ │ See also: _A_L_L_E_G_R_O___P_I_X_E_L___F_O_R_M_A_T, _a_l___g_e_t___n_e_w___b_i_t_m_a_p___f_o_r_m_a_t, _a_l___g_e_t___b_i_t_m_a_p___f_o_r_m_a_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___c_o_n_v_e_r_t_._c │ │ │ │ │ + * _e_x___p_i_x_e_l_f_o_r_m_a_t_._c_p_p │ │ │ │ │ + * _e_x___b_l_e_n_d___t_e_s_t_._c │ │ │ │ │ ********** aall__sseett__nneeww__bbiittmmaapp__ddeepptthh ********** │ │ │ │ │ void al_set_new_bitmap_depth(int depth) │ │ │ │ │ SETTER(new_bitmap_depth, depth) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Sets the depthbuffer depth used by newly created bitmaps (on the current │ │ │ │ │ thread) if they are used with _a_l___s_e_t___t_a_r_g_e_t___b_i_t_m_a_p. 0 means no depth-buffer │ │ │ │ │ will be created when drawing into the bitmap, which is the default. │ │ │ │ │ Since: 5.2.1 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: This is an experimental feature and currently only │ │ │ │ │ works for the OpenGL backend. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_e_p_t_h___t_a_r_g_e_t_._c │ │ │ │ │ ********** aall__ggeett__nneeww__bbiittmmaapp__ddeepptthh ********** │ │ │ │ │ int al_get_new_bitmap_depth(void) │ │ │ │ │ GETTER(new_bitmap_depth, 0) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the value currently set with _a_l___s_e_t___n_e_w___b_i_t_m_a_p___d_e_p_t_h on the current │ │ │ │ │ thread or 0 if none was set. │ │ │ │ │ Since: 5.2.1 │ │ │ │ │ @@ -803,14 +866,17 @@ │ │ │ │ │ al_set_target_bitmap(backbuffer); │ │ │ │ │ al_lock_bitmap(multisample, ...) │ │ │ │ │ // CORRECT: at this point, the bitmap contents are updated and │ │ │ │ │ // there will be an anti-aliased line in it. │ │ │ │ │ Since: 5.2.1 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: This is an experimental feature and currently only │ │ │ │ │ works for the OpenGL backend. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_u_l_t_i_s_a_m_p_l_e___t_a_r_g_e_t_._c │ │ │ │ │ + * _e_x___d_e_p_t_h___t_a_r_g_e_t_._c │ │ │ │ │ ********** aall__ggeett__nneeww__bbiittmmaapp__ssaammpplleess ********** │ │ │ │ │ int al_get_new_bitmap_samples(void) │ │ │ │ │ GETTER(new_bitmap_samples, 0) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the value currently set with _a_l___s_e_t___n_e_w___b_i_t_m_a_p___s_a_m_p_l_e_s on the current │ │ │ │ │ thread or 0 if none was set. │ │ │ │ │ Since: 5.2.1 │ │ │ │ │ @@ -828,14 +894,17 @@ │ │ │ │ │ per-texture. This interacts particularly poorly with the primitives │ │ │ │ │ addon which (for backwards compatibility) alters the wrapping │ │ │ │ │ setting. To minimize this issue, use a wrapping setting that’s not │ │ │ │ │ ALLEGRO_BITMAP_WRAP_DEFAULT. │ │ │ │ │ Since: 5.2.8 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: This is an experimental feature. │ │ │ │ │ See also: _A_L_L_E_G_R_O___B_I_T_M_A_P___W_R_A_P │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_r_i_m___w_r_a_p_._c │ │ │ │ │ + * _e_x___p_r_i_m_._c │ │ │ │ │ ********** aall__ggeett__nneeww__bbiittmmaapp__wwrraapp ********** │ │ │ │ │ Source Code │ │ │ │ │ Returns the value currently set with _a_l___s_e_t___n_e_w___b_i_t_m_a_p___w_r_a_p on the current │ │ │ │ │ thread. │ │ │ │ │ Since: 5.2.8 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: This is an experimental feature. │ │ │ │ │ See also: _A_L_L_E_G_R_O___B_I_T_M_A_P___W_R_A_P │ │ │ │ │ @@ -849,14 +918,17 @@ │ │ │ │ │ ALLEGRO_BITMAP_WRAP_CLAMP otherwise. │ │ │ │ │ * ALLEGRO_BITMAP_WRAP_REPEAT - The texture coordinates get shifted to the │ │ │ │ │ opposite edge that they go past. │ │ │ │ │ * ALLEGRO_BITMAP_WRAP_CLAMP - The texture coordinates get clamped to the │ │ │ │ │ edges that they go past. │ │ │ │ │ * ALLEGRO_BITMAP_WRAP_MIRROR - The texture coordinates get mirrored across │ │ │ │ │ the edges that they go past. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_r_i_m___w_r_a_p_._c │ │ │ │ │ + * _e_x___p_r_i_m_._c │ │ │ │ │ ************ BBiittmmaapp pprrooppeerrttiieess ************ │ │ │ │ │ ********** aall__ggeett__bbiittmmaapp__ffllaaggss ********** │ │ │ │ │ int al_get_bitmap_flags(ALLEGRO_BITMAP *bitmap) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the flags used to create the bitmap. │ │ │ │ │ See also: _a_l___s_e_t___n_e_w___b_i_t_m_a_p___f_l_a_g_s │ │ │ │ │ Examples: │ │ │ │ │ @@ -871,25 +943,25 @@ │ │ │ │ │ * _e_x___c_o_m_p_r_e_s_s_e_d_._c │ │ │ │ │ * _e_x___d_r_a_w_._c │ │ │ │ │ ********** aall__ggeett__bbiittmmaapp__hheeiigghhtt ********** │ │ │ │ │ int al_get_bitmap_height(ALLEGRO_BITMAP *bitmap) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the height of a bitmap in pixels. │ │ │ │ │ Examples: │ │ │ │ │ - * _e_x___c_o_l_o_r_._c_p_p │ │ │ │ │ - * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ + * _e_x___m_u_l_t_i_w_i_n_._c │ │ │ │ │ * _e_x___r_e_s_i_z_e_._c │ │ │ │ │ + * _e_x___m_e_m_b_m_p_._c │ │ │ │ │ ********** aall__ggeett__bbiittmmaapp__wwiiddtthh ********** │ │ │ │ │ int al_get_bitmap_width(ALLEGRO_BITMAP *bitmap) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the width of a bitmap in pixels. │ │ │ │ │ Examples: │ │ │ │ │ - * _e_x___c_o_l_o_r_._c_p_p │ │ │ │ │ * _e_x___f_o_n_t___j_u_s_t_i_f_y_._c_p_p │ │ │ │ │ - * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ + * _e_x___m_u_l_t_i_w_i_n_._c │ │ │ │ │ + * _e_x___r_e_s_i_z_e_._c │ │ │ │ │ ********** aall__ggeett__bbiittmmaapp__ddeepptthh ********** │ │ │ │ │ int al_get_bitmap_depth(ALLEGRO_BITMAP *bitmap) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the depthbuffer depth used by this bitmap if it is used with │ │ │ │ │ _a_l___s_e_t___t_a_r_g_e_t___b_i_t_m_a_p. │ │ │ │ │ Since: 5.2.1 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: This is an experimental feature and currently only │ │ │ │ │ @@ -907,16 +979,16 @@ │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get a pixel’s color value from the specified bitmap. This operation is slow on │ │ │ │ │ non-memory bitmaps. Consider locking the bitmap if you are going to use this │ │ │ │ │ function multiple times on the same bitmap. │ │ │ │ │ See also: _A_L_L_E_G_R_O___C_O_L_O_R, _a_l___p_u_t___p_i_x_e_l, _a_l___l_o_c_k___b_i_t_m_a_p │ │ │ │ │ Examples: │ │ │ │ │ * _e_x___b_l_e_n_d___t_e_s_t_._c │ │ │ │ │ - * _e_x___v_e_r_t_e_x___b_u_f_f_e_r_._c │ │ │ │ │ * _e_x___c_o_m_p_r_e_s_s_e_d_._c │ │ │ │ │ + * _e_x___v_e_r_t_e_x___b_u_f_f_e_r_._c │ │ │ │ │ ********** aall__iiss__bbiittmmaapp__lloocckkeedd ********** │ │ │ │ │ bool al_is_bitmap_locked(ALLEGRO_BITMAP *bitmap) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns whether or not a bitmap is already locked. │ │ │ │ │ See also: _a_l___l_o_c_k___b_i_t_m_a_p, _a_l___l_o_c_k___b_i_t_m_a_p___r_e_g_i_o_n, _a_l___u_n_l_o_c_k___b_i_t_m_a_p │ │ │ │ │ ********** aall__iiss__ccoommppaattiibbllee__bbiittmmaapp ********** │ │ │ │ │ bool al_is_compatible_bitmap(ALLEGRO_BITMAP *bitmap) │ │ │ │ │ @@ -977,16 +1049,16 @@ │ │ │ │ │ bitmap pointer stays the same. This has many uses, for example an animation │ │ │ │ │ player could return a single bitmap which can just be re-parented to different │ │ │ │ │ animation frames without having to re-draw the contents. Or a sprite atlas │ │ │ │ │ could re-arrange its sprites without having to invalidate all existing bitmaps. │ │ │ │ │ See also: _a_l___c_r_e_a_t_e___s_u_b___b_i_t_m_a_p, _a_l___g_e_t___p_a_r_e_n_t___b_i_t_m_a_p │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ Examples: │ │ │ │ │ - * _e_x___m_u_l_t_i_s_a_m_p_l_e___t_a_r_g_e_t_._c │ │ │ │ │ * _e_x___r_e_p_a_r_e_n_t_._c │ │ │ │ │ + * _e_x___m_u_l_t_i_s_a_m_p_l_e___t_a_r_g_e_t_._c │ │ │ │ │ ********** aall__ggeett__bbiittmmaapp__bblleennddeerr ********** │ │ │ │ │ void al_get_bitmap_blender(int *op, int *src, int *dst) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the current blender being used by the target bitmap. You can pass NULL │ │ │ │ │ for values you are not interested in. │ │ │ │ │ Since: 5.2.5 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: New API. │ │ │ │ │ @@ -1058,17 +1130,17 @@ │ │ │ │ │ created in a thread. │ │ │ │ │ ********** aall__cclleeaarr__ttoo__ccoolloorr ********** │ │ │ │ │ void al_clear_to_color(ALLEGRO_COLOR color) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Clear the complete target bitmap, but confined by the clipping rectangle. │ │ │ │ │ See also: _A_L_L_E_G_R_O___C_O_L_O_R, _a_l___s_e_t___c_l_i_p_p_i_n_g___r_e_c_t_a_n_g_l_e, _a_l___c_l_e_a_r___d_e_p_t_h___b_u_f_f_e_r │ │ │ │ │ Examples: │ │ │ │ │ - * _e_x___a_u_d_i_o___p_r_o_p_s_._c_p_p │ │ │ │ │ * _e_x___k_e_y_b_o_a_r_d___f_o_c_u_s_._c │ │ │ │ │ - * _e_x___f_o_n_t___m_u_l_t_i_l_i_n_e_._c_p_p │ │ │ │ │ + * _e_x___n_o_d_i_s_p_l_a_y_._c │ │ │ │ │ + * _e_x___m_o_u_s_e___f_o_c_u_s_._c │ │ │ │ │ ********** aall__cclleeaarr__ddeepptthh__bbuuffffeerr ********** │ │ │ │ │ void al_clear_depth_buffer(float z) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Clear the depth buffer (confined by the clipping rectangle) to the given value. │ │ │ │ │ A depth buffer is only available if it was requested with │ │ │ │ │ _a_l___s_e_t___n_e_w___d_i_s_p_l_a_y___o_p_t_i_o_n and the requirement could be met by the │ │ │ │ │ _a_l___c_r_e_a_t_e___d_i_s_p_l_a_y call creating the current display. Operations involving the │ │ │ │ │ @@ -1076,17 +1148,17 @@ │ │ │ │ │ For example, if ALLEGRO_DEPTH_FUNCTION is set to ALLEGRO_RENDER_LESS then depth │ │ │ │ │ buffer value of 1 represents infinite distance, and thus is a good value to use │ │ │ │ │ when clearing the depth buffer. │ │ │ │ │ Since: 5.1.2 │ │ │ │ │ See also: _a_l___c_l_e_a_r___t_o___c_o_l_o_r, _a_l___s_e_t___c_l_i_p_p_i_n_g___r_e_c_t_a_n_g_l_e, _a_l___s_e_t___r_e_n_d_e_r___s_t_a_t_e, │ │ │ │ │ _a_l___s_e_t___n_e_w___d_i_s_p_l_a_y___o_p_t_i_o_n │ │ │ │ │ Examples: │ │ │ │ │ - * _e_x___d_e_p_t_h___t_a_r_g_e_t_._c │ │ │ │ │ * _e_x___d_e_p_t_h___m_a_s_k_._c │ │ │ │ │ - * _e_x___c_a_m_e_r_a_._c │ │ │ │ │ + * _e_x___d_e_p_t_h___t_a_r_g_e_t_._c │ │ │ │ │ + * _e_x___p_r_o_j_e_c_t_i_o_n_2_._c │ │ │ │ │ ********** aall__ddrraaww__bbiittmmaapp ********** │ │ │ │ │ void al_draw_bitmap(ALLEGRO_BITMAP *bitmap, float dx, float dy, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Draws an unscaled, unrotated bitmap at the given position to the current target │ │ │ │ │ bitmap (see _a_l___s_e_t___t_a_r_g_e_t___b_i_t_m_a_p). │ │ │ │ │ flags can be a combination of: │ │ │ │ │ * ALLEGRO_FLIP_HORIZONTAL - flip the bitmap about the y-axis │ │ │ │ │ @@ -1100,17 +1172,17 @@ │ │ │ │ │ transformed, blended or tinted. If you need to draw the backbuffer │ │ │ │ │ draw it to a temporary bitmap first with no active transformation │ │ │ │ │ (except translation). Blending and tinting settings/parameters will │ │ │ │ │ be ignored. This does not apply when drawing into a memory bitmap. │ │ │ │ │ See also: _a_l___d_r_a_w___b_i_t_m_a_p___r_e_g_i_o_n, _a_l___d_r_a_w___s_c_a_l_e_d___b_i_t_m_a_p, _a_l___d_r_a_w___r_o_t_a_t_e_d___b_i_t_m_a_p, │ │ │ │ │ _a_l___d_r_a_w___s_c_a_l_e_d___r_o_t_a_t_e_d___b_i_t_m_a_p │ │ │ │ │ Examples: │ │ │ │ │ - * _e_x___m_o_u_s_e_._c │ │ │ │ │ + * _e_x___n_o_d_i_s_p_l_a_y_._c │ │ │ │ │ * _e_x___o_p_e_n_g_l___p_i_x_e_l___s_h_a_d_e_r_._c │ │ │ │ │ - * _e_x___s_h_a_d_e_r_._c_p_p │ │ │ │ │ + * _e_x___b_l_e_n_d___b_e_n_c_h_._c │ │ │ │ │ ********** aall__ddrraaww__ttiinntteedd__bbiittmmaapp ********** │ │ │ │ │ void al_draw_tinted_bitmap(ALLEGRO_BITMAP *bitmap, ALLEGRO_COLOR tint, │ │ │ │ │ float dx, float dy, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___d_r_a_w___b_i_t_m_a_p but multiplies all colors in the bitmap with the given │ │ │ │ │ color. For example: │ │ │ │ │ al_draw_tinted_bitmap(bitmap, al_map_rgba_f(0.5, 0.5, 0.5, 0.5), x, y, 0); │ │ │ │ │ @@ -1119,15 +1191,15 @@ │ │ │ │ │ al_draw_tinted_bitmap(bitmap, al_map_rgba_f(1, 0, 0, 1), x, y, 0); │ │ │ │ │ The above will only draw the red component of the bitmap. │ │ │ │ │ See _a_l___d_r_a_w___b_i_t_m_a_p for a note on restrictions on which bitmaps can be drawn │ │ │ │ │ where. │ │ │ │ │ See also: _a_l___d_r_a_w___b_i_t_m_a_p │ │ │ │ │ Examples: │ │ │ │ │ * _e_x___n_o_d_i_s_p_l_a_y_._c │ │ │ │ │ - * _e_x___s_h_a_d_e_r___t_a_r_g_e_t_._c │ │ │ │ │ + * _e_x___e_x_p_o_s_e_._c │ │ │ │ │ * _e_x___b_i_t_m_a_p___f_l_i_p_._c │ │ │ │ │ ********** aall__ddrraaww__bbiittmmaapp__rreeggiioonn ********** │ │ │ │ │ void al_draw_bitmap_region(ALLEGRO_BITMAP *bitmap, │ │ │ │ │ float sx, float sy, float sw, float sh, float dx, float dy, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Draws a region of the given bitmap to the target bitmap. │ │ │ │ │ * sx - source x │ │ │ │ │ @@ -1138,31 +1210,31 @@ │ │ │ │ │ * dy - destination y │ │ │ │ │ * flags - same as for _a_l___d_r_a_w___b_i_t_m_a_p │ │ │ │ │ See _a_l___d_r_a_w___b_i_t_m_a_p for a note on restrictions on which bitmaps can be drawn │ │ │ │ │ where. │ │ │ │ │ See also: _a_l___d_r_a_w___b_i_t_m_a_p, _a_l___d_r_a_w___s_c_a_l_e_d___b_i_t_m_a_p, _a_l___d_r_a_w___r_o_t_a_t_e_d___b_i_t_m_a_p, │ │ │ │ │ _a_l___d_r_a_w___s_c_a_l_e_d___r_o_t_a_t_e_d___b_i_t_m_a_p │ │ │ │ │ Examples: │ │ │ │ │ - * _e_x___b_l_e_n_d_._c │ │ │ │ │ * _e_x___f_o_n_t_._c │ │ │ │ │ + * _e_x___c_l_i_p_._c │ │ │ │ │ * _e_x___b_l_i_t_._c │ │ │ │ │ ********** aall__ddrraaww__ttiinntteedd__bbiittmmaapp__rreeggiioonn ********** │ │ │ │ │ void al_draw_tinted_bitmap_region(ALLEGRO_BITMAP *bitmap, │ │ │ │ │ ALLEGRO_COLOR tint, │ │ │ │ │ float sx, float sy, float sw, float sh, float dx, float dy, │ │ │ │ │ int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___d_r_a_w___b_i_t_m_a_p___r_e_g_i_o_n but multiplies all colors in the bitmap with the │ │ │ │ │ given color. │ │ │ │ │ See _a_l___d_r_a_w___b_i_t_m_a_p for a note on restrictions on which bitmaps can be drawn │ │ │ │ │ where. │ │ │ │ │ See also: _a_l___d_r_a_w___t_i_n_t_e_d___b_i_t_m_a_p │ │ │ │ │ Examples: │ │ │ │ │ - * _e_x___t_t_f_._c │ │ │ │ │ * _e_x___t_r_a_n_s_f_o_r_m_._c │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ********** aall__ddrraaww__ppiixxeell ********** │ │ │ │ │ void al_draw_pixel(float x, float y, ALLEGRO_COLOR color) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Draws a single pixel at x, y. This function, unlike _a_l___p_u_t___p_i_x_e_l, does blending │ │ │ │ │ and, unlike _a_l___p_u_t___b_l_e_n_d_e_d___p_i_x_e_l, respects the transformations (that is, the │ │ │ │ │ pixel’s position is transformed, but its size is unaffected - it remains a │ │ │ │ │ pixel). This function can be slow if called often; if you need to draw a lot of │ │ │ │ │ @@ -1174,16 +1246,16 @@ │ │ │ │ │ NNoottee:: This function may not draw exactly where you expect it to. See │ │ │ │ │ the _p_i_x_e_l_-_p_r_e_c_i_s_e_ _o_u_t_p_u_t_ _s_e_c_t_i_o_n on the primitives addon │ │ │ │ │ documentation for details on how to control exactly where the pixel │ │ │ │ │ is drawn. │ │ │ │ │ See also: _A_L_L_E_G_R_O___C_O_L_O_R, _a_l___p_u_t___p_i_x_e_l │ │ │ │ │ Examples: │ │ │ │ │ * _e_x___d_r_a_w_p_i_x_e_l_s_._c │ │ │ │ │ - * _e_x___r_e_s_a_m_p_l_e___t_e_s_t_._c │ │ │ │ │ * _e_x___b_l_e_n_d___t_e_s_t_._c │ │ │ │ │ + * _e_x___r_e_s_a_m_p_l_e___t_e_s_t_._c │ │ │ │ │ ********** aall__ddrraaww__rroottaatteedd__bbiittmmaapp ********** │ │ │ │ │ void al_draw_rotated_bitmap(ALLEGRO_BITMAP *bitmap, │ │ │ │ │ float cx, float cy, float dx, float dy, float angle, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Draws a rotated version of the given bitmap to the target bitmap. The bitmap is │ │ │ │ │ rotated by ‘angle’ radians clockwise. │ │ │ │ │ The point at cx/cy relative to the upper left corner of the bitmap will be │ │ │ │ │ @@ -1202,16 +1274,16 @@ │ │ │ │ │ The above code draws the bitmap centered on x/y and rotates it 90° clockwise. │ │ │ │ │ See _a_l___d_r_a_w___b_i_t_m_a_p for a note on restrictions on which bitmaps can be drawn │ │ │ │ │ where. │ │ │ │ │ See also: _a_l___d_r_a_w___b_i_t_m_a_p, _a_l___d_r_a_w___b_i_t_m_a_p___r_e_g_i_o_n, _a_l___d_r_a_w___s_c_a_l_e_d___b_i_t_m_a_p, │ │ │ │ │ _a_l___d_r_a_w___s_c_a_l_e_d___r_o_t_a_t_e_d___b_i_t_m_a_p │ │ │ │ │ Examples: │ │ │ │ │ * _e_x___b_l_e_n_d_2_._c_p_p │ │ │ │ │ + * _e_x___m_u_l_t_i_s_a_m_p_l_e_._c │ │ │ │ │ * _e_x___m_u_l_t_i_s_a_m_p_l_e___t_a_r_g_e_t_._c │ │ │ │ │ - * _e_x___p_a_l_e_t_t_e_._c │ │ │ │ │ ********** aall__ddrraaww__ttiinntteedd__rroottaatteedd__bbiittmmaapp ********** │ │ │ │ │ void al_draw_tinted_rotated_bitmap(ALLEGRO_BITMAP *bitmap, │ │ │ │ │ ALLEGRO_COLOR tint, │ │ │ │ │ float cx, float cy, float dx, float dy, float angle, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___d_r_a_w___r_o_t_a_t_e_d___b_i_t_m_a_p but multiplies all colors in the bitmap with the │ │ │ │ │ given color. │ │ │ │ │ @@ -1238,16 +1310,16 @@ │ │ │ │ │ * flags - same as for _a_l___d_r_a_w___b_i_t_m_a_p │ │ │ │ │ See _a_l___d_r_a_w___b_i_t_m_a_p for a note on restrictions on which bitmaps can be drawn │ │ │ │ │ where. │ │ │ │ │ See also: _a_l___d_r_a_w___b_i_t_m_a_p, _a_l___d_r_a_w___b_i_t_m_a_p___r_e_g_i_o_n, _a_l___d_r_a_w___s_c_a_l_e_d___b_i_t_m_a_p, │ │ │ │ │ _a_l___d_r_a_w___r_o_t_a_t_e_d___b_i_t_m_a_p │ │ │ │ │ Examples: │ │ │ │ │ * _e_x___b_l_e_n_d___b_e_n_c_h_._c │ │ │ │ │ - * _e_x___p_r_e_m_u_l_a_l_p_h_a_._c │ │ │ │ │ - * _e_x___s_h_a_d_e_r___m_u_l_t_i_t_e_x_._c │ │ │ │ │ + * _e_x___b_i_t_m_a_p_._c │ │ │ │ │ + * _e_x___b_i_t_m_a_p___f_i_l_e_._c │ │ │ │ │ ********** aall__ddrraaww__ttiinntteedd__ssccaalleedd__rroottaatteedd__bbiittmmaapp ********** │ │ │ │ │ void al_draw_tinted_scaled_rotated_bitmap(ALLEGRO_BITMAP *bitmap, │ │ │ │ │ ALLEGRO_COLOR tint, │ │ │ │ │ float cx, float cy, float dx, float dy, float xscale, float yscale, │ │ │ │ │ float angle, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___d_r_a_w___s_c_a_l_e_d___r_o_t_a_t_e_d___b_i_t_m_a_p but multiplies all colors in the bitmap with │ │ │ │ │ @@ -1298,15 +1370,15 @@ │ │ │ │ │ See _a_l___d_r_a_w___b_i_t_m_a_p for a note on restrictions on which bitmaps can be drawn │ │ │ │ │ where. │ │ │ │ │ See also: _a_l___d_r_a_w___b_i_t_m_a_p, _a_l___d_r_a_w___b_i_t_m_a_p___r_e_g_i_o_n, _a_l___d_r_a_w___r_o_t_a_t_e_d___b_i_t_m_a_p, │ │ │ │ │ _a_l___d_r_a_w___s_c_a_l_e_d___r_o_t_a_t_e_d___b_i_t_m_a_p, │ │ │ │ │ Examples: │ │ │ │ │ * _e_x___b_l_e_n_d___b_e_n_c_h_._c │ │ │ │ │ * _e_x___d_u_a_l_i_e_s_._c │ │ │ │ │ - * _e_x___m_e_m_b_m_p_._c │ │ │ │ │ + * _e_x___m_u_l_t_i_w_i_n_._c │ │ │ │ │ ********** aall__ddrraaww__ttiinntteedd__ssccaalleedd__bbiittmmaapp ********** │ │ │ │ │ void al_draw_tinted_scaled_bitmap(ALLEGRO_BITMAP *bitmap, │ │ │ │ │ ALLEGRO_COLOR tint, │ │ │ │ │ float sx, float sy, float sw, float sh, │ │ │ │ │ float dx, float dy, float dw, float dh, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___d_r_a_w___s_c_a_l_e_d___b_i_t_m_a_p but multiplies all colors in the bitmap with the │ │ │ │ │ @@ -1319,26 +1391,30 @@ │ │ │ │ │ * _e_x___b_l_e_n_d_2_._c_p_p │ │ │ │ │ * _e_x___t_r_a_n_s_f_o_r_m_._c │ │ │ │ │ ********** aall__ggeett__ttaarrggeett__bbiittmmaapp ********** │ │ │ │ │ ALLEGRO_BITMAP *al_get_target_bitmap(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the target bitmap of the calling thread. │ │ │ │ │ See also: _a_l___s_e_t___t_a_r_g_e_t___b_i_t_m_a_p │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t___j_u_s_t_i_f_y_._c_p_p │ │ │ │ │ + * _e_x___r_e_s_i_z_e_._c │ │ │ │ │ + * _e_x___m_e_m_b_m_p_._c │ │ │ │ │ ********** aall__ppuutt__ppiixxeell ********** │ │ │ │ │ void al_put_pixel(int x, int y, ALLEGRO_COLOR color) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Draw a single pixel on the target bitmap. This operation is slow on non-memory │ │ │ │ │ bitmaps. Consider locking the bitmap if you are going to use this function │ │ │ │ │ multiple times on the same bitmap. This function is not affected by the │ │ │ │ │ transformations or the color blenders. │ │ │ │ │ See also: _A_L_L_E_G_R_O___C_O_L_O_R, _a_l___g_e_t___p_i_x_e_l, _a_l___p_u_t___b_l_e_n_d_e_d___p_i_x_e_l, _a_l___l_o_c_k___b_i_t_m_a_p │ │ │ │ │ Examples: │ │ │ │ │ * _e_x___d_r_a_w_p_i_x_e_l_s_._c │ │ │ │ │ - * _e_x___i_c_o_n_._c │ │ │ │ │ * _e_x___i_c_o_n_2_._c │ │ │ │ │ + * _e_x___i_c_o_n_._c │ │ │ │ │ ********** aall__ppuutt__bblleennddeedd__ppiixxeell ********** │ │ │ │ │ void al_put_blended_pixel(int x, int y, ALLEGRO_COLOR color) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___p_u_t___p_i_x_e_l, but the pixel color is blended using the current blenders │ │ │ │ │ before being drawn. │ │ │ │ │ See also: _A_L_L_E_G_R_O___C_O_L_O_R, _a_l___p_u_t___p_i_x_e_l │ │ │ │ │ ************ TTaarrggeett bbiittmmaapp ************ │ │ │ │ │ @@ -1387,25 +1463,37 @@ │ │ │ │ │ The above allows using _a_l___p_u_t___p_i_x_e_l on a locked bitmap without creating an FBO. │ │ │ │ │ In this example an FBO is created however: │ │ │ │ │ al_set_target_bitmap(bitmap); │ │ │ │ │ al_draw_line(x1, y1, x2, y2, color, 0); │ │ │ │ │ An OpenGL command will be used to directly draw the line into the bitmap’s │ │ │ │ │ associated texture. │ │ │ │ │ See also: _a_l___g_e_t___t_a_r_g_e_t___b_i_t_m_a_p, _a_l___s_e_t___t_a_r_g_e_t___b_a_c_k_b_u_f_f_e_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___n_o_d_i_s_p_l_a_y_._c │ │ │ │ │ + * _e_x___o_p_e_n_g_l___p_i_x_e_l___s_h_a_d_e_r_._c │ │ │ │ │ + * _e_x___b_l_e_n_d___b_e_n_c_h_._c │ │ │ │ │ ********** aall__sseett__ttaarrggeett__bbaacckkbbuuffffeerr ********** │ │ │ │ │ void al_set_target_backbuffer(ALLEGRO_DISPLAY *display) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Same as al_set_target_bitmap(al_get_backbuffer(display)); │ │ │ │ │ See also: _a_l___s_e_t___t_a_r_g_e_t___b_i_t_m_a_p, _a_l___g_e_t___b_a_c_k_b_u_f_f_e_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___k_e_y_b_o_a_r_d___f_o_c_u_s_._c │ │ │ │ │ + * _e_x___m_o_u_s_e___f_o_c_u_s_._c │ │ │ │ │ + * _e_x___o_p_e_n_g_l___p_i_x_e_l___s_h_a_d_e_r_._c │ │ │ │ │ ********** aall__ggeett__ccuurrrreenntt__ddiissppllaayy ********** │ │ │ │ │ ALLEGRO_DISPLAY *al_get_current_display(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the display that is “current” for the calling thread, or NULL if there │ │ │ │ │ is none. │ │ │ │ │ See also: _a_l___s_e_t___t_a_r_g_e_t___b_i_t_m_a_p │ │ │ │ │ +Examples: │ │ │ │ │ + * _c_o_m_m_o_n_._c │ │ │ │ │ + * _e_x___v_s_y_n_c_._c │ │ │ │ │ + * _e_x___c_o_l_o_r_2_._c │ │ │ │ │ ************ BBlleennddiinngg mmooddeess ************ │ │ │ │ │ ********** aall__ggeett__bblleennddeerr ********** │ │ │ │ │ void al_get_blender(int *op, int *src, int *dst) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the active blender for the current thread. You can pass NULL for values │ │ │ │ │ you are not interested in. │ │ │ │ │ See also: _a_l___s_e_t___b_l_e_n_d_e_r, _a_l___g_e_t___s_e_p_a_r_a_t_e___b_l_e_n_d_e_r │ │ │ │ │ @@ -1500,31 +1588,41 @@ │ │ │ │ │ al_set_blend_color(al_map_rgba_f(0.5, 0.5, 0.5, 0.5)); │ │ │ │ │ As formula: │ │ │ │ │ r = d.r * 0 + s.r * d.r │ │ │ │ │ g = d.g * 0 + s.g * d.g │ │ │ │ │ b = d.b * 0 + s.b * d.b │ │ │ │ │ a = d.a * 0 + s.a * d.a │ │ │ │ │ See also: _a_l___s_e_t___s_e_p_a_r_a_t_e___b_l_e_n_d_e_r, _a_l___s_e_t___b_l_e_n_d___c_o_l_o_r, _a_l___g_e_t___b_l_e_n_d_e_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___b_l_e_n_d___b_e_n_c_h_._c │ │ │ │ │ + * _e_x___r_o_t_a_t_e_._c │ │ │ │ │ + * _e_x___m_e_m_b_m_p_._c │ │ │ │ │ ********** aall__sseett__sseeppaarraattee__bblleennddeerr ********** │ │ │ │ │ void al_set_separate_blender(int op, int src, int dst, │ │ │ │ │ int alpha_op, int alpha_src, int alpha_dst) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___s_e_t___b_l_e_n_d_e_r, but allows specifying a separate blending operation for │ │ │ │ │ the alpha channel. This is useful if your target bitmap also has an alpha │ │ │ │ │ channel and the two alpha channels need to be combined in a different way than │ │ │ │ │ the color components. │ │ │ │ │ See also: _a_l___s_e_t___b_l_e_n_d_e_r, _a_l___g_e_t___b_l_e_n_d_e_r, _a_l___g_e_t___s_e_p_a_r_a_t_e___b_l_e_n_d_e_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___b_l_e_n_d___t_e_s_t_._c │ │ │ │ │ + * _e_x___b_l_e_n_d_2_._c_p_p │ │ │ │ │ + * _e_x___l_o_g_o_._c │ │ │ │ │ ********** aall__sseett__bblleenndd__ccoolloorr ********** │ │ │ │ │ void al_set_blend_color(ALLEGRO_COLOR color) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Sets the color to use for blending when using the ALLEGRO_CONST_COLOR or │ │ │ │ │ ALLEGRO_INVERSE_CONST_COLOR blend functions. See _a_l___s_e_t___b_l_e_n_d_e_r for more │ │ │ │ │ information. │ │ │ │ │ See also: _a_l___s_e_t___b_l_e_n_d_e_r, _a_l___g_e_t___b_l_e_n_d___c_o_l_o_r │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___b_l_e_n_d_2_._c_p_p │ │ │ │ │ ************ CClliippppiinngg ************ │ │ │ │ │ ********** aall__ggeett__cclliippppiinngg__rreeccttaannggllee ********** │ │ │ │ │ void al_get_clipping_rectangle(int *x, int *y, int *w, int *h) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Gets the clipping rectangle of the target bitmap. │ │ │ │ │ See also: _a_l___s_e_t___c_l_i_p_p_i_n_g___r_e_c_t_a_n_g_l_e │ │ │ │ │ Examples: │ │ │ │ │ @@ -1534,17 +1632,17 @@ │ │ │ │ │ ********** aall__sseett__cclliippppiinngg__rreeccttaannggllee ********** │ │ │ │ │ void al_set_clipping_rectangle(int x, int y, int width, int height) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the region of the target bitmap or display that pixels get clipped to. The │ │ │ │ │ default is to clip pixels to the entire bitmap. │ │ │ │ │ See also: _a_l___g_e_t___c_l_i_p_p_i_n_g___r_e_c_t_a_n_g_l_e, _a_l___r_e_s_e_t___c_l_i_p_p_i_n_g___r_e_c_t_a_n_g_l_e │ │ │ │ │ Examples: │ │ │ │ │ - * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ - * _e_x___l_i_n_e_s_._c │ │ │ │ │ * _e_x___r_o_t_a_t_e_._c │ │ │ │ │ + * _e_x___s_c_a_l_e_._c │ │ │ │ │ + * _e_x___l_i_n_e_s_._c │ │ │ │ │ ********** aall__rreesseett__cclliippppiinngg__rreeccttaannggllee ********** │ │ │ │ │ void al_reset_clipping_rectangle(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Equivalent to calling `al_set_clipping_rectangle(0, 0, w, h)’ where ww and hh are │ │ │ │ │ the width and height of the target bitmap respectively. │ │ │ │ │ Does nothing if there is no target bitmap. │ │ │ │ │ See also: _a_l___s_e_t___c_l_i_p_p_i_n_g___r_e_c_t_a_n_g_l_e │ │ │ │ │ @@ -1553,16 +1651,16 @@ │ │ │ │ │ ********** aall__ccoonnvveerrtt__mmaasskk__ttoo__aallpphhaa ********** │ │ │ │ │ void al_convert_mask_to_alpha(ALLEGRO_BITMAP *bitmap, ALLEGRO_COLOR mask_color) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Convert the given mask color to an alpha channel in the bitmap. Can be used to │ │ │ │ │ convert older 4.2-style bitmaps with magic pink to alpha-ready bitmaps. │ │ │ │ │ See also: _A_L_L_E_G_R_O___C_O_L_O_R │ │ │ │ │ Examples: │ │ │ │ │ - * _e_x___p_r_o_j_e_c_t_i_o_n_._c │ │ │ │ │ * _e_x___a_n_d_r_o_i_d_._c │ │ │ │ │ + * _e_x___p_r_o_j_e_c_t_i_o_n_._c │ │ │ │ │ ************ DDeeffeerrrreedd ddrraawwiinngg ************ │ │ │ │ │ ********** aall__hhoolldd__bbiittmmaapp__ddrraawwiinngg ********** │ │ │ │ │ void al_hold_bitmap_drawing(bool hold) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Enables or disables deferred bitmap drawing. This allows for efficient drawing │ │ │ │ │ of many bitmaps that share a parent bitmap, such as sub-bitmaps from a │ │ │ │ │ tilesheet or simply identical bitmaps. Drawing bitmaps that do not share a │ │ │ │ │ @@ -1578,16 +1676,16 @@ │ │ │ │ │ as many bitmaps as possible, taking care to stagger bitmaps that share parent │ │ │ │ │ bitmaps, and then disable deferred drawing. As mentioned above, this function │ │ │ │ │ also works with bitmap and truetype fonts, so if multiple lines of text need to │ │ │ │ │ be drawn, this function can speed things up. │ │ │ │ │ See also: _a_l___i_s___b_i_t_m_a_p___d_r_a_w_i_n_g___h_e_l_d │ │ │ │ │ Examples: │ │ │ │ │ * _e_x___d_e_p_t_h___m_a_s_k_._c │ │ │ │ │ - * _e_x___t_t_f_._c │ │ │ │ │ * _e_x___d_r_a_w___b_i_t_m_a_p_._c │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ********** aall__iiss__bbiittmmaapp__ddrraawwiinngg__hheelldd ********** │ │ │ │ │ bool al_is_bitmap_drawing_held(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns whether the deferred bitmap drawing mode is turned on or off. │ │ │ │ │ See also: _a_l___h_o_l_d___b_i_t_m_a_p___d_r_a_w_i_n_g │ │ │ │ │ ************ IImmaaggee II//OO ************ │ │ │ │ │ ********** aall__rreeggiisstteerr__bbiittmmaapp__llooaaddeerr ********** │ │ │ │ │ @@ -1649,16 +1747,16 @@ │ │ │ │ │ NNoottee:: the core Allegro library does not support any image file │ │ │ │ │ formats by default. You must use the allegro_image addon, or register │ │ │ │ │ your own format handler. │ │ │ │ │ See also: _a_l___l_o_a_d___b_i_t_m_a_p___f_l_a_g_s, _a_l___l_o_a_d___b_i_t_m_a_p___f, _a_l___r_e_g_i_s_t_e_r___b_i_t_m_a_p___l_o_a_d_e_r, │ │ │ │ │ _a_l___s_e_t___n_e_w___b_i_t_m_a_p___f_o_r_m_a_t, _a_l___s_e_t___n_e_w___b_i_t_m_a_p___f_l_a_g_s, _a_l___i_n_i_t___i_m_a_g_e___a_d_d_o_n │ │ │ │ │ Examples: │ │ │ │ │ * _e_x___c_o_n_v_e_r_t_._c │ │ │ │ │ - * _e_x___m_o_u_s_e_._c │ │ │ │ │ - * _e_x___o_p_e_n_g_l___p_i_x_e_l___s_h_a_d_e_r_._c │ │ │ │ │ + * _e_x___n_o_d_i_s_p_l_a_y_._c │ │ │ │ │ + * _e_x___f_i_l_e___s_l_i_c_e_._c │ │ │ │ │ ********** aall__llooaadd__bbiittmmaapp__ffllaaggss ********** │ │ │ │ │ ALLEGRO_BITMAP *al_load_bitmap_flags(const char *filename, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Loads an image file into a new _A_L_L_E_G_R_O___B_I_T_M_A_P. The file type is determined by │ │ │ │ │ _a_l___i_d_e_n_t_i_f_y___b_i_t_m_a_p, using the extension as a fallback in case identification is │ │ │ │ │ not possible. │ │ │ │ │ Returns NULL on error. │ │ │ │ │ @@ -1750,16 +1848,16 @@ │ │ │ │ │ NNoottee:: the core Allegro library does not support any image file │ │ │ │ │ formats by default. You must use the allegro_image addon, or register │ │ │ │ │ your own format handler. │ │ │ │ │ See also: _a_l___l_o_a_d___b_i_t_m_a_p___f_l_a_g_s___f, _a_l___l_o_a_d___b_i_t_m_a_p, _a_l___r_e_g_i_s_t_e_r___b_i_t_m_a_p___l_o_a_d_e_r___f, │ │ │ │ │ _a_l___i_n_i_t___i_m_a_g_e___a_d_d_o_n │ │ │ │ │ Examples: │ │ │ │ │ * _e_x___c_o_n_v_e_r_t_._c │ │ │ │ │ - * _e_x___r_e_c_o_r_d___n_a_m_e_._c │ │ │ │ │ - * _e_x___b_i_t_m_a_p___f_l_i_p_._c │ │ │ │ │ + * _e_x___f_i_l_e___s_l_i_c_e_._c │ │ │ │ │ + * _e_x___b_i_t_m_a_p___f_i_l_e_._c │ │ │ │ │ ********** aall__llooaadd__bbiittmmaapp__ffllaaggss__ff ********** │ │ │ │ │ ALLEGRO_BITMAP *al_load_bitmap_flags_f(ALLEGRO_FILE *fp, │ │ │ │ │ const char *ident, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Loads an image from an _A_L_L_E_G_R_O___F_I_L_E stream into a new _A_L_L_E_G_R_O___B_I_T_M_A_P. The file │ │ │ │ │ type is determined by _a_l___i_d_e_n_t_i_f_y___b_i_t_m_a_p___f. If identification is not possible, │ │ │ │ │ the passed ‘ident’ parameter, which is a file name extension including the │ │ │ │ │ @@ -1837,15 +1935,16 @@ │ │ │ │ │ including the leading dot. For example “.png” or “.jpg”. Returns NULL if the │ │ │ │ │ bitmap type cannot be determined. │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ See also: _a_l___i_n_i_t___i_m_a_g_e___a_d_d_o_n, _a_l___i_d_e_n_t_i_f_y___b_i_t_m_a_p, │ │ │ │ │ _a_l___r_e_g_i_s_t_e_r___b_i_t_m_a_p___i_d_e_n_t_i_f_i_e_r │ │ │ │ │ ************ RReennddeerr SSttaattee ************ │ │ │ │ │ ********** AALLLLEEGGRROO__RREENNDDEERR__SSTTAATTEE ********** │ │ │ │ │ -Source Code │ │ │ │ │ +typedef enum ALLEGRO_RENDER_STATE { │ │ │ │ │ +_S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Possible render states which can be set with _a_l___s_e_t___r_e_n_d_e_r___s_t_a_t_e: │ │ │ │ │ ALLEGRO_ALPHA_TEST │ │ │ │ │ If this is set to 1, the values of ALLEGRO_ALPHA_FUNCTION and │ │ │ │ │ ALLEGRO_ALPHA_TEST_VALUE define a comparison function which is performed │ │ │ │ │ on the alpha component of each pixel. Only if it evaluates to true the │ │ │ │ │ pixel is written. Otherwise no subsequent processing (like depth test or │ │ │ │ │ blending) is performed. This can be very useful, for example if a depth │ │ │ │ │ @@ -1866,28 +1965,30 @@ │ │ │ │ │ will write a value of 0 into the depth buffer. │ │ │ │ │ ALLEGRO_DEPTH_FUNCTION │ │ │ │ │ One of _A_L_L_E_G_R_O___R_E_N_D_E_R___F_U_N_C_T_I_O_N, only used when ALLEGRO_DEPTH_TEST is 1. │ │ │ │ │ Since: 5.1.2 │ │ │ │ │ See also: _a_l___s_e_t___r_e_n_d_e_r___s_t_a_t_e, _A_L_L_E_G_R_O___R_E_N_D_E_R___F_U_N_C_T_I_O_N, │ │ │ │ │ _A_L_L_E_G_R_O___W_R_I_T_E___M_A_S_K___F_L_A_G_S │ │ │ │ │ ********** AALLLLEEGGRROO__RREENNDDEERR__FFUUNNCCTTIIOONN ********** │ │ │ │ │ -Source Code │ │ │ │ │ +typedef enum ALLEGRO_RENDER_FUNCTION { │ │ │ │ │ +_S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Possible functions are: │ │ │ │ │ * ALLEGRO_RENDER_NEVER │ │ │ │ │ * ALLEGRO_RENDER_ALWAYS │ │ │ │ │ * ALLEGRO_RENDER_LESS │ │ │ │ │ * ALLEGRO_RENDER_EQUAL │ │ │ │ │ * ALLEGRO_RENDER_LESS_EQUAL │ │ │ │ │ * ALLEGRO_RENDER_GREATER │ │ │ │ │ * ALLEGRO_RENDER_NOT_EQUAL │ │ │ │ │ * ALLEGRO_RENDER_GREATER_EQUAL │ │ │ │ │ Since: 5.1.2 │ │ │ │ │ See also: _a_l___s_e_t___r_e_n_d_e_r___s_t_a_t_e │ │ │ │ │ ********** AALLLLEEGGRROO__WWRRIITTEE__MMAASSKK__FFLLAAGGSS ********** │ │ │ │ │ -Source Code │ │ │ │ │ +typedef enum ALLEGRO_WRITE_MASK_FLAGS { │ │ │ │ │ +_S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Each enabled bit means the corresponding value is written, a disabled bit means │ │ │ │ │ it is not. │ │ │ │ │ * ALLEGRO_MASK_RED │ │ │ │ │ * ALLEGRO_MASK_GREEN │ │ │ │ │ * ALLEGRO_MASK_BLUE │ │ │ │ │ * ALLEGRO_MASK_ALPHA │ │ │ │ │ * ALLEGRO_MASK_DEPTH │ │ │ │ │ @@ -1908,17 +2009,17 @@ │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set one of several render attributes; see _A_L_L_E_G_R_O___R_E_N_D_E_R___S_T_A_T_E for details. │ │ │ │ │ This function does nothing if the target bitmap is a memory bitmap. │ │ │ │ │ Since: 5.1.2 │ │ │ │ │ See also: _a_l___g_e_t___r_e_n_d_e_r___s_t_a_t_e, _A_L_L_E_G_R_O___R_E_N_D_E_R___S_T_A_T_E, _A_L_L_E_G_R_O___R_E_N_D_E_R___F_U_N_C_T_I_O_N, │ │ │ │ │ _A_L_L_E_G_R_O___W_R_I_T_E___M_A_S_K___F_L_A_G_S │ │ │ │ │ Examples: │ │ │ │ │ - * _e_x___d_e_p_t_h___t_a_r_g_e_t_._c │ │ │ │ │ * _e_x___d_e_p_t_h___m_a_s_k_._c │ │ │ │ │ - * _e_x___c_a_m_e_r_a_._c │ │ │ │ │ + * _e_x___d_e_p_t_h___t_a_r_g_e_t_._c │ │ │ │ │ + * _e_x___d_r_a_w___b_i_t_m_a_p_._c │ │ │ │ │ ********** aall__bbaacckkuupp__ddiirrttyy__bbiittmmaapp ********** │ │ │ │ │ void al_backup_dirty_bitmap(ALLEGRO_BITMAP *bitmap) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ On some platforms, notably Windows Direct3D and Android, textures may be lost │ │ │ │ │ at any time for events such as display resize or switching out of the app. On │ │ │ │ │ those platforms, bitmaps created without the ALLEGRO_NO_PRESERVE_TEXTURE flag │ │ │ │ │ automatically get backed up to system memory every time al_flip_display is │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/haptic.html │ │ │ │ @@ -265,14 +265,21 @@ │ │ │ │

    Unstable │ │ │ │ API: Perhaps could be simplified due to limited support for all │ │ │ │ the exposed features across all of the platforms. Awaiting feedback from │ │ │ │ users.

    │ │ │ │
    │ │ │ │

    See also: al_get_haptic_from_joystick

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_HAPTIC_CONSTANTS

    │ │ │ │ 
    enum ALLEGRO_HAPTIC_CONSTANTS
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    This enum contains flags that are used to define haptic effects and │ │ │ │ capabilities. If the flag is set in the return value of Since: 5.1.8

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: Perhaps could be simplified due to limited support for all │ │ │ │ the exposed features across all of the platforms. Awaiting feedback from │ │ │ │ users.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_HAPTIC_EFFECT_ID

    │ │ │ │ 
    typedef struct ALLEGRO_HAPTIC_EFFECT_ID ALLEGRO_HAPTIC_EFFECT_ID;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    This struct is used as a handle to control playback of a haptic │ │ │ │ effect and should be considered opaque. Its implementation is visible │ │ │ │ @@ -531,14 +545,21 @@ │ │ │ │

    Since: 5.1.8

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: Perhaps could be simplified due to limited support for all │ │ │ │ the exposed features across all of the platforms. Awaiting feedback from │ │ │ │ users.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_install_haptic

    │ │ │ │ 
    bool al_install_haptic(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Installs the haptic (force feedback) device subsystem. This must be │ │ │ │ called before using any other haptic-related functions. Returns true if │ │ │ │ @@ -792,14 +813,21 @@ │ │ │ │

    Since: 5.1.8

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: Perhaps could be simplified due to limited support for all │ │ │ │ the exposed features across all of the platforms. Awaiting feedback from │ │ │ │ users.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_is_haptic_active

    │ │ │ │ 
    bool al_is_haptic_active(ALLEGRO_HAPTIC *hap)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true if the haptic device can currently be used, false if │ │ │ │ not.

    │ │ │ │ @@ -1201,14 +1229,21 @@ │ │ │ │

    Since: 5.1.8

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: Perhaps could be simplified due to limited support for all │ │ │ │ the exposed features across all of the platforms. Awaiting feedback from │ │ │ │ users.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_rumble_haptic

    │ │ │ │ 
    bool al_rumble_haptic(ALLEGRO_HAPTIC *hap,
│ │ │ │     double intensity, double duration, ALLEGRO_HAPTIC_EFFECT_ID *id)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Uploads a simple rumble effect to the haptic device and starts │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -90,14 +90,17 @@ │ │ │ │ │ This is an abstract data type representing a haptic device that supports force │ │ │ │ │ feedback or vibration. │ │ │ │ │ Since: 5.1.8 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: Perhaps could be simplified due to limited support for │ │ │ │ │ all the exposed features across all of the platforms. Awaiting │ │ │ │ │ feedback from users. │ │ │ │ │ See also: _a_l___g_e_t___h_a_p_t_i_c___f_r_o_m___j_o_y_s_t_i_c_k │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___h_a_p_t_i_c_._c │ │ │ │ │ + * _e_x___h_a_p_t_i_c_2_._c_p_p │ │ │ │ │ ************ AALLLLEEGGRROO__HHAAPPTTIICC__CCOONNSSTTAANNTTSS ************ │ │ │ │ │ enum ALLEGRO_HAPTIC_CONSTANTS │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This enum contains flags that are used to define haptic effects and │ │ │ │ │ capabilities. If the flag is set in the return value of │ │ │ │ │ _a_l___g_e_t___h_a_p_t_i_c___c_a_p_a_b_i_l_i_t_i_e_s, it means the device supports the given effect. The │ │ │ │ │ value of these flags should be set into a _A_L_L_E_G_R_O___H_A_P_T_I_C___E_F_F_E_C_T struct to │ │ │ │ │ @@ -283,24 +286,30 @@ │ │ │ │ │ If you don’t want to use an envelope, then set all four fields of │ │ │ │ │ data.envelope to 0.0. The effect will then play back at full intensity │ │ │ │ │ throughout its playback. │ │ │ │ │ Since: 5.1.8 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: Perhaps could be simplified due to limited support for │ │ │ │ │ all the exposed features across all of the platforms. Awaiting │ │ │ │ │ feedback from users. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___h_a_p_t_i_c_._c │ │ │ │ │ + * _e_x___h_a_p_t_i_c_2_._c_p_p │ │ │ │ │ ************ AALLLLEEGGRROO__HHAAPPTTIICC__EEFFFFEECCTT__IIDD ************ │ │ │ │ │ typedef struct ALLEGRO_HAPTIC_EFFECT_ID ALLEGRO_HAPTIC_EFFECT_ID; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This struct is used as a handle to control playback of a haptic effect and │ │ │ │ │ should be considered opaque. Its implementation is visible merely to allow │ │ │ │ │ allocation by the users of the Allegro library. │ │ │ │ │ Since: 5.1.8 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: Perhaps could be simplified due to limited support for │ │ │ │ │ all the exposed features across all of the platforms. Awaiting │ │ │ │ │ feedback from users. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___h_a_p_t_i_c_._c │ │ │ │ │ + * _e_x___h_a_p_t_i_c_2_._c_p_p │ │ │ │ │ ************ aall__iinnssttaallll__hhaappttiicc ************ │ │ │ │ │ bool al_install_haptic(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Installs the haptic (force feedback) device subsystem. This must be called │ │ │ │ │ before using any other haptic-related functions. Returns true if the haptics │ │ │ │ │ subsystem could be initialized correctly, false in case of error. │ │ │ │ │ For portability you should first open a display before calling │ │ │ │ │ @@ -447,14 +456,17 @@ │ │ │ │ │ Returns true on success or false if the haptic device couldn’t be released for │ │ │ │ │ any reason, such as NULL being passed, the device not being active or failure │ │ │ │ │ in the driver. │ │ │ │ │ Since: 5.1.8 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: Perhaps could be simplified due to limited support for │ │ │ │ │ all the exposed features across all of the platforms. Awaiting │ │ │ │ │ feedback from users. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___h_a_p_t_i_c_._c │ │ │ │ │ + * _e_x___h_a_p_t_i_c_2_._c_p_p │ │ │ │ │ ************ aall__iiss__hhaappttiicc__aaccttiivvee ************ │ │ │ │ │ bool al_is_haptic_active(ALLEGRO_HAPTIC *hap) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true if the haptic device can currently be used, false if not. │ │ │ │ │ Since: 5.1.8 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: Perhaps could be simplified due to limited support for │ │ │ │ │ all the exposed features across all of the platforms. Awaiting │ │ │ │ │ @@ -682,14 +694,17 @@ │ │ │ │ │ Returns true on success, false if the effect couldn’t be released for any │ │ │ │ │ reason such as when NULL is passed, the effect is not active or failure to │ │ │ │ │ release the effect by the driver. │ │ │ │ │ Since: 5.1.8 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: Perhaps could be simplified due to limited support for │ │ │ │ │ all the exposed features across all of the platforms. Awaiting │ │ │ │ │ feedback from users. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___h_a_p_t_i_c_._c │ │ │ │ │ + * _e_x___h_a_p_t_i_c_2_._c_p_p │ │ │ │ │ ************ aall__rruummbbllee__hhaappttiicc ************ │ │ │ │ │ bool al_rumble_haptic(ALLEGRO_HAPTIC *hap, │ │ │ │ │ double intensity, double duration, ALLEGRO_HAPTIC_EFFECT_ID *id) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Uploads a simple rumble effect to the haptic device and starts playback │ │ │ │ │ immediately. The parameter intensity is a relative magnitude between 0.0 and │ │ │ │ │ 1.0 that determines the intensity of the rumble effect. The duration determines │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/image.html │ │ │ │ @@ -207,14 +207,23 @@ │ │ │ │ installed libraries, but are not guaranteed and should not be assumed to │ │ │ │ be universally available.

    │ │ │ │

    The DDS format is only supported to load from, and only if the DDS │ │ │ │ file contains textures compressed in the DXT1, DXT3 and DXT5 formats. │ │ │ │ Note that when loading a DDS file, the created bitmap will always be a │ │ │ │ video bitmap and will have the pixel format matching the format in the │ │ │ │ file.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_is_image_addon_initialized

    │ │ │ │ 
    bool al_is_image_addon_initialized(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true if the image addon is initialized, otherwise returns │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -64,14 +64,18 @@ │ │ │ │ │ Other formats may be available depending on the operating system and installed │ │ │ │ │ libraries, but are not guaranteed and should not be assumed to be universally │ │ │ │ │ available. │ │ │ │ │ The DDS format is only supported to load from, and only if the DDS file │ │ │ │ │ contains textures compressed in the DXT1, DXT3 and DXT5 formats. Note that when │ │ │ │ │ loading a DDS file, the created bitmap will always be a video bitmap and will │ │ │ │ │ have the pixel format matching the format in the file. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___c_o_n_v_e_r_t_._c │ │ │ │ │ + * _e_x___n_o_d_i_s_p_l_a_y_._c │ │ │ │ │ + * _e_x___o_p_e_n_g_l___p_i_x_e_l___s_h_a_d_e_r_._c │ │ │ │ │ ************ aall__iiss__iimmaaggee__aaddddoonn__iinniittiiaalliizzeedd ************ │ │ │ │ │ bool al_is_image_addon_initialized(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true if the image addon is initialized, otherwise returns false. │ │ │ │ │ Since: 5.2.6 │ │ │ │ │ ************ aall__sshhuuttddoowwnn__iimmaaggee__aaddddoonn ************ │ │ │ │ │ void al_shutdown_image_addon(void) │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/joystick.html │ │ │ │ @@ -230,28 +230,44 @@ │ │ │ │ 

    typedef struct ALLEGRO_JOYSTICK ALLEGRO_JOYSTICK;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    This is an abstract data type representing a physical joystick.

    │ │ │ │

    See also: al_get_joystick

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_JOYSTICK_STATE

    │ │ │ │ 
    typedef struct ALLEGRO_JOYSTICK_STATE ALLEGRO_JOYSTICK_STATE;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    This is a structure that is used to hold a “snapshot” of a joystick’s │ │ │ │ axes and buttons at a particular instant. All fields public and │ │ │ │ read-only.

    │ │ │ │ 
    struct {
│ │ │ │     float axis[num_axes];             // -1.0 to 1.0
│ │ │ │  } stick[num_sticks];
│ │ │ │  int button[num_buttons];             // 0 to 32767
    │ │ │ │

    See also: al_get_joystick_state

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_JOYFLAGS

    │ │ │ │ 
    enum ALLEGRO_JOYFLAGS
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │
      │ │ │ │
    • ALLEGRO_JOYFLAG_DIGITAL - the stick provides digital input
      • │ │ │ │ @@ -265,14 +281,23 @@ │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Install a joystick driver, returning true if successful. If a │ │ │ │ joystick driver was already installed, returns true immediately.

      │ │ │ │

      See also: al_uninstall_joystick

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_uninstall_joystick

      │ │ │ │ 
      void al_uninstall_joystick(void)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Uninstalls the active joystick driver. All outstanding ALLEGRO_JOYSTICK structures │ │ │ │ @@ -319,27 +344,45 @@ │ │ │ │ your game has an input configuration screen or similar, you may wish to │ │ │ │ call al_reconfigure_joysticks │ │ │ │ when entering that screen.

      │ │ │ │

      See also: al_get_joystick_event_source, │ │ │ │ ALLEGRO_EVENT

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_get_num_joysticks

      │ │ │ │ 
      int al_get_num_joysticks(void)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Return the number of joysticks currently on the system (or │ │ │ │ potentially on the system). This number can change after al_reconfigure_joysticks │ │ │ │ is called, in order to support hotplugging.

      │ │ │ │

      Returns 0 if there is no joystick driver installed.

      │ │ │ │

      See also: al_get_joystick, al_get_joystick_active

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_get_joystick

      │ │ │ │ 
      ALLEGRO_JOYSTICK * al_get_joystick(int num)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Get a handle for a joystick on the system. The number may be from 0 │ │ │ │ to │ │ │ │

      See also: al_get_num_joysticks, al_reconfigure_joysticks, │ │ │ │ al_get_joystick_active

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_release_joystick

      │ │ │ │ 
      void al_release_joystick(ALLEGRO_JOYSTICK *joy)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      This function currently does nothing.

      │ │ │ │

      See also: al_get_joystick

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_get_joystick_active

      │ │ │ │ 
      bool al_get_joystick_active(ALLEGRO_JOYSTICK *joy)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Return if the joystick handle is “active”, i.e. in the current │ │ │ │ configuration, the handle represents some physical device plugged into │ │ │ │ the system. al_get_joystick │ │ │ │ returns active handles. After reconfiguration, active handles may become │ │ │ │ inactive, and vice versa.

      │ │ │ │

      See also: al_reconfigure_joysticks

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_get_joystick_name

      │ │ │ │ 
      const char *al_get_joystick_name(ALLEGRO_JOYSTICK *joy)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Return the name of the given joystick.

      │ │ │ │

      See also: al_get_joystick_stick_name, │ │ │ │ al_get_joystick_axis_name, │ │ │ │ al_get_joystick_button_name

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_get_joystick_stick_name

      │ │ │ │ 
      const char *al_get_joystick_stick_name(ALLEGRO_JOYSTICK *joy, int stick)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Return the name of the given “stick”. If the stick doesn’t exist, │ │ │ │ NULL is returned.

      │ │ │ │

      See also: al_get_joystick_axis_name, │ │ │ │ al_get_joystick_num_sticks

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_get_joystick_axis_name

      │ │ │ │ 
      const char *al_get_joystick_axis_name(ALLEGRO_JOYSTICK *joy, int stick, int axis)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Return the name of the given axis. If the axis doesn’t exist, NULL is │ │ │ │ returned. Indices begin from 0.

      │ │ │ │

      See also: al_get_joystick_stick_name, │ │ │ │ al_get_joystick_num_axes

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_get_joystick_button_name

      │ │ │ │ 
      const char *al_get_joystick_button_name(ALLEGRO_JOYSTICK *joy, int button)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Return the name of the given button. If the button doesn’t exist, │ │ │ │ NULL is returned. Indices begin from 0.

      │ │ │ │

      See also: al_get_joystick_stick_name, │ │ │ │ al_get_joystick_axis_name, │ │ │ │ al_get_joystick_num_buttons

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_get_joystick_stick_flags

      │ │ │ │ 
      int al_get_joystick_stick_flags(ALLEGRO_JOYSTICK *joy, int stick)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Return the flags of the given “stick”. If the stick doesn’t exist, │ │ │ │ NULL is returned. Indices begin from 0.

      │ │ │ │ @@ -439,51 +531,88 @@ │ │ │ │ Code

      │ │ │ │

      Return the number of “sticks” on the given joystick. A stick has one │ │ │ │ or more axes.

      │ │ │ │

      See also: al_get_joystick_num_axes, │ │ │ │ al_get_joystick_num_buttons

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_get_joystick_num_axes

      │ │ │ │ 
      int al_get_joystick_num_axes(ALLEGRO_JOYSTICK *joy, int stick)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Return the number of axes on the given “stick”. If the stick doesn’t │ │ │ │ exist, 0 is returned.

      │ │ │ │

      See also: al_get_joystick_num_sticks

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_get_joystick_num_buttons

      │ │ │ │ 
      int al_get_joystick_num_buttons(ALLEGRO_JOYSTICK *joy)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Return the number of buttons on the joystick.

      │ │ │ │

      See also: al_get_joystick_num_sticks

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_get_joystick_state

      │ │ │ │ 
      void al_get_joystick_state(ALLEGRO_JOYSTICK *joy, ALLEGRO_JOYSTICK_STATE *ret_state)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Get the current joystick state.

      │ │ │ │

      See also: ALLEGRO_JOYSTICK_STATE, │ │ │ │ al_get_joystick_num_buttons, │ │ │ │ al_get_joystick_num_axes

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_get_joystick_event_source

      │ │ │ │ 
      ALLEGRO_EVENT_SOURCE *al_get_joystick_event_source(void)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Returns the global joystick event source. All joystick events are │ │ │ │ generated by this event source.

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      │ │ │ │ Allegro version 5.2.10 │ │ │ │ - Last updated: 2025-01-09 13:52:42 UTC │ │ │ │

      │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -74,37 +74,48 @@ │ │ │ │ │ mutually exclusive. The haptics subsystem will use the same driver as the │ │ │ │ │ joystick system does. │ │ │ │ │ ************ AALLLLEEGGRROO__JJOOYYSSTTIICCKK ************ │ │ │ │ │ typedef struct ALLEGRO_JOYSTICK ALLEGRO_JOYSTICK; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This is an abstract data type representing a physical joystick. │ │ │ │ │ See also: _a_l___g_e_t___j_o_y_s_t_i_c_k │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___h_a_p_t_i_c_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ ************ AALLLLEEGGRROO__JJOOYYSSTTIICCKK__SSTTAATTEE ************ │ │ │ │ │ typedef struct ALLEGRO_JOYSTICK_STATE ALLEGRO_JOYSTICK_STATE; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This is a structure that is used to hold a “snapshot” of a joystick’s axes and │ │ │ │ │ buttons at a particular instant. All fields public and read-only. │ │ │ │ │ struct { │ │ │ │ │ float axis[num_axes]; // -1.0 to 1.0 │ │ │ │ │ } stick[num_sticks]; │ │ │ │ │ int button[num_buttons]; // 0 to 32767 │ │ │ │ │ See also: _a_l___g_e_t___j_o_y_s_t_i_c_k___s_t_a_t_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ ************ AALLLLEEGGRROO__JJOOYYFFLLAAGGSS ************ │ │ │ │ │ enum ALLEGRO_JOYFLAGS │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ * ALLEGRO_JOYFLAG_DIGITAL - the stick provides digital input │ │ │ │ │ * ALLEGRO_JOYFLAG_ANALOGUE - the stick provides analogue input │ │ │ │ │ (this enum is a holdover from the old API and may be removed) │ │ │ │ │ See also: _a_l___g_e_t___j_o_y_s_t_i_c_k___s_t_i_c_k___f_l_a_g_s │ │ │ │ │ ************ aall__iinnssttaallll__jjooyyssttiicckk ************ │ │ │ │ │ bool al_install_joystick(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Install a joystick driver, returning true if successful. If a joystick driver │ │ │ │ │ was already installed, returns true immediately. │ │ │ │ │ See also: _a_l___u_n_i_n_s_t_a_l_l___j_o_y_s_t_i_c_k │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___h_a_p_t_i_c_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__uunniinnssttaallll__jjooyyssttiicckk ************ │ │ │ │ │ void al_uninstall_joystick(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Uninstalls the active joystick driver. All outstanding _A_L_L_E_G_R_O___J_O_Y_S_T_I_C_K │ │ │ │ │ structures are invalidated. If no joystick driver was active, this function │ │ │ │ │ does nothing. │ │ │ │ │ This function is automatically called when Allegro is shut down. │ │ │ │ │ @@ -130,102 +141,147 @@ │ │ │ │ │ again, being reused to represent newly connected devices. │ │ │ │ │ Returns true if the joystick configuration changed, otherwise returns false. │ │ │ │ │ It is possible that on some systems, Allegro won’t be able to generate │ │ │ │ │ ALLEGRO_EVENT_JOYSTICK_CONFIGURATION events. If your game has an input │ │ │ │ │ configuration screen or similar, you may wish to call _a_l___r_e_c_o_n_f_i_g_u_r_e___j_o_y_s_t_i_c_k_s │ │ │ │ │ when entering that screen. │ │ │ │ │ See also: _a_l___g_e_t___j_o_y_s_t_i_c_k___e_v_e_n_t___s_o_u_r_c_e, _A_L_L_E_G_R_O___E_V_E_N_T │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ + * _e_x___h_a_p_t_i_c_2_._c_p_p │ │ │ │ │ ************ aall__ggeett__nnuumm__jjooyyssttiicckkss ************ │ │ │ │ │ int al_get_num_joysticks(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the number of joysticks currently on the system (or potentially on the │ │ │ │ │ system). This number can change after _a_l___r_e_c_o_n_f_i_g_u_r_e___j_o_y_s_t_i_c_k_s is called, in │ │ │ │ │ order to support hotplugging. │ │ │ │ │ Returns 0 if there is no joystick driver installed. │ │ │ │ │ See also: _a_l___g_e_t___j_o_y_s_t_i_c_k, _a_l___g_e_t___j_o_y_s_t_i_c_k___a_c_t_i_v_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___h_a_p_t_i_c_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___h_a_p_t_i_c_2_._c_p_p │ │ │ │ │ ************ aall__ggeett__jjooyyssttiicckk ************ │ │ │ │ │ ALLEGRO_JOYSTICK * al_get_joystick(int num) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get a handle for a joystick on the system. The number may be from 0 to │ │ │ │ │ _a_l___g_e_t___n_u_m___j_o_y_s_t_i_c_k_s-1. If successful a pointer to a joystick object is │ │ │ │ │ returned, which represents a physical device. Otherwise NULL is returned. │ │ │ │ │ The handle and the index are only incidentally linked. After │ │ │ │ │ _a_l___r_e_c_o_n_f_i_g_u_r_e___j_o_y_s_t_i_c_k_s is called, _a_l___g_e_t___j_o_y_s_t_i_c_k may return handles in a │ │ │ │ │ different order, and handles which represent disconnected devices will not be │ │ │ │ │ returned. │ │ │ │ │ See also: _a_l___g_e_t___n_u_m___j_o_y_s_t_i_c_k_s, _a_l___r_e_c_o_n_f_i_g_u_r_e___j_o_y_s_t_i_c_k_s, │ │ │ │ │ _a_l___g_e_t___j_o_y_s_t_i_c_k___a_c_t_i_v_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___h_a_p_t_i_c_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__rreelleeaassee__jjooyyssttiicckk ************ │ │ │ │ │ void al_release_joystick(ALLEGRO_JOYSTICK *joy) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This function currently does nothing. │ │ │ │ │ See also: _a_l___g_e_t___j_o_y_s_t_i_c_k │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___h_a_p_t_i_c_._c │ │ │ │ │ ************ aall__ggeett__jjooyyssttiicckk__aaccttiivvee ************ │ │ │ │ │ bool al_get_joystick_active(ALLEGRO_JOYSTICK *joy) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return if the joystick handle is “active”, i.e. in the current configuration, │ │ │ │ │ the handle represents some physical device plugged into the system. │ │ │ │ │ _a_l___g_e_t___j_o_y_s_t_i_c_k returns active handles. After reconfiguration, active handles │ │ │ │ │ may become inactive, and vice versa. │ │ │ │ │ See also: _a_l___r_e_c_o_n_f_i_g_u_r_e___j_o_y_s_t_i_c_k_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ ************ aall__ggeett__jjooyyssttiicckk__nnaammee ************ │ │ │ │ │ const char *al_get_joystick_name(ALLEGRO_JOYSTICK *joy) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the name of the given joystick. │ │ │ │ │ See also: _a_l___g_e_t___j_o_y_s_t_i_c_k___s_t_i_c_k___n_a_m_e, _a_l___g_e_t___j_o_y_s_t_i_c_k___a_x_i_s___n_a_m_e, │ │ │ │ │ _a_l___g_e_t___j_o_y_s_t_i_c_k___b_u_t_t_o_n___n_a_m_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___h_a_p_t_i_c_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__ggeett__jjooyyssttiicckk__ssttiicckk__nnaammee ************ │ │ │ │ │ const char *al_get_joystick_stick_name(ALLEGRO_JOYSTICK *joy, int stick) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the name of the given “stick”. If the stick doesn’t exist, NULL is │ │ │ │ │ returned. │ │ │ │ │ See also: _a_l___g_e_t___j_o_y_s_t_i_c_k___a_x_i_s___n_a_m_e, _a_l___g_e_t___j_o_y_s_t_i_c_k___n_u_m___s_t_i_c_k_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__ggeett__jjooyyssttiicckk__aaxxiiss__nnaammee ************ │ │ │ │ │ const char *al_get_joystick_axis_name(ALLEGRO_JOYSTICK *joy, int stick, int │ │ │ │ │ axis) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the name of the given axis. If the axis doesn’t exist, NULL is returned. │ │ │ │ │ Indices begin from 0. │ │ │ │ │ See also: _a_l___g_e_t___j_o_y_s_t_i_c_k___s_t_i_c_k___n_a_m_e, _a_l___g_e_t___j_o_y_s_t_i_c_k___n_u_m___a_x_e_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__ggeett__jjooyyssttiicckk__bbuuttttoonn__nnaammee ************ │ │ │ │ │ const char *al_get_joystick_button_name(ALLEGRO_JOYSTICK *joy, int button) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the name of the given button. If the button doesn’t exist, NULL is │ │ │ │ │ returned. Indices begin from 0. │ │ │ │ │ See also: _a_l___g_e_t___j_o_y_s_t_i_c_k___s_t_i_c_k___n_a_m_e, _a_l___g_e_t___j_o_y_s_t_i_c_k___a_x_i_s___n_a_m_e, │ │ │ │ │ _a_l___g_e_t___j_o_y_s_t_i_c_k___n_u_m___b_u_t_t_o_n_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__ggeett__jjooyyssttiicckk__ssttiicckk__ffllaaggss ************ │ │ │ │ │ int al_get_joystick_stick_flags(ALLEGRO_JOYSTICK *joy, int stick) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the flags of the given “stick”. If the stick doesn’t exist, NULL is │ │ │ │ │ returned. Indices begin from 0. │ │ │ │ │ See also: _A_L_L_E_G_R_O___J_O_Y_F_L_A_G_S │ │ │ │ │ ************ aall__ggeett__jjooyyssttiicckk__nnuumm__ssttiicckkss ************ │ │ │ │ │ int al_get_joystick_num_sticks(ALLEGRO_JOYSTICK *joy) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the number of “sticks” on the given joystick. A stick has one or more │ │ │ │ │ axes. │ │ │ │ │ See also: _a_l___g_e_t___j_o_y_s_t_i_c_k___n_u_m___a_x_e_s, _a_l___g_e_t___j_o_y_s_t_i_c_k___n_u_m___b_u_t_t_o_n_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__ggeett__jjooyyssttiicckk__nnuumm__aaxxeess ************ │ │ │ │ │ int al_get_joystick_num_axes(ALLEGRO_JOYSTICK *joy, int stick) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the number of axes on the given “stick”. If the stick doesn’t exist, 0 │ │ │ │ │ is returned. │ │ │ │ │ See also: _a_l___g_e_t___j_o_y_s_t_i_c_k___n_u_m___s_t_i_c_k_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__ggeett__jjooyyssttiicckk__nnuumm__bbuuttttoonnss ************ │ │ │ │ │ int al_get_joystick_num_buttons(ALLEGRO_JOYSTICK *joy) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the number of buttons on the joystick. │ │ │ │ │ See also: _a_l___g_e_t___j_o_y_s_t_i_c_k___n_u_m___s_t_i_c_k_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__ggeett__jjooyyssttiicckk__ssttaattee ************ │ │ │ │ │ void al_get_joystick_state(ALLEGRO_JOYSTICK *joy, ALLEGRO_JOYSTICK_STATE │ │ │ │ │ *ret_state) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get the current joystick state. │ │ │ │ │ See also: _A_L_L_E_G_R_O___J_O_Y_S_T_I_C_K___S_T_A_T_E, _a_l___g_e_t___j_o_y_s_t_i_c_k___n_u_m___b_u_t_t_o_n_s, │ │ │ │ │ _a_l___g_e_t___j_o_y_s_t_i_c_k___n_u_m___a_x_e_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__ggeett__jjooyyssttiicckk__eevveenntt__ssoouurrccee ************ │ │ │ │ │ ALLEGRO_EVENT_SOURCE *al_get_joystick_event_source(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the global joystick event source. All _j_o_y_s_t_i_c_k_ _e_v_e_n_t_s are generated by │ │ │ │ │ this event source. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___h_o_t_p_l_u_g_g_i_n_g_._c │ │ │ │ │ + * _e_x___j_o_y_s_t_i_c_k___e_v_e_n_t_s_._c │ │ │ │ │ + * _e_x___h_a_p_t_i_c_2_._c_p_p │ │ │ │ │ Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/keyboard.html │ │ │ │ @@ -212,14 +212,23 @@ │ │ │ │
        │ │ │ │
      • display - points to the display that had keyboard focus at the time │ │ │ │ the state was saved. If no display was focused, this points to │ │ │ │ NULL.
        • │ │ │ │
      │ │ │ │

      You cannot read the state of keys directly. Use the function al_key_down.

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      Key codes

      │ │ │ │

      The constant ALLEGRO_KEY_MAX is always one higher than the highest │ │ │ │ key code. So if you want to use the key code as array index you can do │ │ │ │ something like this:

      │ │ │ │ 
      bool pressed_keys[ALLEGRO_KEY_MAX];
│ │ │ │  //...
│ │ │ │  pressed_keys[key_code] = true;
      │ │ │ │ @@ -341,14 +350,23 @@ │ │ │ │ href="https://github.com/liballeg/allegro5/blob/master/src/keybdnu.c#L121">Source │ │ │ │ Code

      │ │ │ │

      Install a keyboard driver. Returns true if successful. If a driver │ │ │ │ was already installed, nothing happens and true is returned.

      │ │ │ │

      See also: al_uninstall_keyboard, al_is_keyboard_installed

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_is_keyboard_installed

      │ │ │ │ 
      bool al_is_keyboard_installed(void)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Returns true if al_install_keyboard was │ │ │ │ @@ -371,14 +389,23 @@ │ │ │ │ Code

      │ │ │ │

      Save the state of the keyboard specified at the time the function is │ │ │ │ called into the structure pointed to by ret_state.

      │ │ │ │

      See also: al_key_down, al_clear_keyboard_state, │ │ │ │ ALLEGRO_KEYBOARD_STATE

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_clear_keyboard_state

      │ │ │ │ 
      void al_clear_keyboard_state(ALLEGRO_DISPLAY *display)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Clear the state of the keyboard, emitting ALLEGRO_EVENT_KEY_UP for │ │ │ │ @@ -396,29 +423,48 @@ │ │ │ │ href="keyboard.html#allegro_keyboard_state">ALLEGRO_KEYBOARD_STATE

      │ │ │ │

      Since: 5.2.3

      │ │ │ │
      │ │ │ │

      Unstable │ │ │ │ API: This is a new feature and the exact semantics are still │ │ │ │ being decided upon.

      │ │ │ │
      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_key_down

      │ │ │ │ 
      bool al_key_down(const ALLEGRO_KEYBOARD_STATE *state, int keycode)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Return true if the key specified was held down in the state │ │ │ │ specified.

      │ │ │ │

      See also: ALLEGRO_KEYBOARD_STATE

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_keycode_to_name

      │ │ │ │ 
      const char *al_keycode_to_name(int keycode)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Converts the given keycode to a description of the key.

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_can_set_keyboard_leds

      │ │ │ │ 
      bool al_can_set_keyboard_leds(void)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Returns true if setting the keyboard LED indicators is available.

      │ │ │ │

      Since: 5.2.9

      │ │ │ │ @@ -444,14 +490,23 @@ │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Retrieve the keyboard event source. All keyboard events are │ │ │ │ generated by this event source.

      │ │ │ │

      Returns NULL if the keyboard subsystem was not installed.

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      │ │ │ │ Allegro version 5.2.10 │ │ │ │ - Last updated: 2025-01-09 13:52:42 UTC │ │ │ │

      │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -62,14 +62,18 @@ │ │ │ │ │ typedef struct ALLEGRO_KEYBOARD_STATE ALLEGRO_KEYBOARD_STATE; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This is a structure that is used to hold a “snapshot” of a keyboard’s state at │ │ │ │ │ a particular instant. It contains the following publically readable fields: │ │ │ │ │ * display - points to the display that had keyboard focus at the time the │ │ │ │ │ state was saved. If no display was focused, this points to NULL. │ │ │ │ │ You cannot read the state of keys directly. Use the function _a_l___k_e_y___d_o_w_n. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_3_d_._c_p_p │ │ │ │ │ + * _e_x___k_e_y_b_o_a_r_d___f_o_c_u_s_._c │ │ │ │ │ + * _e_x___m_o_u_s_e___f_o_c_u_s_._c │ │ │ │ │ ************ KKeeyy ccooddeess ************ │ │ │ │ │ The constant ALLEGRO_KEY_MAX is always one higher than the highest key code. So │ │ │ │ │ if you want to use the key code as array index you can do something like this: │ │ │ │ │ bool pressed_keys[ALLEGRO_KEY_MAX]; │ │ │ │ │ //... │ │ │ │ │ pressed_keys[key_code] = true; │ │ │ │ │ These are the list of key codes used by Allegro, which are returned in the │ │ │ │ │ @@ -185,14 +189,18 @@ │ │ │ │ │ typed. │ │ │ │ │ ************ aall__iinnssttaallll__kkeeyybbooaarrdd ************ │ │ │ │ │ bool al_install_keyboard(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Install a keyboard driver. Returns true if successful. If a driver was already │ │ │ │ │ installed, nothing happens and true is returned. │ │ │ │ │ See also: _a_l___u_n_i_n_s_t_a_l_l___k_e_y_b_o_a_r_d, _a_l___i_s___k_e_y_b_o_a_r_d___i_n_s_t_a_l_l_e_d │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_3_d_._c_p_p │ │ │ │ │ + * _e_x___k_e_y_b_o_a_r_d___f_o_c_u_s_._c │ │ │ │ │ + * _e_x___m_o_u_s_e___f_o_c_u_s_._c │ │ │ │ │ ************ aall__iiss__kkeeyybbooaarrdd__iinnssttaalllleedd ************ │ │ │ │ │ bool al_is_keyboard_installed(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true if _a_l___i_n_s_t_a_l_l___k_e_y_b_o_a_r_d was called successfully. │ │ │ │ │ ************ aall__uunniinnssttaallll__kkeeyybbooaarrdd ************ │ │ │ │ │ void al_uninstall_keyboard(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ @@ -202,14 +210,18 @@ │ │ │ │ │ See also: _a_l___i_n_s_t_a_l_l___k_e_y_b_o_a_r_d │ │ │ │ │ ************ aall__ggeett__kkeeyybbooaarrdd__ssttaattee ************ │ │ │ │ │ void al_get_keyboard_state(ALLEGRO_KEYBOARD_STATE *ret_state) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Save the state of the keyboard specified at the time the function is called │ │ │ │ │ into the structure pointed to by rreett__ssttaattee. │ │ │ │ │ See also: _a_l___k_e_y___d_o_w_n, _a_l___c_l_e_a_r___k_e_y_b_o_a_r_d___s_t_a_t_e, _A_L_L_E_G_R_O___K_E_Y_B_O_A_R_D___S_T_A_T_E │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_3_d_._c_p_p │ │ │ │ │ + * _e_x___k_e_y_b_o_a_r_d___f_o_c_u_s_._c │ │ │ │ │ + * _e_x___m_o_u_s_e___f_o_c_u_s_._c │ │ │ │ │ ************ aall__cclleeaarr__kkeeyybbooaarrdd__ssttaattee ************ │ │ │ │ │ void al_clear_keyboard_state(ALLEGRO_DISPLAY *display) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Clear the state of the keyboard, emitting _A_L_L_E_G_R_O___E_V_E_N_T___K_E_Y___U_P for each │ │ │ │ │ currently pressed key. The given display is regarded as the one which had the │ │ │ │ │ keyboard focus when the event occurred. In case display is NULL no event is │ │ │ │ │ emitted. For most keyboard drivers Allegro maintains its own state of the │ │ │ │ │ @@ -217,23 +229,31 @@ │ │ │ │ │ intended to remedy such situation by resetting Allegro’s keyboard state to a │ │ │ │ │ known default (no key pressed). This is particularly useful in response to │ │ │ │ │ _A_L_L_E_G_R_O___E_V_E_N_T___D_I_S_P_L_A_Y___S_W_I_T_C_H___O_U_T events. │ │ │ │ │ See also: _a_l___g_e_t___k_e_y_b_o_a_r_d___s_t_a_t_e, _A_L_L_E_G_R_O___K_E_Y_B_O_A_R_D___S_T_A_T_E │ │ │ │ │ Since: 5.2.3 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: This is a new feature and the exact semantics are still │ │ │ │ │ being decided upon. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___k_e_y_b_o_a_r_d___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__kkeeyy__ddoowwnn ************ │ │ │ │ │ bool al_key_down(const ALLEGRO_KEYBOARD_STATE *state, int keycode) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return true if the key specified was held down in the state specified. │ │ │ │ │ See also: _A_L_L_E_G_R_O___K_E_Y_B_O_A_R_D___S_T_A_T_E │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_3_d_._c_p_p │ │ │ │ │ + * _e_x___k_e_y_b_o_a_r_d___f_o_c_u_s_._c │ │ │ │ │ + * _e_x___m_o_u_s_e___f_o_c_u_s_._c │ │ │ │ │ ************ aall__kkeeyyccooddee__ttoo__nnaammee ************ │ │ │ │ │ const char *al_keycode_to_name(int keycode) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Converts the given keycode to a description of the key. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___k_e_y_b_o_a_r_d___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__ccaann__sseett__kkeeyybbooaarrdd__lleeddss ************ │ │ │ │ │ bool al_can_set_keyboard_leds(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true if setting the keyboard LED indicators is available. │ │ │ │ │ Since: 5.2.9 │ │ │ │ │ See also: _a_l___s_e_t___k_e_y_b_o_a_r_d___l_e_d_s │ │ │ │ │ ************ aall__sseett__kkeeyybbooaarrdd__lleeddss ************ │ │ │ │ │ @@ -247,8 +267,12 @@ │ │ │ │ │ See also: _a_l___c_a_n___s_e_t___k_e_y_b_o_a_r_d___l_e_d_s │ │ │ │ │ ************ aall__ggeett__kkeeyybbooaarrdd__eevveenntt__ssoouurrccee ************ │ │ │ │ │ ALLEGRO_EVENT_SOURCE *al_get_keyboard_event_source(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Retrieve the keyboard event source. All _k_e_y_b_o_a_r_d_ _e_v_e_n_t_s are generated by this │ │ │ │ │ event source. │ │ │ │ │ Returns NULL if the keyboard subsystem was not installed. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___k_e_y_b_o_a_r_d___e_v_e_n_t_s_._c │ │ │ │ │ + * _e_x___o_p_e_n_g_l_._c │ │ │ │ │ + * _e_x___w_i_n_f_u_l_l_._c │ │ │ │ │ Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/memfile.html │ │ │ │ @@ -196,14 +196,19 @@ │ │ │ │ Regardless of the mode, the file always opens at position 0. The file │ │ │ │ size is fixed and cannot be expanded. The file is always read │ │ │ │ from/written to in binary mode, which means that no newline translation │ │ │ │ is performed.

      │ │ │ │

      It should be closed with al_fclose. │ │ │ │ After the file is closed, you are responsible for freeing the memory (if │ │ │ │ needed).

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_get_allegro_memfile_version

      │ │ │ │ 
      uint32_t al_get_allegro_memfile_version(void)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Returns the (compiled) version of the addon, in the same format as │ │ │ │

      This is a macro.

      │ │ │ │

      See also: al_free, al_realloc, al_calloc, al_malloc_with_context, al_set_memory_interface

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_free

      │ │ │ │ 
      #define al_free(p) \
│ │ │ │     (al_free_with_context((p), __LINE__, __FILE__, __func__))
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Like free() in the C standard library, but the implementation may be │ │ │ │ @@ -218,91 +225,110 @@ │ │ │ │

      Additionally, on Windows, a memory block allocated by one DLL must be │ │ │ │ freed from the same DLL. In the few places where an Allegro function │ │ │ │ returns a pointer that must be freed, you must use al_free for portability to Windows.

      │ │ │ │

      This is a macro.

      │ │ │ │

      See also: al_malloc, al_free_with_context

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_realloc

      │ │ │ │ -
      #define al_realloc(p, n) \
      │ │ │ │ +
      #define al_realloc(p, n) \
│ │ │ │ +   (al_realloc_with_context((p), (n), __LINE__, __FILE__, __func__))
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Like realloc() in the C standard library, but the implementation may │ │ │ │ be overridden.

      │ │ │ │

      This is a macro.

      │ │ │ │

      See also: al_malloc, al_realloc_with_context

      │ │ │ │

      al_calloc

      │ │ │ │ -

      Source Code

      │ │ │ │ +
      #define al_calloc(c, n) \
│ │ │ │ +   (al_calloc_with_context((c), (n), __LINE__, __FILE__, __func__))
      │ │ │ │ +

      Source │ │ │ │ +Code

      │ │ │ │

      Like calloc() in the C standard library, but the implementation may │ │ │ │ be overridden.

      │ │ │ │

      This is a macro.

      │ │ │ │

      See also: al_malloc, al_calloc_with_context

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_malloc_with_context

      │ │ │ │ -
      void *al_malloc_with_context(size_t n,
│ │ │ │ -   int line, const char *file, const char *func)
      │ │ │ │ +
      void *al_malloc_with_context(size_t n,
│ │ │ │ +   int line, const char *file, const char *func)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      This calls malloc() from the Allegro library (this matters on │ │ │ │ Windows), unless overridden with al_set_memory_interface,

      │ │ │ │

      Generally you should use the al_malloc macro.

      │ │ │ │

      al_free_with_context

      │ │ │ │ -
      void al_free_with_context(void *ptr,
│ │ │ │ -   int line, const char *file, const char *func)
      │ │ │ │ +
      void al_free_with_context(void *ptr,
│ │ │ │ +   int line, const char *file, const char *func)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      This calls free() from the Allegro library (this matters on Windows), │ │ │ │ unless overridden with al_set_memory_interface.

      │ │ │ │

      Generally you should use the al_free macro.

      │ │ │ │

      al_realloc_with_context

      │ │ │ │ -
      void *al_realloc_with_context(void *ptr, size_t n,
│ │ │ │ -   int line, const char *file, const char *func)
      │ │ │ │ +
      void *al_realloc_with_context(void *ptr, size_t n,
│ │ │ │ +   int line, const char *file, const char *func)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      This calls realloc() from the Allegro library (this matters on │ │ │ │ Windows), unless overridden with al_set_memory_interface,

      │ │ │ │

      Generally you should use the al_realloc macro.

      │ │ │ │

      al_calloc_with_context

      │ │ │ │ -
      void *al_calloc_with_context(size_t count, size_t n,
│ │ │ │ -   int line, const char *file, const char *func)
      │ │ │ │ +
      void *al_calloc_with_context(size_t count, size_t n,
│ │ │ │ +   int line, const char *file, const char *func)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      This calls calloc() from the Allegro library (this matters on │ │ │ │ Windows), unless overridden with al_set_memory_interface,

      │ │ │ │

      Generally you should use the al_calloc macro.

      │ │ │ │

      ALLEGRO_MEMORY_INTERFACE

      │ │ │ │ -
      typedef struct ALLEGRO_MEMORY_INTERFACE ALLEGRO_MEMORY_INTERFACE;
      │ │ │ │ +
      typedef struct ALLEGRO_MEMORY_INTERFACE ALLEGRO_MEMORY_INTERFACE;
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      This structure has the following fields.

      │ │ │ │ -
      void *(*mi_malloc)(size_t n, int line, const char *file, const char *func);
│ │ │ │ -void (*mi_free)(void *ptr, int line, const char *file, const char *func);
│ │ │ │ -void *(*mi_realloc)(void *ptr, size_t n, int line, const char *file,
│ │ │ │ -                    const char *func);
│ │ │ │ -void *(*mi_calloc)(size_t count, size_t n, int line, const char *file,
│ │ │ │ -                   const char *func);
      │ │ │ │ +
      void *(*mi_malloc)(size_t n, int line, const char *file, const char *func);
│ │ │ │ +void (*mi_free)(void *ptr, int line, const char *file, const char *func);
│ │ │ │ +void *(*mi_realloc)(void *ptr, size_t n, int line, const char *file,
│ │ │ │ +                    const char *func);
│ │ │ │ +void *(*mi_calloc)(size_t count, size_t n, int line, const char *file,
│ │ │ │ +                   const char *func);
      │ │ │ │

      See also: al_set_memory_interface

      │ │ │ │

      al_set_memory_interface

      │ │ │ │ -
      void al_set_memory_interface(ALLEGRO_MEMORY_INTERFACE *memory_interface)
      │ │ │ │ +
      void al_set_memory_interface(ALLEGRO_MEMORY_INTERFACE *memory_interface)
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      Override the memory management functions with implementations of al_malloc_with_context, al_free_with_context, al_realloc_with_context │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -60,38 +60,50 @@ │ │ │ │ │ (al_malloc_with_context((n), __LINE__, __FILE__, __func__)) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like malloc() in the C standard library, but the implementation may be │ │ │ │ │ overridden. │ │ │ │ │ This is a macro. │ │ │ │ │ See also: _a_l___f_r_e_e, _a_l___r_e_a_l_l_o_c, _a_l___c_a_l_l_o_c, _a_l___m_a_l_l_o_c___w_i_t_h___c_o_n_t_e_x_t, │ │ │ │ │ _a_l___s_e_t___m_e_m_o_r_y___i_n_t_e_r_f_a_c_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___a_u_d_i_o___t_i_m_e_r_._c │ │ │ │ │ + * _e_x___v_e_r_t_e_x___b_u_f_f_e_r_._c │ │ │ │ │ ************ aall__ffrreeee ************ │ │ │ │ │ #define al_free(p) \ │ │ │ │ │ (al_free_with_context((p), __LINE__, __FILE__, __func__)) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like free() in the C standard library, but the implementation may be │ │ │ │ │ overridden. │ │ │ │ │ Additionally, on Windows, a memory block allocated by one DLL must be freed │ │ │ │ │ from the same DLL. In the few places where an Allegro function returns a │ │ │ │ │ pointer that must be freed, you must use _a_l___f_r_e_e for portability to Windows. │ │ │ │ │ This is a macro. │ │ │ │ │ See also: _a_l___m_a_l_l_o_c, _a_l___f_r_e_e___w_i_t_h___c_o_n_t_e_x_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___c_l_i_p_b_o_a_r_d_._c │ │ │ │ │ + * _e_x___d_r_a_g___a_n_d___d_r_o_p_._c │ │ │ │ │ + * _e_x___r_e_c_o_r_d___n_a_m_e_._c │ │ │ │ │ ************ aall__rreeaalllloocc ************ │ │ │ │ │ #define al_realloc(p, n) \ │ │ │ │ │ + (al_realloc_with_context((p), (n), __LINE__, __FILE__, __func__)) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like realloc() in the C standard library, but the implementation may be │ │ │ │ │ overridden. │ │ │ │ │ This is a macro. │ │ │ │ │ See also: _a_l___m_a_l_l_o_c, _a_l___r_e_a_l_l_o_c___w_i_t_h___c_o_n_t_e_x_t │ │ │ │ │ ************ aall__ccaalllloocc ************ │ │ │ │ │ -Source Code │ │ │ │ │ +#define al_calloc(c, n) \ │ │ │ │ │ + (al_calloc_with_context((c), (n), __LINE__, __FILE__, __func__)) │ │ │ │ │ +_S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like calloc() in the C standard library, but the implementation may be │ │ │ │ │ overridden. │ │ │ │ │ This is a macro. │ │ │ │ │ See also: _a_l___m_a_l_l_o_c, _a_l___c_a_l_l_o_c___w_i_t_h___c_o_n_t_e_x_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___r_e_c_o_r_d___n_a_m_e_._c │ │ │ │ │ ************ aall__mmaalllloocc__wwiitthh__ccoonntteexxtt ************ │ │ │ │ │ void *al_malloc_with_context(size_t n, │ │ │ │ │ int line, const char *file, const char *func) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This calls malloc() from the Allegro library (this matters on Windows), unless │ │ │ │ │ overridden with _a_l___s_e_t___m_e_m_o_r_y___i_n_t_e_r_f_a_c_e, │ │ │ │ │ Generally you should use the _a_l___m_a_l_l_o_c macro. │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/misc.html │ │ │ │ @@ -182,14 +182,23 @@ │ │ │ │

      ALLEGRO_PI

      │ │ │ │ 
      #define ALLEGRO_PI        3.14159265358979323846
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      C99 compilers have no predefined value like M_PI for the constant π, │ │ │ │ but you can use this one instead.

      │ │ │ │ +

      Examples:

      │ │ │ │ + │ │ │ │

      al_run_main

      │ │ │ │ 
      int al_run_main(int argc, char **argv, int (*user_main)(int, char **))
      │ │ │ │

      Source │ │ │ │ Code

      │ │ │ │

      This function is useful in cases where you don’t have a main() │ │ │ │ function but want to run Allegro (mostly useful in a wrapper library). │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -48,14 +48,18 @@ │ │ │ │ │ These functions are declared in the main Allegro header file: │ │ │ │ │ #include │ │ │ │ │ ************ AALLLLEEGGRROO__PPII ************ │ │ │ │ │ #define ALLEGRO_PI 3.14159265358979323846 │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ C99 compilers have no predefined value like M_PI for the constant π, but you │ │ │ │ │ can use this one instead. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___c_o_n_v_e_r_t_._c │ │ │ │ │ + * _e_x___o_p_e_n_g_l_._c │ │ │ │ │ + * _e_x___b_l_e_n_d___b_e_n_c_h_._c │ │ │ │ │ ************ aall__rruunn__mmaaiinn ************ │ │ │ │ │ int al_run_main(int argc, char **argv, int (*user_main)(int, char **)) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This function is useful in cases where you don’t have a main() function but │ │ │ │ │ want to run Allegro (mostly useful in a wrapper library). Under Windows and │ │ │ │ │ Linux this is no problem because you simply can call _a_l___i_n_s_t_a_l_l___s_y_s_t_e_m. But │ │ │ │ │ some other system (like OSX) don’t allow calling _a_l___i_n_s_t_a_l_l___s_y_s_t_e_m in the main │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/monitor.html │ │ │ │ @@ -184,72 +184,107 @@ │ │ │ │

    • al_get_monitor_refresh_rate
      • │ │ │ │
    │ │ │ │ │ │ │ │

    These functions are declared in the main Allegro header file:

    │ │ │ │ 
     #include <allegro5/allegro.h>
    │ │ │ │

    ALLEGRO_MONITOR_INFO

    │ │ │ │ -

    Source Code

    │ │ │ │ +
    typedef struct ALLEGRO_MONITOR_INFO
    │ │ │ │ +

    Source │ │ │ │ +Code

    │ │ │ │

    Describes a monitor’s size and position relative to other monitors. │ │ │ │ x1, y1 will be 0, 0 on the primary display. Other monitors can have │ │ │ │ negative values if they are to the left or above the primary display. │ │ │ │ x2, y2 are the coordinates one beyond the bottom right pixel, so that │ │ │ │ x2-x1 gives the width and y2-y1 gives the height of the display.

    │ │ │ │ -
    typedef struct ALLEGRO_MONITOR_INFO
│ │ │ │ -{
│ │ │ │ -   int x1;
│ │ │ │ -   int y1;
│ │ │ │ -   int x2;
│ │ │ │ -   int y2;
│ │ │ │ -} ALLEGRO_MONITOR_INFO;
    │ │ │ │ +
    typedef struct ALLEGRO_MONITOR_INFO
│ │ │ │ +{
│ │ │ │ +   int x1;
│ │ │ │ +   int y1;
│ │ │ │ +   int x2;
│ │ │ │ +   int y2;
│ │ │ │ +} ALLEGRO_MONITOR_INFO;
    │ │ │ │

    See also: al_get_monitor_info

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_monitor_info

    │ │ │ │ -
    bool al_get_monitor_info(int adapter, ALLEGRO_MONITOR_INFO *info)
    │ │ │ │ +
    bool al_get_monitor_info(int adapter, ALLEGRO_MONITOR_INFO *info)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Get information about a monitor’s position on the desktop. adapter is │ │ │ │ a number from 0 to al_get_num_video_adapters()-1.

    │ │ │ │

    On Windows, use al_set_new_display_flags │ │ │ │ to switch between Direct3D and OpenGL backends, which will often have │ │ │ │ different adapters available.

    │ │ │ │

    Returns true on success, false on │ │ │ │ failure.

    │ │ │ │

    See also: ALLEGRO_MONITOR_INFO, al_get_num_video_adapters

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_monitor_dpi

    │ │ │ │ -
    int al_get_monitor_dpi(int adapter)
    │ │ │ │ +
    int al_get_monitor_dpi(int adapter)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Get the dots per inch of a monitor attached to the display │ │ │ │ adapter.

    │ │ │ │

    Since: 5.2.5

    │ │ │ │

    See also: al_get_num_video_adapters

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_num_video_adapters

    │ │ │ │ -
    int al_get_num_video_adapters(void)
    │ │ │ │ +
    int al_get_num_video_adapters(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Get the number of video “adapters” attached to the computer. Each │ │ │ │ video card attached to the computer counts as one or more adapters. An │ │ │ │ adapter is thus really a video port that can have a monitor connected to │ │ │ │ it.

    │ │ │ │

    On Windows, use al_set_new_display_flags │ │ │ │ to switch between Direct3D and OpenGL backends, which will often have │ │ │ │ different adapters available.

    │ │ │ │

    See also: al_get_monitor_info

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_monitor_refresh_rate

    │ │ │ │ -
    int al_get_monitor_refresh_rate(int adapter)
    │ │ │ │ +
    int al_get_monitor_refresh_rate(int adapter)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the current refresh rate of a monitor attached to the display │ │ │ │ adapter.

    │ │ │ │

    Since: 5.2.6

    │ │ │ │
    │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -47,52 +47,67 @@ │ │ │ │ │ * _a_l___g_e_t___m_o_n_i_t_o_r___i_n_f_o │ │ │ │ │ * _a_l___g_e_t___m_o_n_i_t_o_r___d_p_i │ │ │ │ │ * _a_l___g_e_t___n_u_m___v_i_d_e_o___a_d_a_p_t_e_r_s │ │ │ │ │ * _a_l___g_e_t___m_o_n_i_t_o_r___r_e_f_r_e_s_h___r_a_t_e │ │ │ │ │ These functions are declared in the main Allegro header file: │ │ │ │ │ #include │ │ │ │ │ ************ AALLLLEEGGRROO__MMOONNIITTOORR__IINNFFOO ************ │ │ │ │ │ -Source Code │ │ │ │ │ +typedef struct ALLEGRO_MONITOR_INFO │ │ │ │ │ +_S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Describes a monitor’s size and position relative to other monitors. x1, y1 will │ │ │ │ │ be 0, 0 on the primary display. Other monitors can have negative values if they │ │ │ │ │ are to the left or above the primary display. x2, y2 are the coordinates one │ │ │ │ │ beyond the bottom right pixel, so that x2-x1 gives the width and y2-y1 gives │ │ │ │ │ the height of the display. │ │ │ │ │ typedef struct ALLEGRO_MONITOR_INFO │ │ │ │ │ { │ │ │ │ │ int x1; │ │ │ │ │ int y1; │ │ │ │ │ int x2; │ │ │ │ │ int y2; │ │ │ │ │ } ALLEGRO_MONITOR_INFO; │ │ │ │ │ See also: _a_l___g_e_t___m_o_n_i_t_o_r___i_n_f_o │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_n_i_t_o_r_i_n_f_o_._c │ │ │ │ │ + * _e_x___d_r_a_g___a_n_d___d_r_o_p_._c │ │ │ │ │ + * _e_x___w_i_n_d_o_w_s_._c │ │ │ │ │ ************ aall__ggeett__mmoonniittoorr__iinnffoo ************ │ │ │ │ │ bool al_get_monitor_info(int adapter, ALLEGRO_MONITOR_INFO *info) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get information about a monitor’s position on the desktop. adapter is a number │ │ │ │ │ from 0 to al_get_num_video_adapters()-1. │ │ │ │ │ On Windows, use _a_l___s_e_t___n_e_w___d_i_s_p_l_a_y___f_l_a_g_s to switch between Direct3D and OpenGL │ │ │ │ │ backends, which will often have different adapters available. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _A_L_L_E_G_R_O___M_O_N_I_T_O_R___I_N_F_O, _a_l___g_e_t___n_u_m___v_i_d_e_o___a_d_a_p_t_e_r_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_n_i_t_o_r_i_n_f_o_._c │ │ │ │ │ + * _e_x___d_r_a_g___a_n_d___d_r_o_p_._c │ │ │ │ │ + * _e_x___w_i_n_d_o_w_s_._c │ │ │ │ │ ************ aall__ggeett__mmoonniittoorr__ddppii ************ │ │ │ │ │ int al_get_monitor_dpi(int adapter) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get the dots per inch of a monitor attached to the display adapter. │ │ │ │ │ Since: 5.2.5 │ │ │ │ │ See also: _a_l___g_e_t___n_u_m___v_i_d_e_o___a_d_a_p_t_e_r_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_n_i_t_o_r_i_n_f_o_._c │ │ │ │ │ ************ aall__ggeett__nnuumm__vviiddeeoo__aaddaapptteerrss ************ │ │ │ │ │ int al_get_num_video_adapters(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get the number of video “adapters” attached to the computer. Each video card │ │ │ │ │ attached to the computer counts as one or more adapters. An adapter is thus │ │ │ │ │ really a video port that can have a monitor connected to it. │ │ │ │ │ On Windows, use _a_l___s_e_t___n_e_w___d_i_s_p_l_a_y___f_l_a_g_s to switch between Direct3D and OpenGL │ │ │ │ │ backends, which will often have different adapters available. │ │ │ │ │ See also: _a_l___g_e_t___m_o_n_i_t_o_r___i_n_f_o │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_n_i_t_o_r_i_n_f_o_._c │ │ │ │ │ + * _e_x___w_i_n_f_u_l_l_._c │ │ │ │ │ + * _e_x___d_u_a_l_i_e_s_._c │ │ │ │ │ ************ aall__ggeett__mmoonniittoorr__rreeffrreesshh__rraattee ************ │ │ │ │ │ int al_get_monitor_refresh_rate(int adapter) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the current refresh rate of a monitor attached to the display adapter. │ │ │ │ │ Since: 5.2.6 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: This is an experimental feature and currently only │ │ │ │ │ works on Windows. │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/mouse.html │ │ │ │ @@ -231,15 +231,18 @@ │ │ │ │ id="toc-al_ungrab_mouse">al_ungrab_mouse │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │

    These functions are declared in the main Allegro header file:

    │ │ │ │ 
     #include <allegro5/allegro.h>
    │ │ │ │

    ALLEGRO_MOUSE_STATE

    │ │ │ │ -

    Source Code

    │ │ │ │ +
    typedef struct ALLEGRO_MOUSE_STATE ALLEGRO_MOUSE_STATE;
    │ │ │ │ +

    Source │ │ │ │ +Code

    │ │ │ │

    Public fields (read only):

    │ │ │ │
      │ │ │ │

    • x - mouse x position

      • │ │ │ │

    • y - mouse y position

      • │ │ │ │

    • w, z - mouse wheel position (2D ‘ball’)

      • │ │ │ │

    • buttons - mouse buttons bitfield

      │ │ │ │

      The zeroth bit is set if the primary mouse button is held down, the │ │ │ │ @@ -248,112 +251,144 @@ │ │ │ │

    • pressure - pressure, ranging from 0.0 to │ │ │ │ 1.0

      • │ │ │ │
    │ │ │ │

    See also: al_get_mouse_state, al_get_mouse_state_axis, │ │ │ │ al_mouse_button_down

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Mouse button constants

    │ │ │ │

    Unlike other indexes, the first mouse button is numbered 1 when │ │ │ │ returned in the event.mouse.button field of │ │ │ │ ALLEGRO_EVENT_MOUSE_BUTTON_UP and ALLEGRO_EVENT_MOUSE_BUTTON_DOWN │ │ │ │ events.

    │ │ │ │

    As a convenience, the following ALLEGRO_MOUSE_BUTTON constants are │ │ │ │ provided below. However, depending on the hardware there may be more or │ │ │ │ fewer mouse buttons. You can check al_get_mouse_num_buttons │ │ │ │ if you want to be sure.

    │ │ │ │ -
    typedef enum ALLEGRO_MOUSE_BUTTON
│ │ │ │ -{
│ │ │ │ -   ALLEGRO_MOUSE_BUTTON_LEFT = 1,
│ │ │ │ -   ALLEGRO_MOUSE_BUTTON_RIGHT = 2,
│ │ │ │ -   ALLEGRO_MOUSE_BUTTON_MIDDLE = 3
│ │ │ │ -} ALLEGRO_MOUSE_BUTTON;
    │ │ │ │ +
    typedef enum ALLEGRO_MOUSE_BUTTON
│ │ │ │ +{
│ │ │ │ +   ALLEGRO_MOUSE_BUTTON_LEFT = 1,
│ │ │ │ +   ALLEGRO_MOUSE_BUTTON_RIGHT = 2,
│ │ │ │ +   ALLEGRO_MOUSE_BUTTON_MIDDLE = 3
│ │ │ │ +} ALLEGRO_MOUSE_BUTTON;
    │ │ │ │

    Since: 5.2.10

    │ │ │ │

    See also: al_get_mouse_num_buttons, │ │ │ │ al_mouse_button_down

    │ │ │ │

    al_install_mouse

    │ │ │ │ -
    bool al_install_mouse(void)
    │ │ │ │ +
    bool al_install_mouse(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Install a mouse driver.

    │ │ │ │

    Returns true if successful. If a driver was already installed, │ │ │ │ nothing happens and true is returned.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_is_mouse_installed

    │ │ │ │ -
    bool al_is_mouse_installed(void)
    │ │ │ │ +
    bool al_is_mouse_installed(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true if al_install_mouse was called │ │ │ │ successfully.

    │ │ │ │

    al_uninstall_mouse

    │ │ │ │ -
    void al_uninstall_mouse(void)
    │ │ │ │ +
    void al_uninstall_mouse(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Uninstalls the active mouse driver, if any. This will automatically │ │ │ │ unregister the mouse event source with any event queues.

    │ │ │ │

    This function is automatically called when Allegro is shut down.

    │ │ │ │

    al_get_mouse_num_axes

    │ │ │ │ -
    unsigned int al_get_mouse_num_axes(void)
    │ │ │ │ +
    unsigned int al_get_mouse_num_axes(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the number of axes on the mouse. The first axis is 0.

    │ │ │ │

    See also: al_get_mouse_num_buttons

    │ │ │ │

    al_get_mouse_num_buttons

    │ │ │ │ -
    unsigned int al_get_mouse_num_buttons(void)
    │ │ │ │ +
    unsigned int al_get_mouse_num_buttons(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the number of buttons on the mouse. The first button is 1.

    │ │ │ │

    See also: al_get_mouse_num_axes

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_mouse_state

    │ │ │ │ -
    void al_get_mouse_state(ALLEGRO_MOUSE_STATE *ret_state)
    │ │ │ │ +
    void al_get_mouse_state(ALLEGRO_MOUSE_STATE *ret_state)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Save the state of the mouse specified at the time the function is │ │ │ │ called into the given structure.

    │ │ │ │

    Example:

    │ │ │ │ -
    ALLEGRO_MOUSE_STATE state;
│ │ │ │ -
│ │ │ │ -al_get_mouse_state(&state);
│ │ │ │ -if (state.buttons & 1) {
│ │ │ │ -    /* Primary (e.g. left) mouse button is held. */
│ │ │ │ -    printf("Mouse position: (%d, %d)\n", state.x, state.y);
│ │ │ │ -}
│ │ │ │ -if (state.buttons & 2) {
│ │ │ │ -    /* Secondary (e.g. right) mouse button is held. */
│ │ │ │ -}
│ │ │ │ -if (state.buttons & 4) {
│ │ │ │ -    /* Tertiary (e.g. middle) mouse button is held. */
│ │ │ │ -}
    │ │ │ │ +
    ALLEGRO_MOUSE_STATE state;
│ │ │ │ +
│ │ │ │ +al_get_mouse_state(&state);
│ │ │ │ +if (state.buttons & 1) {
│ │ │ │ +    /* Primary (e.g. left) mouse button is held. */
│ │ │ │ +    printf("Mouse position: (%d, %d)\n", state.x, state.y);
│ │ │ │ +}
│ │ │ │ +if (state.buttons & 2) {
│ │ │ │ +    /* Secondary (e.g. right) mouse button is held. */
│ │ │ │ +}
│ │ │ │ +if (state.buttons & 4) {
│ │ │ │ +    /* Tertiary (e.g. middle) mouse button is held. */
│ │ │ │ +}
    │ │ │ │

    See also: ALLEGRO_MOUSE_STATE, al_get_mouse_state_axis, │ │ │ │ al_mouse_button_down

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_mouse_state_axis

    │ │ │ │ -
    int al_get_mouse_state_axis(const ALLEGRO_MOUSE_STATE *state, int axis)
    │ │ │ │ +
    int al_get_mouse_state_axis(const ALLEGRO_MOUSE_STATE *state, int axis)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Extract the mouse axis value from the saved state. The axes are │ │ │ │ numbered from 0, in this order: x-axis, y-axis, z-axis, w-axis.

    │ │ │ │

    See also: ALLEGRO_MOUSE_STATE, al_get_mouse_state, al_mouse_button_down

    │ │ │ │

    al_mouse_button_down

    │ │ │ │ -
    bool al_mouse_button_down(const ALLEGRO_MOUSE_STATE *state, int button)
    │ │ │ │ +
    bool al_mouse_button_down(const ALLEGRO_MOUSE_STATE *state, int button)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return true if the mouse button specified was held down in the state │ │ │ │ specified.

    │ │ │ │

    Unlike most things, the first mouse button is numbered 1. As a │ │ │ │ convenience, the constants ALLEGRO_MOUSE_BUTTON_LEFT, │ │ │ │ @@ -362,142 +397,188 @@ │ │ │ │ buttons. You can check al_get_mouse_num_buttons │ │ │ │ if you want to be sure.

    │ │ │ │

    See also: ALLEGRO_MOUSE_STATE, al_get_mouse_state, al_get_mouse_state_axis

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_mouse_xy

    │ │ │ │ -
    bool al_set_mouse_xy(ALLEGRO_DISPLAY *display, int x, int y)
    │ │ │ │ +
    bool al_set_mouse_xy(ALLEGRO_DISPLAY *display, int x, int y)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Try to position the mouse at the given coordinates on the given │ │ │ │ display. The mouse movement resulting from a successful move will │ │ │ │ generate an ALLEGRO_EVENT_MOUSE_WARPED │ │ │ │ event.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: al_set_mouse_z, al_set_mouse_w

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_mouse_z

    │ │ │ │ -
    bool al_set_mouse_z(int z)
    │ │ │ │ +
    bool al_set_mouse_z(int z)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Set the mouse wheel position to the given value.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: al_set_mouse_w

    │ │ │ │

    al_set_mouse_w

    │ │ │ │ -
    bool al_set_mouse_w(int w)
    │ │ │ │ +
    bool al_set_mouse_w(int w)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Set the second mouse wheel position to the given value.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: al_set_mouse_z

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_mouse_axis

    │ │ │ │ -
    bool al_set_mouse_axis(int which, int value)
    │ │ │ │ +
    bool al_set_mouse_axis(int which, int value)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Set the given mouse axis to the given value.

    │ │ │ │

    The axis number must not be 0 or 1, which are the X and Y axes. Use │ │ │ │ al_set_mouse_xy for that.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: al_set_mouse_xy, │ │ │ │ al_set_mouse_z, al_set_mouse_w

    │ │ │ │

    al_get_mouse_event_source

    │ │ │ │ -
    ALLEGRO_EVENT_SOURCE *al_get_mouse_event_source(void)
    │ │ │ │ +
    ALLEGRO_EVENT_SOURCE *al_get_mouse_event_source(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Retrieve the mouse event source. All mouse events are │ │ │ │ generated by this event source.

    │ │ │ │

    Returns NULL if the mouse subsystem was not installed.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_mouse_wheel_precision

    │ │ │ │ -
    void al_set_mouse_wheel_precision(int precision)
    │ │ │ │ +
    void al_set_mouse_wheel_precision(int precision)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Sets the precision of the mouse wheel (the z and w coordinates). This │ │ │ │ precision manifests itself as a multiplier on the dz and │ │ │ │ dw fields in mouse events. It also affects the │ │ │ │ z and w fields of events and ALLEGRO_MOUSE_STATE, but not │ │ │ │ in a simple way if you alter the precision often, so it is suggested to │ │ │ │ reset those axes to 0 when you change precision. Setting this to a high │ │ │ │ value allows you to detect small changes in those two axes for some high │ │ │ │ precision mice. A flexible way of using this precision is to set it to a │ │ │ │ high value (120 is likely sufficient for most, if not all, mice) and use │ │ │ │ a floating point dz and dw like so:

    │ │ │ │ -
    al_set_mouse_wheel_precision(120);
│ │ │ │ -
│ │ │ │ -ALLEGRO_EVENT event;
│ │ │ │ -al_wait_for_event(event_queue, &event);
│ │ │ │ -if (event.type == ALLEGRO_EVENT_MOUSE_AXES) {
│ │ │ │ -  double dz = (double)event.mouse.dz / al_get_mouse_wheel_precision();
│ │ │ │ -  /* Use dz in some way... */
│ │ │ │ -}
    │ │ │ │ +
    al_set_mouse_wheel_precision(120);
│ │ │ │ +
│ │ │ │ +ALLEGRO_EVENT event;
│ │ │ │ +al_wait_for_event(event_queue, &event);
│ │ │ │ +if (event.type == ALLEGRO_EVENT_MOUSE_AXES) {
│ │ │ │ +  double dz = (double)event.mouse.dz / al_get_mouse_wheel_precision();
│ │ │ │ +  /* Use dz in some way... */
│ │ │ │ +}
    │ │ │ │

    Precision is set to 1 by default. It is impossible to set it to a │ │ │ │ lower precision than that.

    │ │ │ │

    Since: 5.1.10

    │ │ │ │

    See also: al_get_mouse_wheel_precision

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_mouse_wheel_precision

    │ │ │ │ -
    int al_get_mouse_wheel_precision(void)
    │ │ │ │ +
    int al_get_mouse_wheel_precision(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Gets the precision of the mouse wheel (the z and w coordinates).

    │ │ │ │

    Since: 5.1.10

    │ │ │ │

    See also: al_set_mouse_wheel_precision

    │ │ │ │

    Mouse cursors

    │ │ │ │

    al_create_mouse_cursor

    │ │ │ │ -
    ALLEGRO_MOUSE_CURSOR *al_create_mouse_cursor(ALLEGRO_BITMAP *bmp,
│ │ │ │ -   int x_focus, int y_focus)
    │ │ │ │ +
    ALLEGRO_MOUSE_CURSOR *al_create_mouse_cursor(ALLEGRO_BITMAP *bmp,
│ │ │ │ +   int x_focus, int y_focus)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Create a mouse cursor from the bitmap provided. x_focus │ │ │ │ and y_focus describe the bit of the cursor that will │ │ │ │ represent the actual mouse position.

    │ │ │ │

    Returns a pointer to the cursor on success, or NULL on failure.

    │ │ │ │

    See also: al_set_mouse_cursor, al_destroy_mouse_cursor

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_destroy_mouse_cursor

    │ │ │ │ -
    void al_destroy_mouse_cursor(ALLEGRO_MOUSE_CURSOR *cursor)
    │ │ │ │ +
    void al_destroy_mouse_cursor(ALLEGRO_MOUSE_CURSOR *cursor)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Free the memory used by the given cursor.

    │ │ │ │

    Has no effect if cursor is NULL.

    │ │ │ │

    See also: al_create_mouse_cursor

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_mouse_cursor

    │ │ │ │ -
    bool al_set_mouse_cursor(ALLEGRO_DISPLAY *display, ALLEGRO_MOUSE_CURSOR *cursor)
    │ │ │ │ +
    bool al_set_mouse_cursor(ALLEGRO_DISPLAY *display, ALLEGRO_MOUSE_CURSOR *cursor)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Set the given mouse cursor to be the current mouse cursor for the │ │ │ │ given display.

    │ │ │ │

    If the cursor is currently ‘shown’ (as opposed to ‘hidden’) the │ │ │ │ change is immediately visible.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: al_set_system_mouse_cursor, │ │ │ │ al_show_mouse_cursor, al_hide_mouse_cursor

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_system_mouse_cursor

    │ │ │ │ -
    bool al_set_system_mouse_cursor(ALLEGRO_DISPLAY *display,
│ │ │ │ -   ALLEGRO_SYSTEM_MOUSE_CURSOR cursor_id)
    │ │ │ │ +
    bool al_set_system_mouse_cursor(ALLEGRO_DISPLAY *display,
│ │ │ │ +   ALLEGRO_SYSTEM_MOUSE_CURSOR cursor_id)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Set the given system mouse cursor to be the current mouse cursor for │ │ │ │ the given display. If the cursor is currently ‘shown’ (as opposed to │ │ │ │ ‘hidden’) the change is immediately visible.

    │ │ │ │

    If the cursor doesn’t exist on the current platform another cursor │ │ │ │ @@ -525,61 +606,87 @@ │ │ │ │

  • ALLEGRO_SYSTEM_MOUSE_CURSOR_UNAVAILABLE
    • │ │ │ │ │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: al_set_mouse_cursor, al_show_mouse_cursor, al_hide_mouse_cursor

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_can_get_mouse_cursor_position

    │ │ │ │ -
    bool al_can_get_mouse_cursor_position(void)
    │ │ │ │ +
    bool al_can_get_mouse_cursor_position(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true if getting the global mouse cursor position is │ │ │ │ available.

    │ │ │ │

    Since: 5.2.9

    │ │ │ │

    See also: al_get_mouse_cursor_position

    │ │ │ │

    al_get_mouse_cursor_position

    │ │ │ │ -
    bool al_get_mouse_cursor_position(int *ret_x, int *ret_y)
    │ │ │ │ +
    bool al_get_mouse_cursor_position(int *ret_x, int *ret_y)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    On platforms where this information is available, this function │ │ │ │ returns the global location of the mouse cursor, relative to the │ │ │ │ desktop. You should not normally use this function, as the information │ │ │ │ is not useful except for special scenarios as moving a window.

    │ │ │ │

    Returns true on success, false on failure.

    │ │ │ │

    See also: al_can_get_mouse_cursor_position

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_hide_mouse_cursor

    │ │ │ │ -
    bool al_hide_mouse_cursor(ALLEGRO_DISPLAY *display)
    │ │ │ │ +
    bool al_hide_mouse_cursor(ALLEGRO_DISPLAY *display)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Hide the mouse cursor in the given display. This has no effect on │ │ │ │ what the current mouse cursor looks like; it just makes it │ │ │ │ disappear.

    │ │ │ │

    Returns true on success (or if the cursor already was hidden), false │ │ │ │ otherwise.

    │ │ │ │

    See also: al_show_mouse_cursor

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_show_mouse_cursor

    │ │ │ │ -
    bool al_show_mouse_cursor(ALLEGRO_DISPLAY *display)
    │ │ │ │ +
    bool al_show_mouse_cursor(ALLEGRO_DISPLAY *display)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Make a mouse cursor visible in the given display.

    │ │ │ │

    Returns true if a mouse cursor is shown as a result of the call (or │ │ │ │ one already was visible), false otherwise.

    │ │ │ │

    See also: al_hide_mouse_cursor

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_grab_mouse

    │ │ │ │ -
    bool al_grab_mouse(ALLEGRO_DISPLAY *display)
    │ │ │ │ +
    bool al_grab_mouse(ALLEGRO_DISPLAY *display)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Confine the mouse cursor to the given display. The mouse cursor can │ │ │ │ only be confined to one display at a time.

    │ │ │ │

    Returns true if successful, otherwise returns false. Do not assume │ │ │ │ that the cursor will remain confined until you call │ │ │ │

    │ │ │ │

    Note: not yet implemented on Mac OS X.

    │ │ │ │
    │ │ │ │

    See also: al_ungrab_mouse

    │ │ │ │

    al_ungrab_mouse

    │ │ │ │ -
    bool al_ungrab_mouse(void)
    │ │ │ │ +
    bool al_ungrab_mouse(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Stop confining the mouse cursor to any display belonging to the │ │ │ │ program.

    │ │ │ │
    │ │ │ │

    Note: not yet implemented on Mac OS X.

    │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -70,24 +70,29 @@ │ │ │ │ │ o _a_l___h_i_d_e___m_o_u_s_e___c_u_r_s_o_r │ │ │ │ │ o _a_l___s_h_o_w___m_o_u_s_e___c_u_r_s_o_r │ │ │ │ │ o _a_l___g_r_a_b___m_o_u_s_e │ │ │ │ │ o _a_l___u_n_g_r_a_b___m_o_u_s_e │ │ │ │ │ These functions are declared in the main Allegro header file: │ │ │ │ │ #include │ │ │ │ │ ************ AALLLLEEGGRROO__MMOOUUSSEE__SSTTAATTEE ************ │ │ │ │ │ -Source Code │ │ │ │ │ +typedef struct ALLEGRO_MOUSE_STATE ALLEGRO_MOUSE_STATE; │ │ │ │ │ +_S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Public fields (read only): │ │ │ │ │ * x - mouse x position │ │ │ │ │ * y - mouse y position │ │ │ │ │ * w, z - mouse wheel position (2D ‘ball’) │ │ │ │ │ * buttons - mouse buttons bitfield │ │ │ │ │ The zeroth bit is set if the primary mouse button is held down, the first │ │ │ │ │ bit is set if the secondary mouse button is held down, and so on. │ │ │ │ │ * pressure - pressure, ranging from 0.0 to 1.0 │ │ │ │ │ See also: _a_l___g_e_t___m_o_u_s_e___s_t_a_t_e, _a_l___g_e_t___m_o_u_s_e___s_t_a_t_e___a_x_i_s, _a_l___m_o_u_s_e___b_u_t_t_o_n___d_o_w_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_u_s_e___f_o_c_u_s_._c │ │ │ │ │ + * _e_x___m_o_u_s_e_._c │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ ************ MMoouussee bbuuttttoonn ccoonnssttaannttss ************ │ │ │ │ │ Unlike other indexes, the first mouse button is numbered 1 when returned in the │ │ │ │ │ event.mouse.button field of ALLEGRO_EVENT_MOUSE_BUTTON_UP and │ │ │ │ │ ALLEGRO_EVENT_MOUSE_BUTTON_DOWN events. │ │ │ │ │ As a convenience, the following ALLEGRO_MOUSE_BUTTON constants are provided │ │ │ │ │ below. However, depending on the hardware there may be more or fewer mouse │ │ │ │ │ buttons. You can check _a_l___g_e_t___m_o_u_s_e___n_u_m___b_u_t_t_o_n_s if you want to be sure. │ │ │ │ │ @@ -101,14 +106,18 @@ │ │ │ │ │ See also: _a_l___g_e_t___m_o_u_s_e___n_u_m___b_u_t_t_o_n_s, _a_l___m_o_u_s_e___b_u_t_t_o_n___d_o_w_n │ │ │ │ │ ************ aall__iinnssttaallll__mmoouussee ************ │ │ │ │ │ bool al_install_mouse(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Install a mouse driver. │ │ │ │ │ Returns true if successful. If a driver was already installed, nothing happens │ │ │ │ │ and true is returned. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_u_s_e___f_o_c_u_s_._c │ │ │ │ │ + * _e_x___m_o_u_s_e_._c │ │ │ │ │ + * _e_x___f_o_n_t___j_u_s_t_i_f_y_._c_p_p │ │ │ │ │ ************ aall__iiss__mmoouussee__iinnssttaalllleedd ************ │ │ │ │ │ bool al_is_mouse_installed(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true if _a_l___i_n_s_t_a_l_l___m_o_u_s_e was called successfully. │ │ │ │ │ ************ aall__uunniinnssttaallll__mmoouussee ************ │ │ │ │ │ void al_uninstall_mouse(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ @@ -121,14 +130,16 @@ │ │ │ │ │ Return the number of axes on the mouse. The first axis is 0. │ │ │ │ │ See also: _a_l___g_e_t___m_o_u_s_e___n_u_m___b_u_t_t_o_n_s │ │ │ │ │ ************ aall__ggeett__mmoouussee__nnuumm__bbuuttttoonnss ************ │ │ │ │ │ unsigned int al_get_mouse_num_buttons(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the number of buttons on the mouse. The first button is 1. │ │ │ │ │ See also: _a_l___g_e_t___m_o_u_s_e___n_u_m___a_x_e_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_u_s_e___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__ggeett__mmoouussee__ssttaattee ************ │ │ │ │ │ void al_get_mouse_state(ALLEGRO_MOUSE_STATE *ret_state) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Save the state of the mouse specified at the time the function is called into │ │ │ │ │ the given structure. │ │ │ │ │ Example: │ │ │ │ │ ALLEGRO_MOUSE_STATE state; │ │ │ │ │ @@ -141,14 +152,18 @@ │ │ │ │ │ if (state.buttons & 2) { │ │ │ │ │ /* Secondary (e.g. right) mouse button is held. */ │ │ │ │ │ } │ │ │ │ │ if (state.buttons & 4) { │ │ │ │ │ /* Tertiary (e.g. middle) mouse button is held. */ │ │ │ │ │ } │ │ │ │ │ See also: _A_L_L_E_G_R_O___M_O_U_S_E___S_T_A_T_E, _a_l___g_e_t___m_o_u_s_e___s_t_a_t_e___a_x_i_s, _a_l___m_o_u_s_e___b_u_t_t_o_n___d_o_w_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_u_s_e___f_o_c_u_s_._c │ │ │ │ │ + * _e_x___m_o_u_s_e_._c │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ ************ aall__ggeett__mmoouussee__ssttaattee__aaxxiiss ************ │ │ │ │ │ int al_get_mouse_state_axis(const ALLEGRO_MOUSE_STATE *state, int axis) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Extract the mouse axis value from the saved state. The axes are numbered from │ │ │ │ │ 0, in this order: x-axis, y-axis, z-axis, w-axis. │ │ │ │ │ See also: _A_L_L_E_G_R_O___M_O_U_S_E___S_T_A_T_E, _a_l___g_e_t___m_o_u_s_e___s_t_a_t_e, _a_l___m_o_u_s_e___b_u_t_t_o_n___d_o_w_n │ │ │ │ │ ************ aall__mmoouussee__bbuuttttoonn__ddoowwnn ************ │ │ │ │ │ @@ -157,48 +172,59 @@ │ │ │ │ │ Return true if the mouse button specified was held down in the state specified. │ │ │ │ │ Unlike most things, the first mouse button is numbered 1. As a convenience, the │ │ │ │ │ constants ALLEGRO_MOUSE_BUTTON_LEFT, ALLEGRO_MOUSE_BUTTON_RIGHT, │ │ │ │ │ ALLEGRO_MOUSE_BUTTON_MIDDLE are provided. However, depending on the hardware │ │ │ │ │ there may be more or fewer mouse buttons. You can check │ │ │ │ │ _a_l___g_e_t___m_o_u_s_e___n_u_m___b_u_t_t_o_n_s if you want to be sure. │ │ │ │ │ See also: _A_L_L_E_G_R_O___M_O_U_S_E___S_T_A_T_E, _a_l___g_e_t___m_o_u_s_e___s_t_a_t_e, _a_l___g_e_t___m_o_u_s_e___s_t_a_t_e___a_x_i_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_u_s_e_._c │ │ │ │ │ ************ aall__sseett__mmoouussee__xxyy ************ │ │ │ │ │ bool al_set_mouse_xy(ALLEGRO_DISPLAY *display, int x, int y) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Try to position the mouse at the given coordinates on the given display. The │ │ │ │ │ mouse movement resulting from a successful move will generate an │ │ │ │ │ _A_L_L_E_G_R_O___E_V_E_N_T___M_O_U_S_E___W_A_R_P_E_D event. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___s_e_t___m_o_u_s_e___z, _a_l___s_e_t___m_o_u_s_e___w │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_u_s_e___w_a_r_p_._c │ │ │ │ │ + * _e_x___o_g_r_e_3_d_._c_p_p │ │ │ │ │ ************ aall__sseett__mmoouussee__zz ************ │ │ │ │ │ bool al_set_mouse_z(int z) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the mouse wheel position to the given value. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___s_e_t___m_o_u_s_e___w │ │ │ │ │ ************ aall__sseett__mmoouussee__ww ************ │ │ │ │ │ bool al_set_mouse_w(int w) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the second mouse wheel position to the given value. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___s_e_t___m_o_u_s_e___z │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_u_s_e___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__sseett__mmoouussee__aaxxiiss ************ │ │ │ │ │ bool al_set_mouse_axis(int which, int value) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the given mouse axis to the given value. │ │ │ │ │ The axis number must not be 0 or 1, which are the X and Y axes. Use │ │ │ │ │ _a_l___s_e_t___m_o_u_s_e___x_y for that. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___s_e_t___m_o_u_s_e___x_y, _a_l___s_e_t___m_o_u_s_e___z, _a_l___s_e_t___m_o_u_s_e___w │ │ │ │ │ ************ aall__ggeett__mmoouussee__eevveenntt__ssoouurrccee ************ │ │ │ │ │ ALLEGRO_EVENT_SOURCE *al_get_mouse_event_source(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Retrieve the mouse event source. All _m_o_u_s_e_ _e_v_e_n_t_s are generated by this event │ │ │ │ │ source. │ │ │ │ │ Returns NULL if the mouse subsystem was not installed. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_i_s_p_l_a_y___e_v_e_n_t_s_._c │ │ │ │ │ + * _e_x___m_o_u_s_e___w_a_r_p_._c │ │ │ │ │ + * _e_x___n_o_f_r_a_m_e_._c │ │ │ │ │ ************ aall__sseett__mmoouussee__wwhheeeell__pprreecciissiioonn ************ │ │ │ │ │ void al_set_mouse_wheel_precision(int precision) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Sets the precision of the mouse wheel (the z and w coordinates). This precision │ │ │ │ │ manifests itself as a multiplier on the dz and dw fields in mouse events. It │ │ │ │ │ also affects the z and w fields of events and _A_L_L_E_G_R_O___M_O_U_S_E___S_T_A_T_E, but not in a │ │ │ │ │ simple way if you alter the precision often, so it is suggested to reset those │ │ │ │ │ @@ -215,14 +241,16 @@ │ │ │ │ │ double dz = (double)event.mouse.dz / al_get_mouse_wheel_precision(); │ │ │ │ │ /* Use dz in some way... */ │ │ │ │ │ } │ │ │ │ │ Precision is set to 1 by default. It is impossible to set it to a lower │ │ │ │ │ precision than that. │ │ │ │ │ Since: 5.1.10 │ │ │ │ │ See also: _a_l___g_e_t___m_o_u_s_e___w_h_e_e_l___p_r_e_c_i_s_i_o_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_u_s_e___e_v_e_n_t_s_._c │ │ │ │ │ ************ aall__ggeett__mmoouussee__wwhheeeell__pprreecciissiioonn ************ │ │ │ │ │ int al_get_mouse_wheel_precision(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Gets the precision of the mouse wheel (the z and w coordinates). │ │ │ │ │ Since: 5.1.10 │ │ │ │ │ See also: _a_l___s_e_t___m_o_u_s_e___w_h_e_e_l___p_r_e_c_i_s_i_o_n │ │ │ │ │ ************ MMoouussee ccuurrssoorrss ************ │ │ │ │ │ @@ -230,31 +258,37 @@ │ │ │ │ │ ALLEGRO_MOUSE_CURSOR *al_create_mouse_cursor(ALLEGRO_BITMAP *bmp, │ │ │ │ │ int x_focus, int y_focus) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Create a mouse cursor from the bitmap provided. x_focus and y_focus describe │ │ │ │ │ the bit of the cursor that will represent the actual mouse position. │ │ │ │ │ Returns a pointer to the cursor on success, or NULL on failure. │ │ │ │ │ See also: _a_l___s_e_t___m_o_u_s_e___c_u_r_s_o_r, _a_l___d_e_s_t_r_o_y___m_o_u_s_e___c_u_r_s_o_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_u_s_e___c_u_r_s_o_r_._c │ │ │ │ │ ********** aall__ddeessttrrooyy__mmoouussee__ccuurrssoorr ********** │ │ │ │ │ void al_destroy_mouse_cursor(ALLEGRO_MOUSE_CURSOR *cursor) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Free the memory used by the given cursor. │ │ │ │ │ Has no effect if cursor is NULL. │ │ │ │ │ See also: _a_l___c_r_e_a_t_e___m_o_u_s_e___c_u_r_s_o_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_u_s_e___c_u_r_s_o_r_._c │ │ │ │ │ ********** aall__sseett__mmoouussee__ccuurrssoorr ********** │ │ │ │ │ bool al_set_mouse_cursor(ALLEGRO_DISPLAY *display, ALLEGRO_MOUSE_CURSOR │ │ │ │ │ *cursor) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the given mouse cursor to be the current mouse cursor for the given │ │ │ │ │ display. │ │ │ │ │ If the cursor is currently ‘shown’ (as opposed to ‘hidden’) the change is │ │ │ │ │ immediately visible. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___s_e_t___s_y_s_t_e_m___m_o_u_s_e___c_u_r_s_o_r, _a_l___s_h_o_w___m_o_u_s_e___c_u_r_s_o_r, │ │ │ │ │ _a_l___h_i_d_e___m_o_u_s_e___c_u_r_s_o_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_u_s_e___c_u_r_s_o_r_._c │ │ │ │ │ ********** aall__sseett__ssyysstteemm__mmoouussee__ccuurrssoorr ********** │ │ │ │ │ bool al_set_system_mouse_cursor(ALLEGRO_DISPLAY *display, │ │ │ │ │ ALLEGRO_SYSTEM_MOUSE_CURSOR cursor_id) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the given system mouse cursor to be the current mouse cursor for the given │ │ │ │ │ display. If the cursor is currently ‘shown’ (as opposed to ‘hidden’) the change │ │ │ │ │ is immediately visible. │ │ │ │ │ @@ -278,14 +312,16 @@ │ │ │ │ │ * ALLEGRO_SYSTEM_MOUSE_CURSOR_PROGRESS │ │ │ │ │ * ALLEGRO_SYSTEM_MOUSE_CURSOR_PRECISION │ │ │ │ │ * ALLEGRO_SYSTEM_MOUSE_CURSOR_LINK │ │ │ │ │ * ALLEGRO_SYSTEM_MOUSE_CURSOR_ALT_SELECT │ │ │ │ │ * ALLEGRO_SYSTEM_MOUSE_CURSOR_UNAVAILABLE │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___s_e_t___m_o_u_s_e___c_u_r_s_o_r, _a_l___s_h_o_w___m_o_u_s_e___c_u_r_s_o_r, _a_l___h_i_d_e___m_o_u_s_e___c_u_r_s_o_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_u_s_e___c_u_r_s_o_r_._c │ │ │ │ │ ********** aall__ccaann__ggeett__mmoouussee__ccuurrssoorr__ppoossiittiioonn ********** │ │ │ │ │ bool al_can_get_mouse_cursor_position(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true if getting the global mouse cursor position is available. │ │ │ │ │ Since: 5.2.9 │ │ │ │ │ See also: _a_l___g_e_t___m_o_u_s_e___c_u_r_s_o_r___p_o_s_i_t_i_o_n │ │ │ │ │ ********** aall__ggeett__mmoouussee__ccuurrssoorr__ppoossiittiioonn ********** │ │ │ │ │ @@ -293,28 +329,37 @@ │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ On platforms where this information is available, this function returns the │ │ │ │ │ global location of the mouse cursor, relative to the desktop. You should not │ │ │ │ │ normally use this function, as the information is not useful except for special │ │ │ │ │ scenarios as moving a window. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ See also: _a_l___c_a_n___g_e_t___m_o_u_s_e___c_u_r_s_o_r___p_o_s_i_t_i_o_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___n_o_f_r_a_m_e_._c │ │ │ │ │ ********** aall__hhiiddee__mmoouussee__ccuurrssoorr ********** │ │ │ │ │ bool al_hide_mouse_cursor(ALLEGRO_DISPLAY *display) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Hide the mouse cursor in the given display. This has no effect on what the │ │ │ │ │ current mouse cursor looks like; it just makes it disappear. │ │ │ │ │ Returns true on success (or if the cursor already was hidden), false otherwise. │ │ │ │ │ See also: _a_l___s_h_o_w___m_o_u_s_e___c_u_r_s_o_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_o_u_s_e_._c │ │ │ │ │ + * _e_x___o_g_r_e_3_d_._c_p_p │ │ │ │ │ + * _e_x___m_o_u_s_e___e_v_e_n_t_s_._c │ │ │ │ │ ********** aall__sshhooww__mmoouussee__ccuurrssoorr ********** │ │ │ │ │ bool al_show_mouse_cursor(ALLEGRO_DISPLAY *display) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Make a mouse cursor visible in the given display. │ │ │ │ │ Returns true if a mouse cursor is shown as a result of the call (or one already │ │ │ │ │ was visible), false otherwise. │ │ │ │ │ See also: _a_l___h_i_d_e___m_o_u_s_e___c_u_r_s_o_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___o_g_r_e_3_d_._c_p_p │ │ │ │ │ + * _e_x___m_o_u_s_e___c_u_r_s_o_r_._c │ │ │ │ │ ********** aall__ggrraabb__mmoouussee ********** │ │ │ │ │ bool al_grab_mouse(ALLEGRO_DISPLAY *display) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Confine the mouse cursor to the given display. The mouse cursor can only be │ │ │ │ │ confined to one display at a time. │ │ │ │ │ Returns true if successful, otherwise returns false. Do not assume that the │ │ │ │ │ cursor will remain confined until you call _a_l___u_n_g_r_a_b___m_o_u_s_e. It may lose the │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/native_dialog.html │ │ │ │ @@ -267,20 +267,32 @@ │ │ │ │ 
     #include <allegro5/allegro_native_dialog.h>
    │ │ │ │

    ALLEGRO_FILECHOOSER

    │ │ │ │ 
    typedef struct ALLEGRO_FILECHOOSER ALLEGRO_FILECHOOSER;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Opaque handle to a native file dialog.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_TEXTLOG

    │ │ │ │ 
    typedef struct ALLEGRO_TEXTLOG ALLEGRO_TEXTLOG;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Opaque handle to a text log window.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_init_native_dialog_addon

    │ │ │ │ 
    bool al_init_native_dialog_addon(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Initialise the native dialog addon.

    │ │ │ │

    Returns true on success, false on error.

    │ │ │ │ @@ -292,14 +304,23 @@ │ │ │ │ is al_show_native_message_box, │ │ │ │ which may be useful to show an error message if Allegro fails to │ │ │ │ initialise.

    │ │ │ │
    │ │ │ │

    See also: al_shutdown_native_dialog_addon

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_is_native_dialog_addon_initialized

    │ │ │ │ 
    bool al_is_native_dialog_addon_initialized(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true if the native dialog addon is initialized, otherwise │ │ │ │ @@ -406,14 +427,19 @@ │ │ │ │ and al_get_native_file_dialog_path. │ │ │ │ When you are done, call al_destroy_native_file_dialog │ │ │ │ on it.

    │ │ │ │

    If a dialog window could not be created then this function returns │ │ │ │ NULL.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_show_native_file_dialog

    │ │ │ │ 
    bool al_show_native_file_dialog(ALLEGRO_DISPLAY *display,
│ │ │ │     ALLEGRO_FILECHOOSER *dialog)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Show the dialog window. The display may be NULL, otherwise the given │ │ │ │ @@ -427,22 +453,32 @@ │ │ │ │

    Note: On Android, ALLEGRO_EVENT_DISPLAY_HALT_DRAWING │ │ │ │ and ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING │ │ │ │ need to be handled before this function returns. This means that you │ │ │ │ must call it from a different thread.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_native_file_dialog_count

    │ │ │ │ 
    int al_get_native_file_dialog_count(const ALLEGRO_FILECHOOSER *dialog)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the number of files selected, or 0 if the dialog was │ │ │ │ cancelled.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_native_file_dialog_path

    │ │ │ │ 
    const char *al_get_native_file_dialog_path(
│ │ │ │     const ALLEGRO_FILECHOOSER *dialog, size_t i)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -452,21 +488,31 @@ │ │ │ │ -1.

    │ │ │ │
    │ │ │ │

    Note: On Android, this function returns a content:// │ │ │ │ Universal Resource Identifier instead of a file path due to the │ │ │ │ constraints of Scoped Storage. Selected files may be accessed using al_android_open_fd.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_destroy_native_file_dialog

    │ │ │ │ 
    void al_destroy_native_file_dialog(ALLEGRO_FILECHOOSER *dialog)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Frees up all resources used by the file dialog.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_show_native_message_box

    │ │ │ │ 
    int al_show_native_message_box(ALLEGRO_DISPLAY *display,
│ │ │ │     char const *title, char const *heading, char const *text,
│ │ │ │     char const *buttons, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -532,14 +578,23 @@ │ │ │ │ "If you click yes then you are confirming that \"Yes\" " │ │ │ │ "is your response to the query which you have " │ │ │ │ "generated by the action you took to open this " │ │ │ │ "message box.", │ │ │ │ NULL, │ │ │ │ ALLEGRO_MESSAGEBOX_YES_NO │ │ │ │ ); │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_open_native_text_log

    │ │ │ │ 
    ALLEGRO_TEXTLOG *al_open_native_text_log(char const *title, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Opens a window to which you can append log messages with al_append_native_text_log. │ │ │ │ @@ -566,37 +621,58 @@ │ │ │ │

    │ │ │ │

    Note: On Android, logs can be viewed using logcat.

    │ │ │ │
    │ │ │ │

    See also: al_append_native_text_log, │ │ │ │ al_close_native_text_log

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_close_native_text_log

    │ │ │ │ 
    void al_close_native_text_log(ALLEGRO_TEXTLOG *textlog)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Closes a message log window opened with al_open_native_text_log │ │ │ │ earlier.

    │ │ │ │

    Does nothing if passed NULL.

    │ │ │ │

    See also: al_open_native_text_log

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_append_native_text_log

    │ │ │ │ 
    void al_append_native_text_log(ALLEGRO_TEXTLOG *textlog,
│ │ │ │     char const *format, ...)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Appends a line of text to the message log window and scrolls to the │ │ │ │ bottom (if the line would not be visible otherwise). This works like │ │ │ │ printf. A line is continued until you add a newline character.

    │ │ │ │

    If the window is NULL then this function will fall back to calling │ │ │ │ printf. This makes it convenient to support logging to a window or a │ │ │ │ terminal.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_native_text_log_event_source

    │ │ │ │ 
    ALLEGRO_EVENT_SOURCE *al_get_native_text_log_event_source(
│ │ │ │     ALLEGRO_TEXTLOG *textlog)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -609,14 +685,23 @@ │ │ │ │ button or pressing Escape on the keyboard. The user.data1 field will │ │ │ │ hold a pointer to the ALLEGRO_TEXTLOG which │ │ │ │ generated the event. The user.data2 field will be 1 if the event was │ │ │ │ generated as a result of a key press; otherwise it will be zero. │ │ │ │ │ │ │ │ │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_allegro_native_dialog_version

    │ │ │ │ 
    uint32_t al_get_allegro_native_dialog_version(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the (compiled) version of the addon, in the same format as ALLEGRO_MENU │ │ │ │ 

    typedef struct ALLEGRO_MENU ALLEGRO_MENU;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    An opaque data type that represents a menu that contains menu items. │ │ │ │ Each of the menu items may optionally include a sub-menu.

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    ALLEGRO_MENU_INFO

    │ │ │ │ 
    typedef struct ALLEGRO_MENU_INFO {
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    A structure that defines how to create a complete menu system. For │ │ │ │ standard menu items, the following format is used:

    │ │ │ │ @@ -713,14 +803,19 @@ │ │ │ │ │ │ │ │ ALLEGRO_MENU *menu = al_build_menu(menu_info); │ │ │ │

    If you prefer, you can build the menu without the structure by using │ │ │ │ al_create_menu and al_insert_menu_item.

    │ │ │ │

    See also: al_build_menu

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_create_menu

    │ │ │ │ 
    ALLEGRO_MENU *al_create_menu(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Creates a menu container that can hold menu items.

    │ │ │ │

    Returns NULL on failure.

    │ │ │ │ @@ -738,14 +833,19 @@ │ │ │ │ created with al_create_menu.

    │ │ │ │

    Returns NULL on failure.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_create_menu, al_build_menu

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_build_menu

    │ │ │ │ 
    ALLEGRO_MENU *al_build_menu(ALLEGRO_MENU_INFO *info)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Builds a menu based on the specifications of a sequence of │ │ │ │ ALLEGRO_MENU_INFO elements.

    │ │ │ │ @@ -754,28 +854,38 @@ │ │ │ │ items, you will need to search for them using al_find_menu_item.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: ALLEGRO_MENU_INFO, al_create_menu, al_create_popup_menu

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_append_menu_item

    │ │ │ │ 
    int al_append_menu_item(ALLEGRO_MENU *parent, char const *title, uint16_t id,
│ │ │ │     int flags, ALLEGRO_BITMAP *icon, ALLEGRO_MENU *submenu)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Appends a menu item to the end of the menu. See al_insert_menu_item │ │ │ │ for more information.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_insert_menu_item, │ │ │ │ al_remove_menu_item

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_insert_menu_item

    │ │ │ │ 
    int al_insert_menu_item(ALLEGRO_MENU *parent, int pos, char const *title,
│ │ │ │     uint16_t id, int flags, ALLEGRO_BITMAP *icon, ALLEGRO_MENU *submenu)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Inserts a menu item at the spot specified. See the introductory text │ │ │ │ @@ -826,48 +936,68 @@ │ │ │ │

    Returns true if an item was removed.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_append_menu_item, │ │ │ │ al_insert_menu_item, │ │ │ │ al_destroy_menu

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_clone_menu

    │ │ │ │ 
    ALLEGRO_MENU *al_clone_menu(ALLEGRO_MENU *menu)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Makes a copy of a menu so that it can be reused on another display. │ │ │ │ The menu being cloned can be anything: a regular menu, a popup menu, or │ │ │ │ a sub-menu.

    │ │ │ │

    Returns the cloned menu.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_clone_menu_for_popup

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_clone_menu_for_popup

    │ │ │ │ 
    ALLEGRO_MENU *al_clone_menu_for_popup(ALLEGRO_MENU *menu)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Exactly like al_clone_menu, except that │ │ │ │ the copy is for a popup menu.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_clone_menu

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_destroy_menu

    │ │ │ │ 
    void al_destroy_menu(ALLEGRO_MENU *menu)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Destroys an entire menu, including its sub-menus. Any references to │ │ │ │ it or a sub-menu are no longer valid. It is safe to call this on a menu │ │ │ │ that is currently being displayed.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_remove_menu_item

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_get_menu_item_caption

    │ │ │ │ 
    const char *al_get_menu_item_caption(ALLEGRO_MENU *menu, int pos)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the caption associated with the menu item. It is valid as │ │ │ │ long as the caption is not modified.

    │ │ │ │ @@ -882,41 +1012,56 @@ │ │ │ │ Code

    │ │ │ │

    Updates the menu item caption with the new caption. This │ │ │ │ will invalidate any previous calls to al_get_menu_item_caption.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_get_menu_item_caption

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_get_menu_item_flags

    │ │ │ │ 
    int al_get_menu_item_flags(ALLEGRO_MENU *menu, int pos)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the currently set flags. See al_insert_menu_item │ │ │ │ for a description of the available flags.

    │ │ │ │

    Returns -1 if the item was not found.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_set_menu_item_flags, │ │ │ │ al_toggle_menu_item_flags

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_set_menu_item_flags

    │ │ │ │ 
    void al_set_menu_item_flags(ALLEGRO_MENU *menu, int pos, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Updates the menu item’s flags. See al_insert_menu_item │ │ │ │ for a description of the available flags.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_get_menu_item_flags, │ │ │ │ al_toggle_menu_item_flags

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_toggle_menu_item_flags

    │ │ │ │ 
    int al_toggle_menu_item_flags(ALLEGRO_MENU *menu, int pos, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Toggles the specified menu item’s flags. See al_insert_menu_item │ │ │ │ @@ -958,26 +1103,36 @@ │ │ │ │ you must clone it if you wish to continue using it.

    │ │ │ │

    If a video bitmap is passed, it will automatically be converted to a │ │ │ │ memory bitmap, so it is preferable to pass a memory bitmap.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_get_menu_item_icon, │ │ │ │ al_clone_bitmap

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_find_menu

    │ │ │ │ 
    ALLEGRO_MENU *al_find_menu(ALLEGRO_MENU *haystack, uint16_t id)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Searches in the haystack menu for any submenu with the │ │ │ │ given id. (Note that this only represents a literal ID, and │ │ │ │ cannot be used as an index.)

    │ │ │ │

    Returns the menu, if found. Otherwise returns NULL.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_find_menu_item

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_find_menu_item

    │ │ │ │ 
    bool al_find_menu_item(ALLEGRO_MENU *haystack, uint16_t id, ALLEGRO_MENU **menu,
│ │ │ │     int *index)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Searches in the haystack menu for an item with the given │ │ │ │ @@ -1004,14 +1159,19 @@ │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_register_event_source, │ │ │ │ al_enable_menu_event_source, │ │ │ │ al_disable_menu_event_source

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_enable_menu_event_source

    │ │ │ │ 
    ALLEGRO_EVENT_SOURCE *al_enable_menu_event_source(ALLEGRO_MENU *menu)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Enables a unique event source for this menu. It and all of its │ │ │ │ sub-menus will use this event source. (It is safe to call this multiple │ │ │ │ @@ -1066,14 +1226,19 @@ │ │ │ │ want to maintain your window’s prior size.

    │ │ │ │ │ │ │ │

    Returns true if successful.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_create_menu, al_remove_display_menu

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_popup_menu

    │ │ │ │ 
    bool al_popup_menu(ALLEGRO_MENU *popup, ALLEGRO_DISPLAY *display)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Displays a context menu next to the mouse cursor. The menu must have │ │ │ │ been created with ALLEGRO_MOUSE_BUTTON_UP events and even then only if that │ │ │ │ event corresponds to the final mouse button that was pressed.

    │ │ │ │ │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_create_popup_menu

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    al_remove_display_menu

    │ │ │ │ 
    ALLEGRO_MENU *al_remove_display_menu(ALLEGRO_DISPLAY *display)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Detaches the menu associated with the display and returns it. The │ │ │ │ menu can then be used on a different display.

    │ │ │ │

    If you simply want to destroy the active menu, you can call al_set_display_menu │ │ │ │ with a NULL menu.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_set_display_menu

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_menu.c
      • │ │ │ │ +
    │ │ │ │

    │ │ │ │ Allegro version 5.2.10 │ │ │ │ - Last updated: 2025-01-09 13:52:42 UTC │ │ │ │

    │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -90,30 +90,39 @@ │ │ │ │ │ These functions are declared in the following header file. Link with │ │ │ │ │ allegro_dialog. │ │ │ │ │ #include │ │ │ │ │ ************ AALLLLEEGGRROO__FFIILLEECCHHOOOOSSEERR ************ │ │ │ │ │ typedef struct ALLEGRO_FILECHOOSER ALLEGRO_FILECHOOSER; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Opaque handle to a native file dialog. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___n_a_t_i_v_e___f_i_l_e_c_h_o_o_s_e_r_._c │ │ │ │ │ ************ AALLLLEEGGRROO__TTEEXXTTLLOOGG ************ │ │ │ │ │ typedef struct ALLEGRO_TEXTLOG ALLEGRO_TEXTLOG; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Opaque handle to a text log window. │ │ │ │ │ +Examples: │ │ │ │ │ + * _c_o_m_m_o_n_._c │ │ │ │ │ + * _e_x___n_a_t_i_v_e___f_i_l_e_c_h_o_o_s_e_r_._c │ │ │ │ │ ************ aall__iinniitt__nnaattiivvee__ddiiaalloogg__aaddddoonn ************ │ │ │ │ │ bool al_init_native_dialog_addon(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Initialise the native dialog addon. │ │ │ │ │ Returns true on success, false on error. │ │ │ │ │ Since: 5.0.9, 5.1.0 │ │ │ │ │ NNoottee:: Prior to Allegro 5.1.0 native dialog functions could be called │ │ │ │ │ without explicit initialisation, but that is now deprecated. Future │ │ │ │ │ functionality may require explicit initialisation. An exception is │ │ │ │ │ _a_l___s_h_o_w___n_a_t_i_v_e___m_e_s_s_a_g_e___b_o_x, which may be useful to show an error │ │ │ │ │ message if Allegro fails to initialise. │ │ │ │ │ See also: _a_l___s_h_u_t_d_o_w_n___n_a_t_i_v_e___d_i_a_l_o_g___a_d_d_o_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _c_o_m_m_o_n_._c │ │ │ │ │ + * _e_x___w_i_n_d_o_w___m_a_x_i_m_i_z_e_d_._c │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ************ aall__iiss__nnaattiivvee__ddiiaalloogg__aaddddoonn__iinniittiiaalliizzeedd ************ │ │ │ │ │ bool al_is_native_dialog_addon_initialized(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true if the native dialog addon is initialized, otherwise returns │ │ │ │ │ false. │ │ │ │ │ Since: 5.2.6 │ │ │ │ │ ************ aall__sshhuuttddoowwnn__nnaattiivvee__ddiiaalloogg__aaddddoonn ************ │ │ │ │ │ @@ -180,45 +189,55 @@ │ │ │ │ │ If supported, allow selecting multiple files. │ │ │ │ │ Returns: │ │ │ │ │ A handle to the dialog which you can pass to _a_l___s_h_o_w___n_a_t_i_v_e___f_i_l_e___d_i_a_l_o_g to │ │ │ │ │ display it, and from which you then can query the results using │ │ │ │ │ _a_l___g_e_t___n_a_t_i_v_e___f_i_l_e___d_i_a_l_o_g___c_o_u_n_t and _a_l___g_e_t___n_a_t_i_v_e___f_i_l_e___d_i_a_l_o_g___p_a_t_h. When you │ │ │ │ │ are done, call _a_l___d_e_s_t_r_o_y___n_a_t_i_v_e___f_i_l_e___d_i_a_l_o_g on it. │ │ │ │ │ If a dialog window could not be created then this function returns NULL. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___n_a_t_i_v_e___f_i_l_e_c_h_o_o_s_e_r_._c │ │ │ │ │ ************ aall__sshhooww__nnaattiivvee__ffiillee__ddiiaalloogg ************ │ │ │ │ │ bool al_show_native_file_dialog(ALLEGRO_DISPLAY *display, │ │ │ │ │ ALLEGRO_FILECHOOSER *dialog) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Show the dialog window. The display may be NULL, otherwise the given display is │ │ │ │ │ treated as the parent if possible. │ │ │ │ │ This function blocks the calling thread until it returns, so you may want to │ │ │ │ │ spawn a thread with _a_l___c_r_e_a_t_e___t_h_r_e_a_d and call it from inside that thread. │ │ │ │ │ Returns true on success, false on failure. │ │ │ │ │ NNoottee:: On Android, _A_L_L_E_G_R_O___E_V_E_N_T___D_I_S_P_L_A_Y___H_A_L_T___D_R_A_W_I_N_G and │ │ │ │ │ _A_L_L_E_G_R_O___E_V_E_N_T___D_I_S_P_L_A_Y___R_E_S_U_M_E___D_R_A_W_I_N_G need to be handled before this │ │ │ │ │ function returns. This means that you must call it from a different │ │ │ │ │ thread. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___n_a_t_i_v_e___f_i_l_e_c_h_o_o_s_e_r_._c │ │ │ │ │ ************ aall__ggeett__nnaattiivvee__ffiillee__ddiiaalloogg__ccoouunntt ************ │ │ │ │ │ int al_get_native_file_dialog_count(const ALLEGRO_FILECHOOSER *dialog) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the number of files selected, or 0 if the dialog was cancelled. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___n_a_t_i_v_e___f_i_l_e_c_h_o_o_s_e_r_._c │ │ │ │ │ ************ aall__ggeett__nnaattiivvee__ffiillee__ddiiaalloogg__ppaatthh ************ │ │ │ │ │ const char *al_get_native_file_dialog_path( │ │ │ │ │ const ALLEGRO_FILECHOOSER *dialog, size_t i) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns one of the selected paths with index i. The index should range from 0 │ │ │ │ │ to the return value of _a_l___g_e_t___n_a_t_i_v_e___f_i_l_e___d_i_a_l_o_g___c_o_u_n_t -1. │ │ │ │ │ NNoottee:: On Android, this function returns a content:// Universal │ │ │ │ │ Resource Identifier instead of a file path due to the constraints of │ │ │ │ │ Scoped Storage. Selected files may be accessed using │ │ │ │ │ _a_l___a_n_d_r_o_i_d___o_p_e_n___f_d. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___n_a_t_i_v_e___f_i_l_e_c_h_o_o_s_e_r_._c │ │ │ │ │ ************ aall__ddeessttrrooyy__nnaattiivvee__ffiillee__ddiiaalloogg ************ │ │ │ │ │ void al_destroy_native_file_dialog(ALLEGRO_FILECHOOSER *dialog) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Frees up all resources used by the file dialog. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___n_a_t_i_v_e___f_i_l_e_c_h_o_o_s_e_r_._c │ │ │ │ │ ************ aall__sshhooww__nnaattiivvee__mmeessssaaggee__bbooxx ************ │ │ │ │ │ int al_show_native_message_box(ALLEGRO_DISPLAY *display, │ │ │ │ │ char const *title, char const *heading, char const *text, │ │ │ │ │ char const *buttons, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Show a native GUI message box. This can be used for example to display an error │ │ │ │ │ message if creation of an initial display fails. The display may be NULL, │ │ │ │ │ @@ -261,14 +280,18 @@ │ │ │ │ │ "If you click yes then you are confirming that \"Yes\" " │ │ │ │ │ "is your response to the query which you have " │ │ │ │ │ "generated by the action you took to open this " │ │ │ │ │ "message box.", │ │ │ │ │ NULL, │ │ │ │ │ ALLEGRO_MESSAGEBOX_YES_NO │ │ │ │ │ ); │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___n_o_d_i_s_p_l_a_y_._c │ │ │ │ │ + * _c_o_m_m_o_n_._c │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ************ aall__ooppeenn__nnaattiivvee__tteexxtt__lloogg ************ │ │ │ │ │ ALLEGRO_TEXTLOG *al_open_native_text_log(char const *title, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Opens a window to which you can append log messages with │ │ │ │ │ _a_l___a_p_p_e_n_d___n_a_t_i_v_e___t_e_x_t___l_o_g. This can be useful for debugging if you don’t want │ │ │ │ │ to depend on a console being available. │ │ │ │ │ Use _a_l___c_l_o_s_e___n_a_t_i_v_e___t_e_x_t___l_o_g to close the window again. │ │ │ │ │ @@ -279,40 +302,53 @@ │ │ │ │ │ _a_l___g_e_t___n_a_t_i_v_e___t_e_x_t___l_o_g___e_v_e_n_t___s_o_u_r_c_e. │ │ │ │ │ ALLEGRO_TEXTLOG_MONOSPACE │ │ │ │ │ Use a monospace font to display the text. │ │ │ │ │ Returns NULL if there was an error opening the window, or if text log windows │ │ │ │ │ are not implemented on the platform. │ │ │ │ │ NNoottee:: On Android, logs can be viewed using logcat. │ │ │ │ │ See also: _a_l___a_p_p_e_n_d___n_a_t_i_v_e___t_e_x_t___l_o_g, _a_l___c_l_o_s_e___n_a_t_i_v_e___t_e_x_t___l_o_g │ │ │ │ │ +Examples: │ │ │ │ │ + * _c_o_m_m_o_n_._c │ │ │ │ │ + * _e_x___n_a_t_i_v_e___f_i_l_e_c_h_o_o_s_e_r_._c │ │ │ │ │ ************ aall__cclloossee__nnaattiivvee__tteexxtt__lloogg ************ │ │ │ │ │ void al_close_native_text_log(ALLEGRO_TEXTLOG *textlog) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Closes a message log window opened with _a_l___o_p_e_n___n_a_t_i_v_e___t_e_x_t___l_o_g earlier. │ │ │ │ │ Does nothing if passed NULL. │ │ │ │ │ See also: _a_l___o_p_e_n___n_a_t_i_v_e___t_e_x_t___l_o_g │ │ │ │ │ +Examples: │ │ │ │ │ + * _c_o_m_m_o_n_._c │ │ │ │ │ + * _e_x___n_a_t_i_v_e___f_i_l_e_c_h_o_o_s_e_r_._c │ │ │ │ │ ************ aall__aappppeenndd__nnaattiivvee__tteexxtt__lloogg ************ │ │ │ │ │ void al_append_native_text_log(ALLEGRO_TEXTLOG *textlog, │ │ │ │ │ char const *format, ...) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Appends a line of text to the message log window and scrolls to the bottom (if │ │ │ │ │ the line would not be visible otherwise). This works like printf. A line is │ │ │ │ │ continued until you add a newline character. │ │ │ │ │ If the window is NULL then this function will fall back to calling printf. This │ │ │ │ │ makes it convenient to support logging to a window or a terminal. │ │ │ │ │ +Examples: │ │ │ │ │ + * _c_o_m_m_o_n_._c │ │ │ │ │ + * _e_x___n_a_t_i_v_e___f_i_l_e_c_h_o_o_s_e_r_._c │ │ │ │ │ ************ aall__ggeett__nnaattiivvee__tteexxtt__lloogg__eevveenntt__ssoouurrccee ************ │ │ │ │ │ ALLEGRO_EVENT_SOURCE *al_get_native_text_log_event_source( │ │ │ │ │ ALLEGRO_TEXTLOG *textlog) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get an event source for a text log window. The possible events are: │ │ │ │ │ ALLEGRO_EVENT_NATIVE_DIALOG_CLOSE │ │ │ │ │ The window was requested to be closed, either by pressing the close │ │ │ │ │ button or pressing Escape on the keyboard. The user.data1 field will hold │ │ │ │ │ a pointer to the _A_L_L_E_G_R_O___T_E_X_T_L_O_G which generated the event. The │ │ │ │ │ user.data2 field will be 1 if the event was generated as a result of a │ │ │ │ │ key press; otherwise it will be zero. │ │ │ │ │ +Examples: │ │ │ │ │ + * _c_o_m_m_o_n_._c │ │ │ │ │ + * _e_x___s_a_w_._c │ │ │ │ │ + * _e_x___r_e_s_a_m_p_l_e___t_e_s_t_._c │ │ │ │ │ ************ aall__ggeett__aalllleeggrroo__nnaattiivvee__ddiiaalloogg__vveerrssiioonn ************ │ │ │ │ │ uint32_t al_get_allegro_native_dialog_version(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the (compiled) version of the addon, in the same format as │ │ │ │ │ _a_l___g_e_t___a_l_l_e_g_r_o___v_e_r_s_i_o_n. │ │ │ │ │ ************ MMeennuuss ************ │ │ │ │ │ Menus are implemented on Windows, X and OS X. Menus on X are implemented with │ │ │ │ │ @@ -361,14 +397,16 @@ │ │ │ │ │ al_set_display_menu(display, NULL) before destroying any display with a menu │ │ │ │ │ attached, to avoid leaking resources. │ │ │ │ │ ********** AALLLLEEGGRROO__MMEENNUU ********** │ │ │ │ │ typedef struct ALLEGRO_MENU ALLEGRO_MENU; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ An opaque data type that represents a menu that contains menu items. Each of │ │ │ │ │ the menu items may optionally include a sub-menu. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** AALLLLEEGGRROO__MMEENNUU__IINNFFOO ********** │ │ │ │ │ typedef struct ALLEGRO_MENU_INFO { │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ A structure that defines how to create a complete menu system. For standard │ │ │ │ │ menu items, the following format is used: │ │ │ │ │ { caption, id, flags, icon } │ │ │ │ │ For special items, these macros are helpful: │ │ │ │ │ @@ -394,14 +432,16 @@ │ │ │ │ │ ALLEGRO_END_OF_MENU │ │ │ │ │ }; │ │ │ │ │ │ │ │ │ │ ALLEGRO_MENU *menu = al_build_menu(menu_info); │ │ │ │ │ If you prefer, you can build the menu without the structure by using │ │ │ │ │ _a_l___c_r_e_a_t_e___m_e_n_u and _a_l___i_n_s_e_r_t___m_e_n_u___i_t_e_m. │ │ │ │ │ See also: _a_l___b_u_i_l_d___m_e_n_u │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__ccrreeaattee__mmeennuu ********** │ │ │ │ │ ALLEGRO_MENU *al_create_menu(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Creates a menu container that can hold menu items. │ │ │ │ │ Returns NULL on failure. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___c_r_e_a_t_e___p_o_p_u_p___m_e_n_u, _a_l___b_u_i_l_d___m_e_n_u │ │ │ │ │ @@ -410,32 +450,38 @@ │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Creates a menu container for popup menus. Only the root (outermost) menu should │ │ │ │ │ be created with this function. Sub menus of popups should be created with │ │ │ │ │ _a_l___c_r_e_a_t_e___m_e_n_u. │ │ │ │ │ Returns NULL on failure. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___c_r_e_a_t_e___m_e_n_u, _a_l___b_u_i_l_d___m_e_n_u │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__bbuuiilldd__mmeennuu ********** │ │ │ │ │ ALLEGRO_MENU *al_build_menu(ALLEGRO_MENU_INFO *info) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Builds a menu based on the specifications of a sequence of ALLEGRO_MENU_INFO │ │ │ │ │ elements. │ │ │ │ │ Returns a pointer to the root ALLEGRO_MENU, or NULL on failure. To gain access │ │ │ │ │ to the other menus and items, you will need to search for them using │ │ │ │ │ _a_l___f_i_n_d___m_e_n_u___i_t_e_m. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _A_L_L_E_G_R_O___M_E_N_U___I_N_F_O, _a_l___c_r_e_a_t_e___m_e_n_u, _a_l___c_r_e_a_t_e___p_o_p_u_p___m_e_n_u │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__aappppeenndd__mmeennuu__iitteemm ********** │ │ │ │ │ int al_append_menu_item(ALLEGRO_MENU *parent, char const *title, uint16_t id, │ │ │ │ │ int flags, ALLEGRO_BITMAP *icon, ALLEGRO_MENU *submenu) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Appends a menu item to the end of the menu. See _a_l___i_n_s_e_r_t___m_e_n_u___i_t_e_m for more │ │ │ │ │ information. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___i_n_s_e_r_t___m_e_n_u___i_t_e_m, _a_l___r_e_m_o_v_e___m_e_n_u___i_t_e_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__iinnsseerrtt__mmeennuu__iitteemm ********** │ │ │ │ │ int al_insert_menu_item(ALLEGRO_MENU *parent, int pos, char const *title, │ │ │ │ │ uint16_t id, int flags, ALLEGRO_BITMAP *icon, ALLEGRO_MENU *submenu) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Inserts a menu item at the spot specified. See the introductory text for a │ │ │ │ │ detailed explanation of how the pos parameter is interpreted. │ │ │ │ │ The parent menu can be a popup menu or a regular menu. To underline one │ │ │ │ │ @@ -463,36 +509,44 @@ │ │ │ │ │ a sub-menu, it too is destroyed. Any references to it are invalidated. If you │ │ │ │ │ want to preserve that sub-menu, you should first make a copy with │ │ │ │ │ _a_l___c_l_o_n_e___m_e_n_u. │ │ │ │ │ This is safe to call on a menu that is currently being displayed. │ │ │ │ │ Returns true if an item was removed. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___a_p_p_e_n_d___m_e_n_u___i_t_e_m, _a_l___i_n_s_e_r_t___m_e_n_u___i_t_e_m, _a_l___d_e_s_t_r_o_y___m_e_n_u │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__cclloonnee__mmeennuu ********** │ │ │ │ │ ALLEGRO_MENU *al_clone_menu(ALLEGRO_MENU *menu) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Makes a copy of a menu so that it can be reused on another display. The menu │ │ │ │ │ being cloned can be anything: a regular menu, a popup menu, or a sub-menu. │ │ │ │ │ Returns the cloned menu. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___c_l_o_n_e___m_e_n_u___f_o_r___p_o_p_u_p │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__cclloonnee__mmeennuu__ffoorr__ppooppuupp ********** │ │ │ │ │ ALLEGRO_MENU *al_clone_menu_for_popup(ALLEGRO_MENU *menu) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Exactly like _a_l___c_l_o_n_e___m_e_n_u, except that the copy is for a popup menu. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___c_l_o_n_e___m_e_n_u │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__ddeessttrrooyy__mmeennuu ********** │ │ │ │ │ void al_destroy_menu(ALLEGRO_MENU *menu) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Destroys an entire menu, including its sub-menus. Any references to it or a │ │ │ │ │ sub-menu are no longer valid. It is safe to call this on a menu that is │ │ │ │ │ currently being displayed. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___r_e_m_o_v_e___m_e_n_u___i_t_e_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__ggeett__mmeennuu__iitteemm__ccaappttiioonn ********** │ │ │ │ │ const char *al_get_menu_item_caption(ALLEGRO_MENU *menu, int pos) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the caption associated with the menu item. It is valid as long as the │ │ │ │ │ caption is not modified. │ │ │ │ │ Returns NULL if the item was not found. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ @@ -500,29 +554,35 @@ │ │ │ │ │ ********** aall__sseett__mmeennuu__iitteemm__ccaappttiioonn ********** │ │ │ │ │ void al_set_menu_item_caption(ALLEGRO_MENU *menu, int pos, const char *caption) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Updates the menu item caption with the new caption. This will invalidate any │ │ │ │ │ previous calls to _a_l___g_e_t___m_e_n_u___i_t_e_m___c_a_p_t_i_o_n. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___g_e_t___m_e_n_u___i_t_e_m___c_a_p_t_i_o_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__ggeett__mmeennuu__iitteemm__ffllaaggss ********** │ │ │ │ │ int al_get_menu_item_flags(ALLEGRO_MENU *menu, int pos) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the currently set flags. See _a_l___i_n_s_e_r_t___m_e_n_u___i_t_e_m for a description of │ │ │ │ │ the available flags. │ │ │ │ │ Returns -1 if the item was not found. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___s_e_t___m_e_n_u___i_t_e_m___f_l_a_g_s, _a_l___t_o_g_g_l_e___m_e_n_u___i_t_e_m___f_l_a_g_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__sseett__mmeennuu__iitteemm__ffllaaggss ********** │ │ │ │ │ void al_set_menu_item_flags(ALLEGRO_MENU *menu, int pos, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Updates the menu item’s flags. See _a_l___i_n_s_e_r_t___m_e_n_u___i_t_e_m for a description of the │ │ │ │ │ available flags. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___g_e_t___m_e_n_u___i_t_e_m___f_l_a_g_s, _a_l___t_o_g_g_l_e___m_e_n_u___i_t_e_m___f_l_a_g_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__ttooggggllee__mmeennuu__iitteemm__ffllaaggss ********** │ │ │ │ │ int al_toggle_menu_item_flags(ALLEGRO_MENU *menu, int pos, int flags) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Toggles the specified menu item’s flags. See _a_l___i_n_s_e_r_t___m_e_n_u___i_t_e_m for a │ │ │ │ │ description of the available flags. │ │ │ │ │ Returns a bitfield of only the specified flags that are set after the toggle. A │ │ │ │ │ flag that was not toggled will not be returned, even if it is set. Returns - │ │ │ │ │ @@ -545,22 +605,26 @@ │ │ │ │ │ Sets the icon for the specified menu item. The menu assumes ownership of the │ │ │ │ │ ALLEGRO_BITMAP and may invalidate the pointer, so you must clone it if you wish │ │ │ │ │ to continue using it. │ │ │ │ │ If a video bitmap is passed, it will automatically be converted to a memory │ │ │ │ │ bitmap, so it is preferable to pass a memory bitmap. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___g_e_t___m_e_n_u___i_t_e_m___i_c_o_n, _a_l___c_l_o_n_e___b_i_t_m_a_p │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__ffiinndd__mmeennuu ********** │ │ │ │ │ ALLEGRO_MENU *al_find_menu(ALLEGRO_MENU *haystack, uint16_t id) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Searches in the haystack menu for any submenu with the given id. (Note that │ │ │ │ │ this only represents a literal ID, and cannot be used as an index.) │ │ │ │ │ Returns the menu, if found. Otherwise returns NULL. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___f_i_n_d___m_e_n_u___i_t_e_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__ffiinndd__mmeennuu__iitteemm ********** │ │ │ │ │ bool al_find_menu_item(ALLEGRO_MENU *haystack, uint16_t id, ALLEGRO_MENU │ │ │ │ │ **menu, │ │ │ │ │ int *index) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Searches in the haystack menu for an item with the given id. (Note that this │ │ │ │ │ only represents a literal ID, and cannot be used as an index.) │ │ │ │ │ @@ -575,14 +639,16 @@ │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the default event source used for menu clicks. If a menu was not given │ │ │ │ │ its own event source via _a_l___e_n_a_b_l_e___m_e_n_u___e_v_e_n_t___s_o_u_r_c_e, then it will use this │ │ │ │ │ default source. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___r_e_g_i_s_t_e_r___e_v_e_n_t___s_o_u_r_c_e, _a_l___e_n_a_b_l_e___m_e_n_u___e_v_e_n_t___s_o_u_r_c_e, │ │ │ │ │ _a_l___d_i_s_a_b_l_e___m_e_n_u___e_v_e_n_t___s_o_u_r_c_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__eennaabbllee__mmeennuu__eevveenntt__ssoouurrccee ********** │ │ │ │ │ ALLEGRO_EVENT_SOURCE *al_enable_menu_event_source(ALLEGRO_MENU *menu) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Enables a unique event source for this menu. It and all of its sub-menus will │ │ │ │ │ use this event source. (It is safe to call this multiple times on the same │ │ │ │ │ menu.) │ │ │ │ │ Returns the event source. │ │ │ │ │ @@ -614,14 +680,16 @@ │ │ │ │ │ NNoottee:: Attaching a menu may cause the window as available to your │ │ │ │ │ application to be resized! You should listen for a resize event, │ │ │ │ │ check how much space was lost, and resize the window accordingly if │ │ │ │ │ you want to maintain your window’s prior size. │ │ │ │ │ Returns true if successful. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___c_r_e_a_t_e___m_e_n_u, _a_l___r_e_m_o_v_e___d_i_s_p_l_a_y___m_e_n_u │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__ppooppuupp__mmeennuu ********** │ │ │ │ │ bool al_popup_menu(ALLEGRO_MENU *popup, ALLEGRO_DISPLAY *display) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Displays a context menu next to the mouse cursor. The menu must have been │ │ │ │ │ created with _a_l___c_r_e_a_t_e___p_o_p_u_p___m_e_n_u. It generates events just like a regular │ │ │ │ │ display menu does. It is possible that the menu will be canceled without any │ │ │ │ │ selection being made. │ │ │ │ │ @@ -631,17 +699,21 @@ │ │ │ │ │ Returns true if the context menu was displayed. │ │ │ │ │ NNoottee:: On Linux this function will fail if any of the mouse keys are │ │ │ │ │ held down. I.e. it will only reliably work if you handle it in │ │ │ │ │ ALLEGRO_MOUSE_BUTTON_UP events and even then only if that event │ │ │ │ │ corresponds to the final mouse button that was pressed. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___c_r_e_a_t_e___p_o_p_u_p___m_e_n_u │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ ********** aall__rreemmoovvee__ddiissppllaayy__mmeennuu ********** │ │ │ │ │ ALLEGRO_MENU *al_remove_display_menu(ALLEGRO_DISPLAY *display) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Detaches the menu associated with the display and returns it. The menu can then │ │ │ │ │ be used on a different display. │ │ │ │ │ If you simply want to destroy the active menu, you can call _a_l___s_e_t___d_i_s_p_l_a_y___m_e_n_u │ │ │ │ │ with a NULL menu. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___s_e_t___d_i_s_p_l_a_y___m_e_n_u │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___m_e_n_u_._c │ │ │ │ │ Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/opengl.html │ │ │ │ @@ -233,14 +233,21 @@ │ │ │ │

    Note: the exact extensions exposed depend on how Allegro was │ │ │ │ compiled. It is recommended to use al_have_opengl_extension │ │ │ │ and al_get_opengl_proc_address │ │ │ │ for the most stable experience.

    │ │ │ │ │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_opengl_proc_address

    │ │ │ │ 
    void *al_get_opengl_proc_address(const char *name)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Helper to get the address of an OpenGL symbol

    │ │ │ │

    Example:

    │ │ │ │ @@ -274,14 +281,21 @@ │ │ │ │

    Returns the OpenGL texture id internally used by the given bitmap if │ │ │ │ it uses one, else 0.

    │ │ │ │

    Example:

    │ │ │ │ 
    bitmap = al_load_bitmap("my_texture.png");
│ │ │ │  texture = al_get_opengl_texture(bitmap);
│ │ │ │  if (texture != 0)
│ │ │ │      glBindTexture(GL_TEXTURE_2D, texture);
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_opengl_texture_size

    │ │ │ │ 
    bool al_get_opengl_texture_size(ALLEGRO_BITMAP *bitmap, int *w, int *h)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Retrieves the size of the texture used for the bitmap. This can be │ │ │ │ different from the bitmap size if OpenGL only supports power-of-two │ │ │ │ @@ -348,14 +362,19 @@ │ │ │ │

    This function is a helper to determine whether an OpenGL extension is │ │ │ │ available on the given display or not.

    │ │ │ │

    Example:

    │ │ │ │ 
    bool packedpixels = al_have_opengl_extension("GL_EXT_packed_pixels");
    │ │ │ │

    If packedpixels is true then you can safely use the │ │ │ │ constants related to the packed pixels extension.

    │ │ │ │

    Returns true if the extension is available; false otherwise.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_opengl_version

    │ │ │ │ 
    uint32_t al_get_opengl_version(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the OpenGL or OpenGL ES version number of the client (the │ │ │ │ computer the program is running on), for the current display. “1.0” is │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -78,14 +78,17 @@ │ │ │ │ │ In case you want to manually check for extensions and load function pointers │ │ │ │ │ yourself (say, in case the Allegro developers did not include it yet), you can │ │ │ │ │ use the _a_l___h_a_v_e___o_p_e_n_g_l___e_x_t_e_n_s_i_o_n and _a_l___g_e_t___o_p_e_n_g_l___p_r_o_c___a_d_d_r_e_s_s functions │ │ │ │ │ instead. │ │ │ │ │ NNoottee:: the exact extensions exposed depend on how Allegro was │ │ │ │ │ compiled. It is recommended to use _a_l___h_a_v_e___o_p_e_n_g_l___e_x_t_e_n_s_i_o_n and │ │ │ │ │ _a_l___g_e_t___o_p_e_n_g_l___p_r_o_c___a_d_d_r_e_s_s for the most stable experience. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___o_p_e_n_g_l_._c │ │ │ │ │ + * _e_x___g_l_e_x_t_._c │ │ │ │ │ ************ aall__ggeett__ooppeennggll__pprroocc__aaddddrreessss ************ │ │ │ │ │ void *al_get_opengl_proc_address(const char *name) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Helper to get the address of an OpenGL symbol │ │ │ │ │ Example: │ │ │ │ │ How to get the function ggllMMuullttiiTTeexxCCoooorrdd33ffAARRBB that comes with ARB’s Multitexture │ │ │ │ │ extension: │ │ │ │ │ @@ -113,14 +116,17 @@ │ │ │ │ │ Returns the OpenGL texture id internally used by the given bitmap if it uses │ │ │ │ │ one, else 0. │ │ │ │ │ Example: │ │ │ │ │ bitmap = al_load_bitmap("my_texture.png"); │ │ │ │ │ texture = al_get_opengl_texture(bitmap); │ │ │ │ │ if (texture != 0) │ │ │ │ │ glBindTexture(GL_TEXTURE_2D, texture); │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___o_p_e_n_g_l___p_i_x_e_l___s_h_a_d_e_r_._c │ │ │ │ │ + * _e_x___g_l_d_e_p_t_h_._c │ │ │ │ │ ************ aall__ggeett__ooppeennggll__tteexxttuurree__ssiizzee ************ │ │ │ │ │ bool al_get_opengl_texture_size(ALLEGRO_BITMAP *bitmap, int *w, int *h) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Retrieves the size of the texture used for the bitmap. This can be different │ │ │ │ │ from the bitmap size if OpenGL only supports power-of-two sizes or if it is a │ │ │ │ │ sub-bitmap. │ │ │ │ │ Returns true on success, false on failure. Zero width and height are returned │ │ │ │ │ @@ -161,14 +167,16 @@ │ │ │ │ │ This function is a helper to determine whether an OpenGL extension is available │ │ │ │ │ on the given display or not. │ │ │ │ │ Example: │ │ │ │ │ bool packedpixels = al_have_opengl_extension("GL_EXT_packed_pixels"); │ │ │ │ │ If ppaacckkeeddppiixxeellss is true then you can safely use the constants related to the │ │ │ │ │ packed pixels extension. │ │ │ │ │ Returns true if the extension is available; false otherwise. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___o_p_e_n_g_l___p_i_x_e_l___s_h_a_d_e_r_._c │ │ │ │ │ ************ aall__ggeett__ooppeennggll__vveerrssiioonn ************ │ │ │ │ │ uint32_t al_get_opengl_version(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the OpenGL or OpenGL ES version number of the client (the computer the │ │ │ │ │ program is running on), for the current display. “1.0” is returned as │ │ │ │ │ 0x01000000, “1.2.1” is returned as 0x01020100, and “1.2.2” as 0x01020200, etc. │ │ │ │ │ A valid OpenGL context must exist for this function to work, which means you │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/path.html │ │ │ │ @@ -240,14 +240,23 @@ │ │ │ │ followed by a directory separator and is neither “.” nor “..”, is │ │ │ │ treated as the last directory name in the path. Otherwise the last │ │ │ │ component is treated as the filename. The string may be NULL for an │ │ │ │ empty path.

    │ │ │ │

    See also: al_create_path_for_directory, │ │ │ │ al_destroy_path

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_create_path_for_directory

    │ │ │ │ 
    ALLEGRO_PATH *al_create_path_for_directory(const char *str)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    This is the same as al_create_path, but interprets the │ │ │ │ @@ -259,143 +268,228 @@ │ │ │ │ 

    void al_destroy_path(ALLEGRO_PATH *path)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Free a path structure. Does nothing if passed NULL.

    │ │ │ │

    See also: al_create_path, al_create_path_for_directory

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_clone_path

    │ │ │ │ 
    ALLEGRO_PATH *al_clone_path(const ALLEGRO_PATH *path)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Clones an ALLEGRO_PATH structure. Returns NULL on failure.

    │ │ │ │

    See also: al_destroy_path

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_join_paths

    │ │ │ │ 
    bool al_join_paths(ALLEGRO_PATH *path, const ALLEGRO_PATH *tail)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Concatenate two path structures. The first path structure is │ │ │ │ modified. If ‘tail’ is an absolute path, this function does nothing.

    │ │ │ │

    If ‘tail’ is a relative path, all of its directory components will be │ │ │ │ appended to ‘path’. tail’s filename will also overwrite path’s filename, │ │ │ │ even if it is just the empty string.

    │ │ │ │

    Tail’s drive is ignored.

    │ │ │ │

    Returns true if ‘tail’ was a relative path and so concatenated to │ │ │ │ ‘path’, otherwise returns false.

    │ │ │ │

    See also: al_rebase_path

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_rebase_path

    │ │ │ │ 
    bool al_rebase_path(const ALLEGRO_PATH *head, ALLEGRO_PATH *tail)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Concatenate two path structures, modifying the second path structure. │ │ │ │ If tail is an absolute path, this function does nothing. │ │ │ │ Otherwise, the drive and path components in head are inserted │ │ │ │ at the start of tail.

    │ │ │ │

    For example, if head is “/anchor/” and tail is │ │ │ │ “data/file.ext”, then after the call tail becomes │ │ │ │ “/anchor/data/file.ext”.

    │ │ │ │

    See also: al_join_paths

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_path_drive

    │ │ │ │ 
    const char *al_get_path_drive(const ALLEGRO_PATH *path)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the drive letter on a path, or the empty string if there is │ │ │ │ none.

    │ │ │ │

    The “drive letter” is only used on Windows, and is usually a string │ │ │ │ like “c:”, but may be something like “\\Computer Name” in the case of │ │ │ │ UNC (Uniform Naming Convention) syntax.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_path_num_components

    │ │ │ │ 
    int al_get_path_num_components(const ALLEGRO_PATH *path)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the number of directory components in a path.

    │ │ │ │

    The directory components do not include the final part of a path (the │ │ │ │ filename).

    │ │ │ │

    See also: al_get_path_component

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_path_component

    │ │ │ │ 
    const char *al_get_path_component(const ALLEGRO_PATH *path, int i)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the i’th directory component of a path, counting from zero. If │ │ │ │ the index is negative then count from the right, i.e. -1 refers to the │ │ │ │ last path component. It is an error to pass an index which is out of │ │ │ │ bounds.

    │ │ │ │

    See also: al_get_path_num_components, │ │ │ │ al_get_path_tail

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_path_tail

    │ │ │ │ 
    const char *al_get_path_tail(const ALLEGRO_PATH *path)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the last directory component, or NULL if there are no │ │ │ │ directory components.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_path_filename

    │ │ │ │ 
    const char *al_get_path_filename(const ALLEGRO_PATH *path)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the filename part of the path, or the empty string if there is │ │ │ │ none.

    │ │ │ │

    The returned pointer is valid only until the filename part of the │ │ │ │ path is modified in any way, or until the path is destroyed.

    │ │ │ │

    See also: al_get_path_basename, al_get_path_extension, al_get_path_component

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_path_basename

    │ │ │ │ 
    const char *al_get_path_basename(const ALLEGRO_PATH *path)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the basename, i.e. filename with the extension removed. If the │ │ │ │ filename doesn’t have an extension, the whole filename is the basename. │ │ │ │ If there is no filename part then the empty string is returned.

    │ │ │ │

    The returned pointer is valid only until the filename part of the │ │ │ │ path is modified in any way, or until the path is destroyed.

    │ │ │ │

    See also: al_get_path_filename, al_get_path_extension

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_path_extension

    │ │ │ │ 
    const char *al_get_path_extension(const ALLEGRO_PATH *path)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return a pointer to the start of the extension of the filename, │ │ │ │ i.e. everything from the final dot (‘.’) character onwards. If no dot │ │ │ │ exists, returns an empty string.

    │ │ │ │

    The returned pointer is valid only until the filename part of the │ │ │ │ path is modified in any way, or until the path is destroyed.

    │ │ │ │

    See also: al_get_path_filename, al_get_path_basename

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_path_drive

    │ │ │ │ 
    void al_set_path_drive(ALLEGRO_PATH *path, const char *drive)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Set the drive string on a path. The drive may be NULL, which is │ │ │ │ equivalent to setting the drive string to the empty string.

    │ │ │ │

    See also: al_get_path_drive

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_append_path_component

    │ │ │ │ 
    void al_append_path_component(ALLEGRO_PATH *path, const char *s)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Append a directory component.

    │ │ │ │

    See also: al_insert_path_component

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_insert_path_component

    │ │ │ │ 
    void al_insert_path_component(ALLEGRO_PATH *path, int i, const char *s)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Insert a directory component at index i. If the index is negative │ │ │ │ then count from the right, i.e. -1 refers to the last path │ │ │ │ @@ -404,57 +498,86 @@ │ │ │ │ <= i <= al_get_path_num_components(path).

    │ │ │ │

    See also: al_append_path_component, │ │ │ │ al_replace_path_component, │ │ │ │ al_remove_path_component

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_replace_path_component

    │ │ │ │ 
    void al_replace_path_component(ALLEGRO_PATH *path, int i, const char *s)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Replace the i’th directory component by another string. If the index │ │ │ │ is negative then count from the right, i.e. -1 refers to the last path │ │ │ │ component. It is an error to pass an index which is out of bounds.

    │ │ │ │

    See also: al_insert_path_component, │ │ │ │ al_remove_path_component

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_remove_path_component

    │ │ │ │ 
    void al_remove_path_component(ALLEGRO_PATH *path, int i)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Delete the i’th directory component. If the index is negative then │ │ │ │ count from the right, i.e. -1 refers to the last path component. It is │ │ │ │ an error to pass an index which is out of bounds.

    │ │ │ │

    See also: al_insert_path_component, │ │ │ │ al_replace_path_component, │ │ │ │ al_drop_path_tail

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_drop_path_tail

    │ │ │ │ 
    void al_drop_path_tail(ALLEGRO_PATH *path)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Remove the last directory component, if any.

    │ │ │ │

    See also: al_remove_path_component

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_path_filename

    │ │ │ │ 
    void al_set_path_filename(ALLEGRO_PATH *path, const char *filename)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Set the optional filename part of the path. The filename may be NULL, │ │ │ │ which is equivalent to setting the filename to the empty string.

    │ │ │ │

    See also: al_set_path_extension, al_get_path_filename

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_path_extension

    │ │ │ │ 
    bool al_set_path_extension(ALLEGRO_PATH *path, char const *extension)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Replaces the extension of the path with the given one, i.e. replaces │ │ │ │ everything from the final dot (‘.’) character onwards, including the │ │ │ │ @@ -462,14 +585,19 @@ │ │ │ │ appended. Usually the new extension you supply should include a leading │ │ │ │ dot.

    │ │ │ │

    Returns false if the path contains no filename part, i.e. the │ │ │ │ filename part is the empty string.

    │ │ │ │

    See also: al_set_path_filename, al_get_path_extension

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_path_cstr

    │ │ │ │ 
    const char *al_path_cstr(const ALLEGRO_PATH *path, char delim)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Convert a path to its string representation, i.e. optional drive, │ │ │ │ followed by directory components separated by ‘delim’, followed by an │ │ │ │ @@ -477,14 +605,23 @@ │ │ │ │

    To use the current native path separator, use ALLEGRO_NATIVE_PATH_SEP │ │ │ │ for ‘delim’.

    │ │ │ │

    The returned pointer is valid only until the path is modified in any │ │ │ │ way, or until the path is destroyed. This returns a null-terminated │ │ │ │ string. If you need an ALLEGRO_USTR instead, use al_path_ustr.

    │ │ │ │

    See also: al_path_ustr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_path_ustr

    │ │ │ │ 
    const ALLEGRO_USTR *al_path_ustr(const ALLEGRO_PATH *path, char delim)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Convert a path to its string representation, i.e. optional drive, │ │ │ │ followed by directory components separated by ‘delim’, followed by an │ │ │ │ @@ -504,14 +641,21 @@ │ │ │ │ Code

    │ │ │ │

    Removes any leading ‘..’ directory components in absolute paths. │ │ │ │ Removes all ‘.’ directory components.

    │ │ │ │

    Note that this does not collapse “x/../y” sections into “y”. │ │ │ │ This is by design. If “/foo” on your system is a symlink to “/bar/baz”, │ │ │ │ then “/foo/../quux” is actually “/bar/quux”, not “/quux” as a naive │ │ │ │ removal of “..” components would give you.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    │ │ │ │ Allegro version 5.2.10 │ │ │ │ - Last updated: 2025-01-09 13:52:42 UTC │ │ │ │

    │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -79,170 +79,228 @@ │ │ │ │ │ ALLEGRO_PATH *al_create_path(const char *str) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Create a path structure from a string. The last component, if it is followed by │ │ │ │ │ a directory separator and is neither “.” nor “..”, is treated as the last │ │ │ │ │ directory name in the path. Otherwise the last component is treated as the │ │ │ │ │ filename. The string may be NULL for an empty path. │ │ │ │ │ See also: _a_l___c_r_e_a_t_e___p_a_t_h___f_o_r___d_i_r_e_c_t_o_r_y, _a_l___d_e_s_t_r_o_y___p_a_t_h │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h_._c │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ************ aall__ccrreeaattee__ppaatthh__ffoorr__ddiirreeccttoorryy ************ │ │ │ │ │ ALLEGRO_PATH *al_create_path_for_directory(const char *str) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This is the same as _a_l___c_r_e_a_t_e___p_a_t_h, but interprets the passed string as a │ │ │ │ │ directory path. The filename component of the returned path will always be │ │ │ │ │ empty. │ │ │ │ │ See also: _a_l___c_r_e_a_t_e___p_a_t_h, _a_l___d_e_s_t_r_o_y___p_a_t_h │ │ │ │ │ ************ aall__ddeessttrrooyy__ppaatthh ************ │ │ │ │ │ void al_destroy_path(ALLEGRO_PATH *path) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Free a path structure. Does nothing if passed NULL. │ │ │ │ │ See also: _a_l___c_r_e_a_t_e___p_a_t_h, _a_l___c_r_e_a_t_e___p_a_t_h___f_o_r___d_i_r_e_c_t_o_r_y │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___g_e_t___p_a_t_h_._c │ │ │ │ │ + * _e_x___p_a_t_h_._c │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ ************ aall__cclloonnee__ppaatthh ************ │ │ │ │ │ ALLEGRO_PATH *al_clone_path(const ALLEGRO_PATH *path) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Clones an ALLEGRO_PATH structure. Returns NULL on failure. │ │ │ │ │ See also: _a_l___d_e_s_t_r_o_y___p_a_t_h │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h_._c │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ ************ aall__jjooiinn__ppaatthhss ************ │ │ │ │ │ bool al_join_paths(ALLEGRO_PATH *path, const ALLEGRO_PATH *tail) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Concatenate two path structures. The first path structure is modified. If │ │ │ │ │ ‘tail’ is an absolute path, this function does nothing. │ │ │ │ │ If ‘tail’ is a relative path, all of its directory components will be appended │ │ │ │ │ to ‘path’. tail’s filename will also overwrite path’s filename, even if it is │ │ │ │ │ just the empty string. │ │ │ │ │ Tail’s drive is ignored. │ │ │ │ │ Returns true if ‘tail’ was a relative path and so concatenated to ‘path’, │ │ │ │ │ otherwise returns false. │ │ │ │ │ See also: _a_l___r_e_b_a_s_e___p_a_t_h │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ ************ aall__rreebbaassee__ppaatthh ************ │ │ │ │ │ bool al_rebase_path(const ALLEGRO_PATH *head, ALLEGRO_PATH *tail) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Concatenate two path structures, modifying the second path structure. If ttaaiill │ │ │ │ │ is an absolute path, this function does nothing. Otherwise, the drive and path │ │ │ │ │ components in hheeaadd are inserted at the start of ttaaiill. │ │ │ │ │ For example, if hheeaadd is “/anchor/” and ttaaiill is “data/file.ext”, then after the │ │ │ │ │ call ttaaiill becomes “/anchor/data/file.ext”. │ │ │ │ │ See also: _a_l___j_o_i_n___p_a_t_h_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ************ aall__ggeett__ppaatthh__ddrriivvee ************ │ │ │ │ │ const char *al_get_path_drive(const ALLEGRO_PATH *path) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the drive letter on a path, or the empty string if there is none. │ │ │ │ │ The “drive letter” is only used on Windows, and is usually a string like “c:”, │ │ │ │ │ but may be something like “\\Computer Name” in the case of UNC (Uniform Naming │ │ │ │ │ Convention) syntax. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h_._c │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ ************ aall__ggeett__ppaatthh__nnuumm__ccoommppoonneennttss ************ │ │ │ │ │ int al_get_path_num_components(const ALLEGRO_PATH *path) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the number of directory components in a path. │ │ │ │ │ The directory components do not include the final part of a path (the │ │ │ │ │ filename). │ │ │ │ │ See also: _a_l___g_e_t___p_a_t_h___c_o_m_p_o_n_e_n_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h_._c │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ ************ aall__ggeett__ppaatthh__ccoommppoonneenntt ************ │ │ │ │ │ const char *al_get_path_component(const ALLEGRO_PATH *path, int i) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the i’th directory component of a path, counting from zero. If the index │ │ │ │ │ is negative then count from the right, i.e. -1 refers to the last path │ │ │ │ │ component. It is an error to pass an index which is out of bounds. │ │ │ │ │ See also: _a_l___g_e_t___p_a_t_h___n_u_m___c_o_m_p_o_n_e_n_t_s, _a_l___g_e_t___p_a_t_h___t_a_i_l │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h_._c │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ************ aall__ggeett__ppaatthh__ttaaiill ************ │ │ │ │ │ const char *al_get_path_tail(const ALLEGRO_PATH *path) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the last directory component, or NULL if there are no directory │ │ │ │ │ components. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ ************ aall__ggeett__ppaatthh__ffiilleennaammee ************ │ │ │ │ │ const char *al_get_path_filename(const ALLEGRO_PATH *path) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the filename part of the path, or the empty string if there is none. │ │ │ │ │ The returned pointer is valid only until the filename part of the path is │ │ │ │ │ modified in any way, or until the path is destroyed. │ │ │ │ │ See also: _a_l___g_e_t___p_a_t_h___b_a_s_e_n_a_m_e, _a_l___g_e_t___p_a_t_h___e_x_t_e_n_s_i_o_n, _a_l___g_e_t___p_a_t_h___c_o_m_p_o_n_e_n_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h_._c │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ ************ aall__ggeett__ppaatthh__bbaasseennaammee ************ │ │ │ │ │ const char *al_get_path_basename(const ALLEGRO_PATH *path) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the basename, i.e. filename with the extension removed. If the filename │ │ │ │ │ doesn’t have an extension, the whole filename is the basename. If there is no │ │ │ │ │ filename part then the empty string is returned. │ │ │ │ │ The returned pointer is valid only until the filename part of the path is │ │ │ │ │ modified in any way, or until the path is destroyed. │ │ │ │ │ See also: _a_l___g_e_t___p_a_t_h___f_i_l_e_n_a_m_e, _a_l___g_e_t___p_a_t_h___e_x_t_e_n_s_i_o_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ ************ aall__ggeett__ppaatthh__eexxtteennssiioonn ************ │ │ │ │ │ const char *al_get_path_extension(const ALLEGRO_PATH *path) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return a pointer to the start of the extension of the filename, i.e. everything │ │ │ │ │ from the final dot (‘.’) character onwards. If no dot exists, returns an empty │ │ │ │ │ string. │ │ │ │ │ The returned pointer is valid only until the filename part of the path is │ │ │ │ │ modified in any way, or until the path is destroyed. │ │ │ │ │ See also: _a_l___g_e_t___p_a_t_h___f_i_l_e_n_a_m_e, _a_l___g_e_t___p_a_t_h___b_a_s_e_n_a_m_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ + * _e_x___p_h_y_s_f_s_._c │ │ │ │ │ ************ aall__sseett__ppaatthh__ddrriivvee ************ │ │ │ │ │ void al_set_path_drive(ALLEGRO_PATH *path, const char *drive) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the drive string on a path. The drive may be NULL, which is equivalent to │ │ │ │ │ setting the drive string to the empty string. │ │ │ │ │ See also: _a_l___g_e_t___p_a_t_h___d_r_i_v_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ ************ aall__aappppeenndd__ppaatthh__ccoommppoonneenntt ************ │ │ │ │ │ void al_append_path_component(ALLEGRO_PATH *path, const char *s) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Append a directory component. │ │ │ │ │ See also: _a_l___i_n_s_e_r_t___p_a_t_h___c_o_m_p_o_n_e_n_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ ************ aall__iinnsseerrtt__ppaatthh__ccoommppoonneenntt ************ │ │ │ │ │ void al_insert_path_component(ALLEGRO_PATH *path, int i, const char *s) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Insert a directory component at index i. If the index is negative then count │ │ │ │ │ from the right, i.e. -1 refers to the last path component. │ │ │ │ │ It is an error to pass an index i which is not within these bounds: 0 <= i <= │ │ │ │ │ al_get_path_num_components(path). │ │ │ │ │ See also: _a_l___a_p_p_e_n_d___p_a_t_h___c_o_m_p_o_n_e_n_t, _a_l___r_e_p_l_a_c_e___p_a_t_h___c_o_m_p_o_n_e_n_t, │ │ │ │ │ _a_l___r_e_m_o_v_e___p_a_t_h___c_o_m_p_o_n_e_n_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ ************ aall__rreeppllaaccee__ppaatthh__ccoommppoonneenntt ************ │ │ │ │ │ void al_replace_path_component(ALLEGRO_PATH *path, int i, const char *s) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Replace the i’th directory component by another string. If the index is │ │ │ │ │ negative then count from the right, i.e. -1 refers to the last path component. │ │ │ │ │ It is an error to pass an index which is out of bounds. │ │ │ │ │ See also: _a_l___i_n_s_e_r_t___p_a_t_h___c_o_m_p_o_n_e_n_t, _a_l___r_e_m_o_v_e___p_a_t_h___c_o_m_p_o_n_e_n_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ ************ aall__rreemmoovvee__ppaatthh__ccoommppoonneenntt ************ │ │ │ │ │ void al_remove_path_component(ALLEGRO_PATH *path, int i) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Delete the i’th directory component. If the index is negative then count from │ │ │ │ │ the right, i.e. -1 refers to the last path component. It is an error to pass an │ │ │ │ │ index which is out of bounds. │ │ │ │ │ See also: _a_l___i_n_s_e_r_t___p_a_t_h___c_o_m_p_o_n_e_n_t, _a_l___r_e_p_l_a_c_e___p_a_t_h___c_o_m_p_o_n_e_n_t, │ │ │ │ │ _a_l___d_r_o_p___p_a_t_h___t_a_i_l │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___c_h_a_i_n_._c_p_p │ │ │ │ │ ************ aall__ddrroopp__ppaatthh__ttaaiill ************ │ │ │ │ │ void al_drop_path_tail(ALLEGRO_PATH *path) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Remove the last directory component, if any. │ │ │ │ │ See also: _a_l___r_e_m_o_v_e___p_a_t_h___c_o_m_p_o_n_e_n_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ ************ aall__sseett__ppaatthh__ffiilleennaammee ************ │ │ │ │ │ void al_set_path_filename(ALLEGRO_PATH *path, const char *filename) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Set the optional filename part of the path. The filename may be NULL, which is │ │ │ │ │ equivalent to setting the filename to the empty string. │ │ │ │ │ See also: _a_l___s_e_t___p_a_t_h___e_x_t_e_n_s_i_o_n, _a_l___g_e_t___p_a_t_h___f_i_l_e_n_a_m_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ + * _e_x___a_n_d_r_o_i_d_._c │ │ │ │ │ ************ aall__sseett__ppaatthh__eexxtteennssiioonn ************ │ │ │ │ │ bool al_set_path_extension(ALLEGRO_PATH *path, char const *extension) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Replaces the extension of the path with the given one, i.e. replaces everything │ │ │ │ │ from the final dot (‘.’) character onwards, including the dot. If the filename │ │ │ │ │ of the path has no extension, the given one is appended. Usually the new │ │ │ │ │ extension you supply should include a leading dot. │ │ │ │ │ Returns false if the path contains no filename part, i.e. the filename part is │ │ │ │ │ the empty string. │ │ │ │ │ See also: _a_l___s_e_t___p_a_t_h___f_i_l_e_n_a_m_e, _a_l___g_e_t___p_a_t_h___e_x_t_e_n_s_i_o_n │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ ************ aall__ppaatthh__ccssttrr ************ │ │ │ │ │ const char *al_path_cstr(const ALLEGRO_PATH *path, char delim) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Convert a path to its string representation, i.e. optional drive, followed by │ │ │ │ │ directory components separated by ‘delim’, followed by an optional filename. │ │ │ │ │ To use the current native path separator, use ALLEGRO_NATIVE_PATH_SEP for │ │ │ │ │ ‘delim’. │ │ │ │ │ The returned pointer is valid only until the path is modified in any way, or │ │ │ │ │ until the path is destroyed. This returns a null-terminated string. If you need │ │ │ │ │ an ALLEGRO_USTR instead, use _a_l___p_a_t_h___u_s_t_r. │ │ │ │ │ See also: _a_l___p_a_t_h___u_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___g_e_t___p_a_t_h_._c │ │ │ │ │ + * _e_x___p_a_t_h_._c │ │ │ │ │ + * _e_x___f_i_l_e___s_l_i_c_e_._c │ │ │ │ │ ************ aall__ppaatthh__uussttrr ************ │ │ │ │ │ const ALLEGRO_USTR *al_path_ustr(const ALLEGRO_PATH *path, char delim) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Convert a path to its string representation, i.e. optional drive, followed by │ │ │ │ │ directory components separated by ‘delim’, followed by an optional filename. │ │ │ │ │ To use the current native path separator, use ALLEGRO_NATIVE_PATH_SEP for │ │ │ │ │ ‘delim’. │ │ │ │ │ @@ -256,8 +314,11 @@ │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Removes any leading ‘..’ directory components in absolute paths. Removes all │ │ │ │ │ ‘.’ directory components. │ │ │ │ │ Note that this does nnoott collapse “x/../y” sections into “y”. This is by design. │ │ │ │ │ If “/foo” on your system is a symlink to “/bar/baz”, then “/foo/../quux” is │ │ │ │ │ actually “/bar/quux”, not “/quux” as a naive removal of “..” components would │ │ │ │ │ give you. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_a_t_h_._c │ │ │ │ │ + * _e_x___p_a_t_h___t_e_s_t_._c │ │ │ │ │ Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/physfs.html │ │ │ │ @@ -224,19 +224,27 @@ │ │ │ │
    │ │ │ │

    Note: PhysFS does not support the text-mode reading and │ │ │ │ writing, which means that Windows-style newlines will not be │ │ │ │ preserved.

    │ │ │ │
    │ │ │ │

    See also: al_set_new_file_interface.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_allegro_physfs_version

    │ │ │ │ 
    uint32_t al_get_allegro_physfs_version(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

    │ │ │ │ - │ │ │ │ +

    │ │ │ │ +Allegro version 5.2.10 │ │ │ │ + - Last updated: 2025-01-09 13:52:42 UTC │ │ │ │ +

    │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -70,12 +70,15 @@ │ │ │ │ │ _a_l___r_e_s_t_o_r_e___s_t_a_t_e. │ │ │ │ │ NNoottee:: due to an oversight, this function differs from │ │ │ │ │ _a_l___s_e_t___n_e_w___f_i_l_e___i_n_t_e_r_f_a_c_e and _a_l___s_e_t___s_t_a_n_d_a_r_d___f_i_l_e___i_n_t_e_r_f_a_c_e which │ │ │ │ │ only alter the current _A_L_L_E_G_R_O___F_I_L_E___I_N_T_E_R_F_A_C_E. │ │ │ │ │ NNoottee:: PhysFS does not support the text-mode reading and writing, │ │ │ │ │ which means that Windows-style newlines will not be preserved. │ │ │ │ │ See also: _a_l___s_e_t___n_e_w___f_i_l_e___i_n_t_e_r_f_a_c_e. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_h_y_s_f_s_._c │ │ │ │ │ ************ aall__ggeett__aalllleeggrroo__pphhyyssffss__vveerrssiioonn ************ │ │ │ │ │ uint32_t al_get_allegro_physfs_version(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the (compiled) version of the addon, in the same format as │ │ │ │ │ _a_l___g_e_t___a_l_l_e_g_r_o___v_e_r_s_i_o_n. │ │ │ │ │ +Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/platform.html │ │ │ │ @@ -226,14 +226,19 @@ │ │ │ │

    al_get_win_window_handle

    │ │ │ │ 
    HWND al_get_win_window_handle(ALLEGRO_DISPLAY *display)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the handle to the window that the passed display is │ │ │ │ using.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_win_add_window_callback

    │ │ │ │ 
    bool al_win_add_window_callback(ALLEGRO_DISPLAY *display,
│ │ │ │     bool (*callback)(ALLEGRO_DISPLAY *display, UINT message, WPARAM wparam,
│ │ │ │     LPARAM lparam, LRESULT *result, void *userdata), void *userdata)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -326,17 +331,17 @@ │ │ │ │ │ │ │ │

    Since: 5.1.2

    │ │ │ │

    Examples:

    │ │ │ │ │ │ │ │

    al_android_set_apk_fs_interface

    │ │ │ │ 
    void al_android_set_apk_fs_interface(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -466,14 +471,19 @@ │ │ │ │ you can set an icon before calling al_create_display. This works by │ │ │ │ setting the icon before XMapWindow.

    │ │ │ │

    Since: 5.2.3

    │ │ │ │
    │ │ │ │

    Unstable │ │ │ │ API: New API.

    │ │ │ │
    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    │ │ │ │ Allegro version 5.2.10 │ │ │ │ - Last updated: 2025-01-09 13:52:42 UTC │ │ │ │

    │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -66,14 +66,16 @@ │ │ │ │ │ ************ WWiinnddoowwss ************ │ │ │ │ │ These functions are declared in the following header file: │ │ │ │ │ #include │ │ │ │ │ ********** aall__ggeett__wwiinn__wwiinnddooww__hhaannddllee ********** │ │ │ │ │ HWND al_get_win_window_handle(ALLEGRO_DISPLAY *display) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the handle to the window that the passed display is using. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___o_g_r_e_3_d_._c_p_p │ │ │ │ │ ********** aall__wwiinn__aadddd__wwiinnddooww__ccaallllbbaacckk ********** │ │ │ │ │ bool al_win_add_window_callback(ALLEGRO_DISPLAY *display, │ │ │ │ │ bool (*callback)(ALLEGRO_DISPLAY *display, UINT message, WPARAM wparam, │ │ │ │ │ LPARAM lparam, LRESULT *result, void *userdata), void *userdata) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ The specified callback function will intercept the window’s message before │ │ │ │ │ Allegro processes it. If the callback function consumes the event, then it │ │ │ │ │ @@ -134,16 +136,16 @@ │ │ │ │ │ This function will set up a custom _A_L_L_E_G_R_O___F_I_L_E___I_N_T_E_R_F_A_C_E that makes all future │ │ │ │ │ calls of _a_l___f_o_p_e_n read from the applicatons’s APK file. │ │ │ │ │ NNoottee:: Currently, access to the APK file after calling this function │ │ │ │ │ is read only. │ │ │ │ │ Since: 5.1.2 │ │ │ │ │ Examples: │ │ │ │ │ * _c_o_m_m_o_n_._c │ │ │ │ │ - * _e_x___n_a_t_i_v_e___f_i_l_e_c_h_o_o_s_e_r_._c │ │ │ │ │ * _e_x___a_n_d_r_o_i_d_._c │ │ │ │ │ + * _e_x___n_a_t_i_v_e___f_i_l_e_c_h_o_o_s_e_r_._c │ │ │ │ │ ********** aall__aannddrrooiidd__sseett__aappkk__ffss__iinntteerrffaaccee ********** │ │ │ │ │ void al_android_set_apk_fs_interface(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This function will set up a custom _A_L_L_E_G_R_O___F_S___I_N_T_E_R_F_A_C_E which allows working │ │ │ │ │ within the APK filesystem. The filesystem root is your assets directory and │ │ │ │ │ there is read-only access to all files within. │ │ │ │ │ NNoottee:: Some things like querying file size or attributes are not │ │ │ │ │ @@ -232,8 +234,10 @@ │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ On some window managers (notably Ubuntu’s Unity) al_set_display_icon doesn’t │ │ │ │ │ work and you need to use a .desktop file. But with this function you can set an │ │ │ │ │ icon before calling al_create_display. This works by setting the icon before │ │ │ │ │ XMapWindow. │ │ │ │ │ Since: 5.2.3 │ │ │ │ │ _UU_nn_ss_tt_aa_bb_ll_ee_ _AA_PP_II:: New API. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___i_c_o_n_2_._c │ │ │ │ │ Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/primitives.html │ │ │ │ @@ -343,14 +343,23 @@ │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Initializes the primitives addon.

    │ │ │ │

    Returns: True on success, false on failure.

    │ │ │ │

    See also: al_shutdown_primitives_addon

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_is_primitives_addon_initialized

    │ │ │ │ 
    bool al_is_primitives_addon_initialized(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true if the primitives addon is initialized, otherwise │ │ │ │ @@ -474,14 +483,23 @@ │ │ │ │

  • x1, y1, x2, y2 - Start and end points of the line
    • │ │ │ │
  • color - Color of the line
    • │ │ │ │
  • thickness - Thickness of the line, pass <= 0 to draw │ │ │ │ hairline lines
    • │ │ │ │ │ │ │ │

    See also: al_draw_soft_line

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_triangle

    │ │ │ │ 
    void al_draw_triangle(float x1, float y1, float x2, float y2,
│ │ │ │     float x3, float y3, ALLEGRO_COLOR color, float thickness)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws an outlined triangle.

    │ │ │ │ @@ -492,28 +510,38 @@ │ │ │ │
  • thickness - Thickness of the lines, pass <= 0 to │ │ │ │ draw hairline lines
    • │ │ │ │ │ │ │ │

    See also: al_draw_filled_triangle, │ │ │ │ al_draw_soft_triangle

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_prim.c
      • │ │ │ │ +
    │ │ │ │

    al_draw_filled_triangle

    │ │ │ │ 
    void al_draw_filled_triangle(float x1, float y1, float x2, float y2,
│ │ │ │     float x3, float y3, ALLEGRO_COLOR color)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws a filled triangle.

    │ │ │ │

    Parameters:

    │ │ │ │
      │ │ │ │
    • x1, y1, x2, y2, x3, y3 - Three points of the triangle
      • │ │ │ │
    • color - Color of the triangle
      • │ │ │ │
    │ │ │ │

    See also: al_draw_triangle

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_prim.c
      • │ │ │ │ +
    │ │ │ │

    al_draw_rectangle

    │ │ │ │ 
    void al_draw_rectangle(float x1, float y1, float x2, float y2,
│ │ │ │     ALLEGRO_COLOR color, float thickness)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws an outlined rectangle.

    │ │ │ │ @@ -525,14 +553,23 @@ │ │ │ │
  • thickness - Thickness of the lines, pass <= 0 to │ │ │ │ draw hairline lines
    • │ │ │ │ │ │ │ │

    See also: al_draw_filled_rectangle, │ │ │ │ al_draw_rounded_rectangle

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_filled_rectangle

    │ │ │ │ 
    void al_draw_filled_rectangle(float x1, float y1, float x2, float y2,
│ │ │ │     ALLEGRO_COLOR color)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws a filled rectangle.

    │ │ │ │ @@ -541,14 +578,23 @@ │ │ │ │
  • x1, y1, x2, y2 - Upper left and lower right points of the │ │ │ │ rectangle
    • │ │ │ │
  • color - Color of the rectangle
    • │ │ │ │ │ │ │ │

    See also: al_draw_rectangle, al_draw_filled_rounded_rectangle

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_rounded_rectangle

    │ │ │ │ 
    void al_draw_rounded_rectangle(float x1, float y1, float x2, float y2,
│ │ │ │     float rx, float ry, ALLEGRO_COLOR color, float thickness)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws an outlined rounded rectangle.

    │ │ │ │ @@ -560,14 +606,23 @@ │ │ │ │
  • rx, ry - The radii of the round
    • │ │ │ │
  • thickness - Thickness of the lines, pass <= 0 to │ │ │ │ draw hairline lines
    • │ │ │ │ │ │ │ │

    See also: al_draw_filled_rounded_rectangle, │ │ │ │ al_draw_rectangle

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_filled_rounded_rectangle

    │ │ │ │ 
    void al_draw_filled_rounded_rectangle(float x1, float y1, float x2, float y2,
│ │ │ │     float rx, float ry, ALLEGRO_COLOR color)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -579,14 +634,23 @@ │ │ │ │
  • color - Color of the rectangle
    • │ │ │ │
  • rx, ry - The radii of the round
    • │ │ │ │ │ │ │ │

    See also: al_draw_rounded_rectangle, │ │ │ │ al_draw_filled_rectangle

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_calculate_arc

    │ │ │ │ 
    void al_calculate_arc(float* dest, int stride, float cx, float cy,
│ │ │ │     float rx, float ry, float start_theta, float delta_theta, float thickness,
│ │ │ │     int num_points)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -647,14 +711,19 @@ │ │ │ │ number to switch direction) │ │ │ │
  • thickness - Thickness of the arc
    • │ │ │ │
  • num_points - The number of points to calculate
    • │ │ │ │ │ │ │ │

    See also: al_draw_arc, al_calculate_spline, al_calculate_ribbon

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_pieslice

    │ │ │ │ 
    void al_draw_pieslice(float cx, float cy, float r, float start_theta,
│ │ │ │     float delta_theta, ALLEGRO_COLOR color, float thickness)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws a pieslice (outlined circular sector).

    │ │ │ │ @@ -669,14 +738,19 @@ │ │ │ │ negative number to switch direction) │ │ │ │
  • thickness - Thickness of the circle, pass <= 0 to │ │ │ │ draw hairline pieslice
    • │ │ │ │ │ │ │ │

    Since: 5.0.6, 5.1.0

    │ │ │ │

    See also: al_draw_filled_pieslice

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_prim.c
      • │ │ │ │ +
    │ │ │ │

    al_draw_filled_pieslice

    │ │ │ │ 
    void al_draw_filled_pieslice(float cx, float cy, float r, float start_theta,
│ │ │ │     float delta_theta, ALLEGRO_COLOR color)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws a filled pieslice (filled circular sector).

    │ │ │ │ @@ -689,14 +763,19 @@ │ │ │ │ radians │ │ │ │
  • delta_theta - Angular span of the pieslice in radians (pass a │ │ │ │ negative number to switch direction)
    • │ │ │ │ │ │ │ │

    Since: 5.0.6, 5.1.0

    │ │ │ │

    See also: al_draw_pieslice

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_prim.c
      • │ │ │ │ +
    │ │ │ │

    al_draw_ellipse

    │ │ │ │ 
    void al_draw_ellipse(float cx, float cy, float rx, float ry,
│ │ │ │     ALLEGRO_COLOR color, float thickness)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws an outlined ellipse.

    │ │ │ │ @@ -707,14 +786,21 @@ │ │ │ │
  • color - Color of the ellipse
    • │ │ │ │
  • thickness - Thickness of the ellipse, pass <= 0 to │ │ │ │ draw a hairline ellipse
    • │ │ │ │ │ │ │ │

    See also: al_draw_filled_ellipse, │ │ │ │ al_draw_circle

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_filled_ellipse

    │ │ │ │ 
    void al_draw_filled_ellipse(float cx, float cy, float rx, float ry,
│ │ │ │     ALLEGRO_COLOR color)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws a filled ellipse.

    │ │ │ │ @@ -723,14 +809,21 @@ │ │ │ │
  • cx, cy - Center of the ellipse
    • │ │ │ │
  • rx, ry - Radii of the ellipse
    • │ │ │ │
  • color - Color of the ellipse
    • │ │ │ │ │ │ │ │

    See also: al_draw_ellipse, al_draw_filled_circle

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_circle

    │ │ │ │ 
    void al_draw_circle(float cx, float cy, float r, ALLEGRO_COLOR color,
│ │ │ │     float thickness)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws an outlined circle.

    │ │ │ │ @@ -741,14 +834,21 @@ │ │ │ │
  • color - Color of the circle
    • │ │ │ │
  • thickness - Thickness of the circle, pass <= 0 to │ │ │ │ draw a hairline circle
    • │ │ │ │ │ │ │ │

    See also: al_draw_filled_circle, │ │ │ │ al_draw_ellipse

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_filled_circle

    │ │ │ │ 
    void al_draw_filled_circle(float cx, float cy, float r, ALLEGRO_COLOR color)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws a filled circle.

    │ │ │ │

    Parameters:

    │ │ │ │ @@ -756,14 +856,23 @@ │ │ │ │
  • cx, cy - Center of the circle
    • │ │ │ │
  • r - Radius of the circle
    • │ │ │ │
  • color - Color of the circle
    • │ │ │ │ │ │ │ │

    See also: al_draw_circle, al_draw_filled_ellipse

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_arc

    │ │ │ │ 
    void al_draw_arc(float cx, float cy, float r, float start_theta,
│ │ │ │     float delta_theta, ALLEGRO_COLOR color, float thickness)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws an arc.

    │ │ │ │ @@ -778,14 +887,19 @@ │ │ │ │ number to switch direction) │ │ │ │
  • thickness - Thickness of the arc, pass <= 0 to draw │ │ │ │ hairline arc
    • │ │ │ │ │ │ │ │

    See also: al_calculate_arc, al_draw_elliptical_arc

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_prim.c
      • │ │ │ │ +
    │ │ │ │

    al_draw_elliptical_arc

    │ │ │ │ 
    void al_draw_elliptical_arc(float cx, float cy, float rx, float ry, float start_theta,
│ │ │ │     float delta_theta, ALLEGRO_COLOR color, float thickness)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws an elliptical arc.

    │ │ │ │ @@ -801,14 +915,19 @@ │ │ │ │
  • thickness - Thickness of the arc, pass <= 0 to draw │ │ │ │ hairline arc
    • │ │ │ │ │ │ │ │

    Since: 5.0.6, 5.1.0

    │ │ │ │

    See also: al_calculate_arc, al_draw_arc

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_prim.c
      • │ │ │ │ +
    │ │ │ │

    al_calculate_spline

    │ │ │ │ 
    void al_calculate_spline(float* dest, int stride, const float points[8],
│ │ │ │     float thickness, int num_segments)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Calculates a Bézier spline given 4 control points. If │ │ │ │ @@ -843,14 +962,19 @@ │ │ │ │ points │ │ │ │

  • color - Color of the spline
    • │ │ │ │
  • thickness - Thickness of the spline, pass <= 0 to │ │ │ │ draw a hairline spline
    • │ │ │ │ │ │ │ │

    See also: al_calculate_spline

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_prim.c
      • │ │ │ │ +
    │ │ │ │

    al_calculate_ribbon

    │ │ │ │ 
    void al_calculate_ribbon(float* dest, int dest_stride, const float *points,
│ │ │ │     int points_stride, float thickness, int num_segments)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Calculates a ribbon given an array of points. The ribbon will go │ │ │ │ @@ -953,14 +1077,23 @@ │ │ │ │ {.x = 256, .y = 256, .z = 0, .color = white, .u = 256, .v = 256}}; │ │ │ │ al_draw_prim(v, NULL, texture, 0, 3, ALLEGRO_PRIM_TRIANGLE_LIST); │ │ │ │

    See also: ALLEGRO_VERTEX, ALLEGRO_PRIM_TYPE, ALLEGRO_VERTEX_DECL, al_draw_indexed_prim

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_indexed_prim

    │ │ │ │ 
    int al_draw_indexed_prim(const void* vtxs, const ALLEGRO_VERTEX_DECL* decl,
│ │ │ │     ALLEGRO_BITMAP* texture, const int* indices, int num_vtx, int type)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws a subset of the passed vertex array. This function uses an │ │ │ │ @@ -981,14 +1114,21 @@ │ │ │ │ │ │ │ │

    Returns: Number of primitives drawn

    │ │ │ │

    See also: ALLEGRO_VERTEX, ALLEGRO_PRIM_TYPE, ALLEGRO_VERTEX_DECL, al_draw_prim

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_vertex_buffer

    │ │ │ │ 
    int al_draw_vertex_buffer(ALLEGRO_VERTEX_BUFFER* vertex_buffer,
│ │ │ │     ALLEGRO_BITMAP* texture, int start, int end, int type)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draws a subset of the passed vertex buffer. The vertex buffer must │ │ │ │ @@ -1008,14 +1148,21 @@ │ │ │ │ enumeration, specifying what kind of primitive to draw │ │ │ │ │ │ │ │

    Returns: Number of primitives drawn

    │ │ │ │

    Since: 5.1.3

    │ │ │ │

    See also: ALLEGRO_VERTEX_BUFFER, │ │ │ │ ALLEGRO_PRIM_TYPE

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_indexed_buffer

    │ │ │ │ 
    int al_draw_indexed_buffer(ALLEGRO_VERTEX_BUFFER* vertex_buffer,
│ │ │ │     ALLEGRO_BITMAP* texture, ALLEGRO_INDEX_BUFFER* index_buffer,
│ │ │ │     int start, int end, int type)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -1041,14 +1188,19 @@ │ │ │ │ │ │ │ │

    Returns: Number of primitives drawn

    │ │ │ │

    Since: 5.1.8

    │ │ │ │

    See also: ALLEGRO_VERTEX_BUFFER, │ │ │ │ ALLEGRO_INDEX_BUFFER, │ │ │ │ ALLEGRO_PRIM_TYPE

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_prim.c
      • │ │ │ │ +
    │ │ │ │

    al_draw_soft_triangle

    │ │ │ │ 
    void al_draw_soft_triangle(
│ │ │ │     ALLEGRO_VERTEX* v1, ALLEGRO_VERTEX* v2, ALLEGRO_VERTEX* v3, uintptr_t state,
│ │ │ │     void (*init)(uintptr_t, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*),
│ │ │ │     void (*first)(uintptr_t, int, int, int, int),
│ │ │ │     void (*step)(uintptr_t, int),
│ │ │ │     void (*draw)(uintptr_t, int, int, int))
    │ │ │ │ @@ -1133,14 +1285,21 @@ │ │ │ │ │ │ │ │

    Returns: Newly created vertex declaration.

    │ │ │ │

    See also: ALLEGRO_VERTEX_ELEMENT, │ │ │ │ ALLEGRO_VERTEX_DECL, │ │ │ │ al_destroy_vertex_decl

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_destroy_vertex_decl

    │ │ │ │ 
    void al_destroy_vertex_decl(ALLEGRO_VERTEX_DECL* decl)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Destroys a vertex declaration.

    │ │ │ │

    Parameters:

    │ │ │ │ @@ -1148,14 +1307,19 @@ │ │ │ │
  • decl - Vertex declaration to destroy
    • │ │ │ │ │ │ │ │

    See also: ALLEGRO_VERTEX_ELEMENT, │ │ │ │ ALLEGRO_VERTEX_DECL, │ │ │ │ al_create_vertex_decl

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Vertex buffer routines

    │ │ │ │

    al_create_vertex_buffer

    │ │ │ │ 
    ALLEGRO_VERTEX_BUFFER* al_create_vertex_buffer(ALLEGRO_VERTEX_DECL* decl,
│ │ │ │     const void* initial_data, int num_vertices, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -1183,25 +1347,39 @@ │ │ │ │ as passing ALLEGRO_PRIM_BUFFER_STATIC. │ │ │ │ │ │ │ │

    Since: 5.1.3

    │ │ │ │

    See also: ALLEGRO_VERTEX_BUFFER, │ │ │ │ al_destroy_vertex_buffer

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_destroy_vertex_buffer

    │ │ │ │ 
    void al_destroy_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Destroys a vertex buffer. Does nothing if passed NULL.

    │ │ │ │

    Since: 5.1.3

    │ │ │ │

    See also: ALLEGRO_VERTEX_BUFFER, │ │ │ │ al_create_vertex_buffer

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_lock_vertex_buffer

    │ │ │ │ 
    void* al_lock_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer, int offset,
│ │ │ │     int length, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Locks a vertex buffer so you can access its data. Will return NULL if │ │ │ │ @@ -1216,25 +1394,39 @@ │ │ │ │ ALLEGRO_LOCK_READWRITE │ │ │ │ │ │ │ │

    Since: 5.1.3

    │ │ │ │

    See also: ALLEGRO_VERTEX_BUFFER, │ │ │ │ al_unlock_vertex_buffer

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_unlock_vertex_buffer

    │ │ │ │ 
    void al_unlock_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Unlocks a previously locked vertex buffer.

    │ │ │ │

    Since: 5.1.3

    │ │ │ │

    See also: ALLEGRO_VERTEX_BUFFER, │ │ │ │ al_lock_vertex_buffer

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_vertex_buffer_size

    │ │ │ │ 
    int al_get_vertex_buffer_size(ALLEGRO_VERTEX_BUFFER* buffer)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the size of the vertex buffer

    │ │ │ │

    Since: 5.1.8

    │ │ │ │ @@ -1269,24 +1461,34 @@ │ │ │ │ flags specifying how this buffer will be created. Passing 0 is the same │ │ │ │ as passing ALLEGRO_PRIM_BUFFER_STATIC. │ │ │ │ │ │ │ │

    Since: 5.1.8

    │ │ │ │

    See also: ALLEGRO_INDEX_BUFFER, al_destroy_index_buffer

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_prim.c
      • │ │ │ │ +
    │ │ │ │

    al_destroy_index_buffer

    │ │ │ │ 
    void al_destroy_index_buffer(ALLEGRO_INDEX_BUFFER* buffer)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Destroys a index buffer. Does nothing if passed NULL.

    │ │ │ │

    Since: 5.1.8

    │ │ │ │

    See also: ALLEGRO_INDEX_BUFFER, al_create_index_buffer

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_prim.c
      • │ │ │ │ +
    │ │ │ │

    al_lock_index_buffer

    │ │ │ │ 
    void* al_lock_index_buffer(ALLEGRO_INDEX_BUFFER* buffer, int offset,
│ │ │ │      int length, int flags)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Locks a index buffer so you can access its data. Will return NULL if │ │ │ │ @@ -1300,24 +1502,34 @@ │ │ │ │

  • flags - ALLEGRO_LOCK_READONLY, ALLEGRO_LOCK_WRITEONLY or │ │ │ │ ALLEGRO_LOCK_READWRITE
    • │ │ │ │ │ │ │ │

    Since: 5.1.8

    │ │ │ │

    See also: ALLEGRO_INDEX_BUFFER, al_unlock_index_buffer

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_prim.c
      • │ │ │ │ +
    │ │ │ │

    al_unlock_index_buffer

    │ │ │ │ 
    void al_unlock_index_buffer(ALLEGRO_INDEX_BUFFER* buffer)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Unlocks a previously locked index buffer.

    │ │ │ │

    Since: 5.1.8

    │ │ │ │

    See also: ALLEGRO_INDEX_BUFFER, al_lock_index_buffer

    │ │ │ │ +

    Examples:

    │ │ │ │ +
      │ │ │ │ +
    • ex_prim.c
      • │ │ │ │ +
    │ │ │ │

    al_get_index_buffer_size

    │ │ │ │ 
    int al_get_index_buffer_size(ALLEGRO_INDEX_BUFFER* buffer)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the size of the index buffer

    │ │ │ │

    Since: 5.1.8

    │ │ │ │ @@ -1365,14 +1577,19 @@ │ │ │ │

    The stride may also be negative if the vertices are stored in reverse │ │ │ │ order.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_draw_polygon, ALLEGRO_LINE_JOIN, ALLEGRO_LINE_CAP

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_polygon

    │ │ │ │ 
    void al_draw_polygon(const float *vertices, int vertex_count,
│ │ │ │     int join_style, ALLEGRO_COLOR color, float thickness, float miter_limit)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draw an unfilled polygon. This is the same as passing │ │ │ │ @@ -1390,14 +1607,19 @@ │ │ │ │

  • miter_limit - Parameter for miter join style
    • │ │ │ │ │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_draw_filled_polygon, │ │ │ │ al_draw_polyline, ALLEGRO_LINE_JOIN

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_filled_polygon

    │ │ │ │ 
    void al_draw_filled_polygon(const float *vertices, int vertex_count,
│ │ │ │     ALLEGRO_COLOR color)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Draw a filled, simple polygon. Simple means it does not have to be │ │ │ │ @@ -1409,14 +1631,19 @@ │ │ │ │ │ │ │ │

    When the y-axis is facing downwards (the usual), the coordinates must │ │ │ │ be ordered anti-clockwise.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_draw_polygon, al_draw_filled_polygon_with_holes

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_draw_filled_polygon_with_holes

    │ │ │ │ 
    void al_draw_filled_polygon_with_holes(const float *vertices,
│ │ │ │     const int *vertex_counts, ALLEGRO_COLOR color)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -1459,14 +1686,19 @@ │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_draw_filled_polygon, │ │ │ │ al_draw_filled_polygon_with_holes, │ │ │ │ al_triangulate_polygon

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_triangulate_polygon

    │ │ │ │ 
    bool al_triangulate_polygon(
│ │ │ │     const float* vertices, size_t vertex_stride, const int* vertex_counts,
│ │ │ │     void (*emit_triangle)(int, int, int, void*), void* userdata)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -1510,28 +1742,44 @@ │ │ │ │
  • x, y, z - Position of the vertex (float)
    • │ │ │ │
  • u, v - Texture coordinates measured in pixels (float)
    • │ │ │ │
  • color - ALLEGRO_COLOR │ │ │ │ structure, storing the color of the vertex
    • │ │ │ │ │ │ │ │

    See also: ALLEGRO_PRIM_ATTR

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_VERTEX_DECL

    │ │ │ │ 
    typedef struct ALLEGRO_VERTEX_DECL ALLEGRO_VERTEX_DECL;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    A vertex declaration. This opaque structure is responsible for │ │ │ │ describing the format and layout of a user defined custom vertex. It is │ │ │ │ created and destroyed by specialized functions.

    │ │ │ │

    See also: al_create_vertex_decl, │ │ │ │ al_destroy_vertex_decl, │ │ │ │ ALLEGRO_VERTEX_ELEMENT

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_VERTEX_ELEMENT

    │ │ │ │ 
    typedef struct ALLEGRO_VERTEX_ELEMENT ALLEGRO_VERTEX_ELEMENT;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    A small structure describing a certain element of a vertex. E.g. the │ │ │ │ position of the vertex, or its color. These structures are used by the │ │ │ │ @@ -1566,14 +1814,21 @@ │ │ │ │ structure. The C function offsetof is very useful here. │ │ │ │ │ │ │ │

    See also: al_create_vertex_decl, │ │ │ │ ALLEGRO_VERTEX_DECL, │ │ │ │ ALLEGRO_PRIM_ATTR, ALLEGRO_PRIM_STORAGE

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_PRIM_TYPE

    │ │ │ │ 
    typedef enum ALLEGRO_PRIM_TYPE
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Enumerates the types of primitives this addon can draw.

    │ │ │ │     │ │ │ │

    See also: al_rotate_transform, │ │ │ │ al_scale_transform, │ │ │ │ al_build_transform

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_rotate_transform

    │ │ │ │ 
    void al_rotate_transform(ALLEGRO_TRANSFORM *trans, float theta)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Apply a rotation to a transformation.

    │ │ │ │

    Parameters:

    │ │ │ │ @@ -632,14 +708,23 @@ │ │ │ │ │ │ │ │

    See also: al_translate_transform, │ │ │ │ al_scale_transform, │ │ │ │ al_build_transform

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_scale_transform

    │ │ │ │ 
    void al_scale_transform(ALLEGRO_TRANSFORM *trans, float sx, float sy)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Apply a scale to a transformation.

    │ │ │ │

    Parameters:

    │ │ │ │ @@ -649,28 +734,42 @@ │ │ │ │ │ │ │ │

    See also: al_translate_transform, │ │ │ │ al_rotate_transform, │ │ │ │ al_build_transform

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_transform_coordinates

    │ │ │ │ 
    void al_transform_coordinates(const ALLEGRO_TRANSFORM *trans, float *x, float *y)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Transform a pair of coordinates.

    │ │ │ │

    Parameters:

    │ │ │ │
      │ │ │ │
    • trans - Transformation to use
      • │ │ │ │
    • x, y - Pointers to the coordinates
      • │ │ │ │
    │ │ │ │

    See also: al_use_transform, al_transform_coordinates_3d

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_transform_coordinates_3d

    │ │ │ │ 
    void al_transform_coordinates_3d(const ALLEGRO_TRANSFORM *trans,
│ │ │ │     float *x, float *y, float *z)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Transform x, y, z coordinates.

    │ │ │ │ @@ -683,14 +782,19 @@ │ │ │ │ want to use al_transform_coordinates_3d_projective │ │ │ │ instead.

    │ │ │ │

    Since 5.1.9

    │ │ │ │

    See also: al_use_transform, al_transform_coordinates

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_transform_coordinates_4d

    │ │ │ │ 
    void al_transform_coordinates_4d(const ALLEGRO_TRANSFORM *trans,
│ │ │ │     float *x, float *y, float *z, float *w)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Transform x, y, z, w coordinates.

    │ │ │ │ @@ -770,14 +874,19 @@ │ │ │ │ │ │ │ │

    See also: al_translate_transform, │ │ │ │ al_rotate_transform, │ │ │ │ al_scale_transform

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_orthographic_transform

    │ │ │ │ 
    void al_orthographic_transform(ALLEGRO_TRANSFORM *trans,
│ │ │ │     float left, float top, float n,
│ │ │ │     float right, float bottom, float f)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -801,14 +910,19 @@ │ │ │ │ href="transformations.html#al_use_projection_transform">al_use_projection_transform │ │ │ │ - see that function for an example use.

    │ │ │ │

    Since: 5.1.3

    │ │ │ │

    See also: al_use_projection_transform, │ │ │ │ al_perspective_transform

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_perspective_transform

    │ │ │ │ 
    void al_perspective_transform(ALLEGRO_TRANSFORM *trans,
│ │ │ │     float left, float top, float n,
│ │ │ │     float right, float bottom, float f)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -877,25 +991,43 @@ │ │ │ │ // pixel (assuming the display is 800 x 450). │ │ │ │ al_draw_filled_rectangle(-1, -1, 1, 1, red);     │ │ │ │

    Since: 5.1.3

    │ │ │ │

    See also: al_use_projection_transform, │ │ │ │ al_orthographic_transform

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_translate_transform_3d

    │ │ │ │ 
    void al_translate_transform_3d(ALLEGRO_TRANSFORM *trans, float x, float y,
│ │ │ │      float z)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Combines the given transformation with a transformation which │ │ │ │ translates coordinates by the given vector.

    │ │ │ │

    Since: 5.1.3

    │ │ │ │

    See also: al_use_projection_transform

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_scale_transform_3d

    │ │ │ │ 
    void al_scale_transform_3d(ALLEGRO_TRANSFORM *trans, float sx, float sy,
│ │ │ │      float sz)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Combines the given transformation with a transformation which scales │ │ │ │ @@ -910,14 +1042,23 @@ │ │ │ │ href="https://github.com/liballeg/allegro5/blob/master/src/transformations.c#L566">Source │ │ │ │ Code

    │ │ │ │

    Combines the given transformation with a transformation which rotates │ │ │ │ coordinates around the given vector by the given angle in radians.

    │ │ │ │

    Note: The vector is assumed to be of unit length (otherwise it will │ │ │ │ also incur a scale).

    │ │ │ │

    Since: 5.1.3

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_horizontal_shear_transform

    │ │ │ │ 
    void al_horizontal_shear_transform(ALLEGRO_TRANSFORM* trans, float theta)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Apply a horizontal shear to the transform

    │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -136,21 +136,27 @@ │ │ │ │ │ typedef struct ALLEGRO_TRANSFORM ALLEGRO_TRANSFORM; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Defines the generic transformation type, a 4x4 matrix. 2D transforms use only a │ │ │ │ │ small subsection of this matrix, namely the top left 2x2 matrix, and the right │ │ │ │ │ most 2x1 matrix, for a total of 6 values. │ │ │ │ │ FFiieellddss:: │ │ │ │ │ * m - A 4x4 float matrix │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_h_a_d_e_r_._c_p_p │ │ │ │ │ + * _e_x___s_h_a_d_e_r___t_a_r_g_e_t_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___t_i_m_e_r_._c │ │ │ │ │ ************ aall__ccooppyy__ttrraannssffoorrmm ************ │ │ │ │ │ void al_copy_transform(ALLEGRO_TRANSFORM *dest, const ALLEGRO_TRANSFORM *src) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Makes a copy of a transformation. │ │ │ │ │ PPaarraammeetteerrss:: │ │ │ │ │ * dest - Source transformation │ │ │ │ │ * src - Destination transformation │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_h_a_d_e_r_._c_p_p │ │ │ │ │ ************ aall__uussee__ttrraannssffoorrmm ************ │ │ │ │ │ void al_use_transform(const ALLEGRO_TRANSFORM *trans) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Sets the transformation to be used for the the drawing operations on the target │ │ │ │ │ bitmap (each bitmap maintains its own transformation). Every drawing operation │ │ │ │ │ after this call will be transformed using this transformation. Call this │ │ │ │ │ function with an identity transformation to return to the default behaviour. │ │ │ │ │ @@ -163,21 +169,28 @@ │ │ │ │ │ ALLEGRO_TRANSFORM transform; │ │ │ │ │ al_translate_transform(&transform, 5, 10); │ │ │ │ │ al_use_transform(&transform); │ │ │ │ │ } │ │ │ │ │ PPaarraammeetteerrss:: │ │ │ │ │ * trans - Transformation to use │ │ │ │ │ See also: _a_l___g_e_t___c_u_r_r_e_n_t___t_r_a_n_s_f_o_r_m, _a_l___t_r_a_n_s_f_o_r_m___c_o_o_r_d_i_n_a_t_e_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_h_a_d_e_r_._c_p_p │ │ │ │ │ + * _e_x___s_h_a_d_e_r___t_a_r_g_e_t_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___t_i_m_e_r_._c │ │ │ │ │ ************ aall__ggeett__ccuurrrreenntt__ttrraannssffoorrmm ************ │ │ │ │ │ const ALLEGRO_TRANSFORM *al_get_current_transform(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the transformation of the current target bitmap, as set by │ │ │ │ │ _a_l___u_s_e___t_r_a_n_s_f_o_r_m. If there is no target bitmap, this function returns NULL. │ │ │ │ │ RReettuurrnnss:: A pointer to the current transformation. │ │ │ │ │ See also: _a_l___g_e_t___c_u_r_r_e_n_t___p_r_o_j_e_c_t_i_o_n___t_r_a_n_s_f_o_r_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_h_a_d_e_r_._c_p_p │ │ │ │ │ + * _e_x___c_o_l_o_r___g_r_a_d_i_e_n_t_._c │ │ │ │ │ ************ aall__uussee__pprroojjeeccttiioonn__ttrraannssffoorrmm ************ │ │ │ │ │ void al_use_projection_transform(const ALLEGRO_TRANSFORM *trans) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Sets the projection transformation to be used for the drawing operations on the │ │ │ │ │ target bitmap (each bitmap maintains its own projection transformation). Every │ │ │ │ │ drawing operation after this call will be transformed using this │ │ │ │ │ transformation. To return default behavior, call this function with an │ │ │ │ │ @@ -201,21 +214,27 @@ │ │ │ │ │ projection transform of the target bitmap was temporarily reset to default). │ │ │ │ │ The parameter is passed by reference as an optimization to avoid the overhead │ │ │ │ │ of stack copying. The reference will not be stored in the Allegro library so it │ │ │ │ │ is safe to pass references to local variables. │ │ │ │ │ Since: 5.1.9 │ │ │ │ │ See also: _a_l___g_e_t___c_u_r_r_e_n_t___p_r_o_j_e_c_t_i_o_n___t_r_a_n_s_f_o_r_m, _a_l___p_e_r_s_p_e_c_t_i_v_e___t_r_a_n_s_f_o_r_m, │ │ │ │ │ _a_l___o_r_t_h_o_g_r_a_p_h_i_c___t_r_a_n_s_f_o_r_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_r_o_j_e_c_t_i_o_n_._c │ │ │ │ │ + * _e_x___d_e_p_t_h___t_a_r_g_e_t_._c │ │ │ │ │ + * _e_x___p_r_o_j_e_c_t_i_o_n_2_._c │ │ │ │ │ ************ aall__ggeett__ccuurrrreenntt__pprroojjeeccttiioonn__ttrraannssffoorrmm ************ │ │ │ │ │ const ALLEGRO_TRANSFORM *al_get_current_projection_transform(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ If there is no target bitmap, this function returns NULL. │ │ │ │ │ RReettuurrnnss:: A pointer to the current transformation. │ │ │ │ │ Since: 5.1.9 │ │ │ │ │ See also: _a_l___u_s_e___p_r_o_j_e_c_t_i_o_n___t_r_a_n_s_f_o_r_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___c_a_m_e_r_a_._c │ │ │ │ │ ************ aall__ggeett__ccuurrrreenntt__iinnvveerrssee__ttrraannssffoorrmm ************ │ │ │ │ │ const ALLEGRO_TRANSFORM *al_get_current_inverse_transform(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the inverse of the current transformation of the target bitmap. If │ │ │ │ │ there is no target bitmap, this function returns NULL. │ │ │ │ │ This is similar to calling al_invert_transform(al_get_current_transform()) but │ │ │ │ │ the result of this function is cached. │ │ │ │ │ @@ -280,14 +299,18 @@ │ │ │ │ │ the default. │ │ │ │ │ ALLEGRO_TRANSFORM t; │ │ │ │ │ al_identity_transform(&t); │ │ │ │ │ al_use_transform(&t); │ │ │ │ │ PPaarraammeetteerrss:: │ │ │ │ │ * trans - Transformation to alter │ │ │ │ │ See also: _a_l___t_r_a_n_s_l_a_t_e___t_r_a_n_s_f_o_r_m, _a_l___r_o_t_a_t_e___t_r_a_n_s_f_o_r_m, _a_l___s_c_a_l_e___t_r_a_n_s_f_o_r_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_h_a_d_e_r_._c_p_p │ │ │ │ │ + * _e_x___s_h_a_d_e_r___t_a_r_g_e_t_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___t_i_m_e_r_._c │ │ │ │ │ ************ aall__bbuuiilldd__ttrraannssffoorrmm ************ │ │ │ │ │ void al_build_transform(ALLEGRO_TRANSFORM *trans, float x, float y, │ │ │ │ │ float sx, float sy, float theta) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Builds a transformation given some parameters. This call is equivalent to │ │ │ │ │ calling the transformations in this order: make identity, rotate, scale, │ │ │ │ │ translate. This method is faster, however, than actually calling those │ │ │ │ │ @@ -298,14 +321,18 @@ │ │ │ │ │ * sx, sy - Scale │ │ │ │ │ * theta - Rotation angle in radians │ │ │ │ │ NNoottee: this function was previously documented to be equivalent to a │ │ │ │ │ different (and more useful) order of operations: identity, scale, │ │ │ │ │ rotate, translate. │ │ │ │ │ See also: _a_l___t_r_a_n_s_l_a_t_e___t_r_a_n_s_f_o_r_m, _a_l___r_o_t_a_t_e___t_r_a_n_s_f_o_r_m, _a_l___s_c_a_l_e___t_r_a_n_s_f_o_r_m, │ │ │ │ │ _a_l___c_o_m_p_o_s_e___t_r_a_n_s_f_o_r_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___t_h_r_e_a_d_s_._c │ │ │ │ │ + * _e_x___c_o_l_o_r___g_r_a_d_i_e_n_t_._c │ │ │ │ │ + * _e_x___p_r_i_m_._c │ │ │ │ │ ************ aall__bbuuiilldd__ccaammeerraa__ttrraannssffoorrmm ************ │ │ │ │ │ void al_build_camera_transform(ALLEGRO_TRANSFORM *trans, │ │ │ │ │ float position_x, float position_y, float position_z, │ │ │ │ │ float look_x, float look_y, float look_z, │ │ │ │ │ float up_x, float up_y, float up_z) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Builds a transformation which can be used to transform 3D coordinates in world │ │ │ │ │ @@ -334,59 +361,77 @@ │ │ │ │ │ al_build_camera_transform(&t, │ │ │ │ │ 1, 1, 1, │ │ │ │ │ 5, 5, 5, │ │ │ │ │ 1, 1, 0); │ │ │ │ │ Since 5.1.9 │ │ │ │ │ See also: _a_l___t_r_a_n_s_l_a_t_e___t_r_a_n_s_f_o_r_m___3_d, _a_l___r_o_t_a_t_e___t_r_a_n_s_f_o_r_m___3_d, │ │ │ │ │ _a_l___s_c_a_l_e___t_r_a_n_s_f_o_r_m___3_d, _a_l___c_o_m_p_o_s_e___t_r_a_n_s_f_o_r_m, _a_l___u_s_e___t_r_a_n_s_f_o_r_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___c_a_m_e_r_a_._c │ │ │ │ │ ************ aall__ttrraannssllaattee__ttrraannssffoorrmm ************ │ │ │ │ │ void al_translate_transform(ALLEGRO_TRANSFORM *trans, float x, float y) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Apply a translation to a transformation. │ │ │ │ │ PPaarraammeetteerrss:: │ │ │ │ │ * trans - Transformation to alter │ │ │ │ │ * x, y - Translation │ │ │ │ │ See also: _a_l___r_o_t_a_t_e___t_r_a_n_s_f_o_r_m, _a_l___s_c_a_l_e___t_r_a_n_s_f_o_r_m, _a_l___b_u_i_l_d___t_r_a_n_s_f_o_r_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_h_a_d_e_r_._c_p_p │ │ │ │ │ + * _e_x___s_h_a_d_e_r___t_a_r_g_e_t_._c │ │ │ │ │ + * _e_x___p_o_l_y_g_o_n_._c │ │ │ │ │ ************ aall__rroottaattee__ttrraannssffoorrmm ************ │ │ │ │ │ void al_rotate_transform(ALLEGRO_TRANSFORM *trans, float theta) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Apply a rotation to a transformation. │ │ │ │ │ PPaarraammeetteerrss:: │ │ │ │ │ * trans - Transformation to alter │ │ │ │ │ * theta - Rotation angle in radians │ │ │ │ │ See also: _a_l___t_r_a_n_s_l_a_t_e___t_r_a_n_s_f_o_r_m, _a_l___s_c_a_l_e___t_r_a_n_s_f_o_r_m, _a_l___b_u_i_l_d___t_r_a_n_s_f_o_r_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_e_p_t_h___m_a_s_k_._c │ │ │ │ │ + * _e_x___p_r_o_j_e_c_t_i_o_n_._c │ │ │ │ │ + * _e_x___d_e_p_t_h___t_a_r_g_e_t_._c │ │ │ │ │ ************ aall__ssccaallee__ttrraannssffoorrmm ************ │ │ │ │ │ void al_scale_transform(ALLEGRO_TRANSFORM *trans, float sx, float sy) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Apply a scale to a transformation. │ │ │ │ │ PPaarraammeetteerrss:: │ │ │ │ │ * trans - Transformation to alter │ │ │ │ │ * sx, sy - Scale │ │ │ │ │ See also: _a_l___t_r_a_n_s_l_a_t_e___t_r_a_n_s_f_o_r_m, _a_l___r_o_t_a_t_e___t_r_a_n_s_f_o_r_m, _a_l___b_u_i_l_d___t_r_a_n_s_f_o_r_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___s_h_a_d_e_r___t_a_r_g_e_t_._c │ │ │ │ │ + * _e_x___a_u_d_i_o___t_i_m_e_r_._c │ │ │ │ │ + * _e_x___p_o_l_y_g_o_n_._c │ │ │ │ │ ************ aall__ttrraannssffoorrmm__ccoooorrddiinnaatteess ************ │ │ │ │ │ void al_transform_coordinates(const ALLEGRO_TRANSFORM *trans, float *x, float │ │ │ │ │ *y) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Transform a pair of coordinates. │ │ │ │ │ PPaarraammeetteerrss:: │ │ │ │ │ * trans - Transformation to use │ │ │ │ │ * x, y - Pointers to the coordinates │ │ │ │ │ See also: _a_l___u_s_e___t_r_a_n_s_f_o_r_m, _a_l___t_r_a_n_s_f_o_r_m___c_o_o_r_d_i_n_a_t_e_s___3_d │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___c_a_m_e_r_a_._c │ │ │ │ │ ************ aall__ttrraannssffoorrmm__ccoooorrddiinnaatteess__33dd ************ │ │ │ │ │ void al_transform_coordinates_3d(const ALLEGRO_TRANSFORM *trans, │ │ │ │ │ float *x, float *y, float *z) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Transform x, y, z coordinates. │ │ │ │ │ PPaarraammeetteerrss:: │ │ │ │ │ * trans - Transformation to use │ │ │ │ │ * x, y, z - Pointers to the coordinates │ │ │ │ │ Note: If you are using a projection transform you most likely will want to use │ │ │ │ │ _a_l___t_r_a_n_s_f_o_r_m___c_o_o_r_d_i_n_a_t_e_s___3_d___p_r_o_j_e_c_t_i_v_e instead. │ │ │ │ │ Since 5.1.9 │ │ │ │ │ See also: _a_l___u_s_e___t_r_a_n_s_f_o_r_m, _a_l___t_r_a_n_s_f_o_r_m___c_o_o_r_d_i_n_a_t_e_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___c_a_m_e_r_a_._c │ │ │ │ │ ************ aall__ttrraannssffoorrmm__ccoooorrddiinnaatteess__44dd ************ │ │ │ │ │ void al_transform_coordinates_4d(const ALLEGRO_TRANSFORM *trans, │ │ │ │ │ float *x, float *y, float *z, float *w) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Transform x, y, z, w coordinates. │ │ │ │ │ PPaarraammeetteerrss:: │ │ │ │ │ * trans - Transformation to use │ │ │ │ │ @@ -438,14 +483,16 @@ │ │ │ │ │ Note that the order of matrix multiplications is important. The effect of │ │ │ │ │ applying the combined transform will be as if first applying trans and then │ │ │ │ │ applying other and not the other way around. │ │ │ │ │ PPaarraammeetteerrss:: │ │ │ │ │ * trans - Transformation to alter │ │ │ │ │ * other - Transformation used to transform trans │ │ │ │ │ See also: _a_l___t_r_a_n_s_l_a_t_e___t_r_a_n_s_f_o_r_m, _a_l___r_o_t_a_t_e___t_r_a_n_s_f_o_r_m, _a_l___s_c_a_l_e___t_r_a_n_s_f_o_r_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___c_o_l_o_r___g_r_a_d_i_e_n_t_._c │ │ │ │ │ ************ aall__oorrtthhooggrraapphhiicc__ttrraannssffoorrmm ************ │ │ │ │ │ void al_orthographic_transform(ALLEGRO_TRANSFORM *trans, │ │ │ │ │ float left, float top, float n, │ │ │ │ │ float right, float bottom, float f) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Combines the given transformation with an orthographic transformation which │ │ │ │ │ maps the screen rectangle to the given left/top and right/bottom coordinates. │ │ │ │ │ @@ -461,14 +508,16 @@ │ │ │ │ │ artifacts. │ │ │ │ │ The result of applying this transformation to coordinates will be to normalize │ │ │ │ │ visible coordinates into the cube from -1/-1/-1 to 1/1/1. Such a transformation │ │ │ │ │ is mostly useful for passing it to _a_l___u_s_e___p_r_o_j_e_c_t_i_o_n___t_r_a_n_s_f_o_r_m - see that │ │ │ │ │ function for an example use. │ │ │ │ │ Since: 5.1.3 │ │ │ │ │ See also: _a_l___u_s_e___p_r_o_j_e_c_t_i_o_n___t_r_a_n_s_f_o_r_m, _a_l___p_e_r_s_p_e_c_t_i_v_e___t_r_a_n_s_f_o_r_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___d_e_p_t_h___t_a_r_g_e_t_._c │ │ │ │ │ ************ aall__ppeerrssppeeccttiivvee__ttrraannssffoorrmm ************ │ │ │ │ │ void al_perspective_transform(ALLEGRO_TRANSFORM *trans, │ │ │ │ │ float left, float top, float n, │ │ │ │ │ float right, float bottom, float f) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___o_r_t_h_o_g_r_a_p_h_i_c___t_r_a_n_s_f_o_r_m but honors perspective. If everything is at a z- │ │ │ │ │ position of -near it will look the same as with an orthographic transformation. │ │ │ │ │ @@ -529,22 +578,30 @@ │ │ │ │ │ // At a z distance of 4 with a 90° hfov everything would be scaled │ │ │ │ │ // down to 25%. However we also zoom 2-fold, so the final scaling is │ │ │ │ │ // 50%. This rectangle therefore will appear at a size of 400 x 225 │ │ │ │ │ // pixel (assuming the display is 800 x 450). │ │ │ │ │ al_draw_filled_rectangle(-1, -1, 1, 1, red); │ │ │ │ │ Since: 5.1.3 │ │ │ │ │ See also: _a_l___u_s_e___p_r_o_j_e_c_t_i_o_n___t_r_a_n_s_f_o_r_m, _a_l___o_r_t_h_o_g_r_a_p_h_i_c___t_r_a_n_s_f_o_r_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_r_o_j_e_c_t_i_o_n_._c │ │ │ │ │ + * _e_x___p_r_o_j_e_c_t_i_o_n_2_._c │ │ │ │ │ + * _e_x___c_a_m_e_r_a_._c │ │ │ │ │ ************ aall__ttrraannssllaattee__ttrraannssffoorrmm__33dd ************ │ │ │ │ │ void al_translate_transform_3d(ALLEGRO_TRANSFORM *trans, float x, float y, │ │ │ │ │ float z) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Combines the given transformation with a transformation which translates │ │ │ │ │ coordinates by the given vector. │ │ │ │ │ Since: 5.1.3 │ │ │ │ │ See also: _a_l___u_s_e___p_r_o_j_e_c_t_i_o_n___t_r_a_n_s_f_o_r_m │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_r_o_j_e_c_t_i_o_n_._c │ │ │ │ │ + * _e_x___d_e_p_t_h___t_a_r_g_e_t_._c │ │ │ │ │ + * _e_x___p_r_o_j_e_c_t_i_o_n_2_._c │ │ │ │ │ ************ aall__ssccaallee__ttrraannssffoorrmm__33dd ************ │ │ │ │ │ void al_scale_transform_3d(ALLEGRO_TRANSFORM *trans, float sx, float sy, │ │ │ │ │ float sz) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Combines the given transformation with a transformation which scales │ │ │ │ │ coordinates by the given vector. │ │ │ │ │ Since: 5.1.3 │ │ │ │ │ @@ -554,14 +611,18 @@ │ │ │ │ │ float x, float y, float z, float angle) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Combines the given transformation with a transformation which rotates │ │ │ │ │ coordinates around the given vector by the given angle in radians. │ │ │ │ │ Note: The vector is assumed to be of unit length (otherwise it will also incur │ │ │ │ │ a scale). │ │ │ │ │ Since: 5.1.3 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___p_r_o_j_e_c_t_i_o_n_._c │ │ │ │ │ + * _e_x___d_e_p_t_h___t_a_r_g_e_t_._c │ │ │ │ │ + * _e_x___p_r_o_j_e_c_t_i_o_n_2_._c │ │ │ │ │ ************ aall__hhoorriizzoonnttaall__sshheeaarr__ttrraannssffoorrmm ************ │ │ │ │ │ void al_horizontal_shear_transform(ALLEGRO_TRANSFORM* trans, float theta) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Apply a horizontal shear to the transform │ │ │ │ │ PPaarraammeetteerrss:: │ │ │ │ │ * trans - Transformation to alter │ │ │ │ │ * theta - Rotation angle in radians │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/utf8.html │ │ │ │ @@ -444,28 +444,46 @@ │ │ │ │ 
    typedef struct _al_tagbstring ALLEGRO_USTR;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    An opaque type representing a string. ALLEGRO_USTRs normally contain │ │ │ │ UTF-8 encoded strings, but they may be used to hold any byte sequences, │ │ │ │ including NULs.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    ALLEGRO_USTR_INFO

    │ │ │ │ 
    typedef struct _al_tagbstring ALLEGRO_USTR_INFO;
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    A type that holds additional information for an ALLEGRO_USTR that references an │ │ │ │ external memory buffer. You can convert it back to ALLEGRO_USTR via al_ref_info.

    │ │ │ │

    See also: al_ref_cstr, al_ref_buffer, al_ref_info and al_ref_ustr.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Creating and destroying │ │ │ │ strings

    │ │ │ │

    al_ustr_new

    │ │ │ │ 
    ALLEGRO_USTR *al_ustr_new(const char *s)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -473,24 +491,38 @@ │ │ │ │ s. The string must eventually be freed with al_ustr_free.

    │ │ │ │

    See also: al_ustr_new_from_buffer, al_ustr_newf, al_ustr_dup, al_ustr_new_from_utf16

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_new_from_buffer

    │ │ │ │ 
    ALLEGRO_USTR *al_ustr_new_from_buffer(const char *s, size_t size)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Create a new string containing a copy of the buffer pointed to by │ │ │ │ s of the given size in bytes. The string must │ │ │ │ eventually be freed with al_ustr_free.

    │ │ │ │

    See also: al_ustr_new

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_newf

    │ │ │ │ 
    ALLEGRO_USTR *al_ustr_newf(const char *fmt, ...)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Create a new string using a printf-style format string.

    │ │ │ │

    Notes:

    │ │ │ │ @@ -503,24 +535,38 @@ │ │ │ │ code point. Therefore it is only usable for ASCII characters (value │ │ │ │ <= 127) or if you really mean to output byte values from 128–255. To │ │ │ │ insert the UTF-8 encoding of a code point, encode it into a memory │ │ │ │ buffer using al_utf8_encode then │ │ │ │ use the “%s” specifier. Remember to NUL terminate the buffer.

    │ │ │ │

    See also: al_ustr_new, al_ustr_appendf

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_free

    │ │ │ │ 
    void al_ustr_free(ALLEGRO_USTR *us)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Free a previously allocated string. Does nothing if the argument is │ │ │ │ NULL.

    │ │ │ │

    See also: al_ustr_new, al_ustr_new_from_buffer, al_ustr_newf

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_cstr

    │ │ │ │ 
    const char *al_cstr(const ALLEGRO_USTR *us)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Get a char * pointer to the data in a string. This │ │ │ │ pointer will only be valid while the

    If the ALLEGRO_USTR references another string, the returned C │ │ │ │ string will point into the referenced string. Again, no NUL terminator │ │ │ │ will be added to the referenced string.

    │ │ │ │ │ │ │ │

    See also: al_ustr_to_buffer, al_cstr_dup

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_to_buffer

    │ │ │ │ 
    void al_ustr_to_buffer(const ALLEGRO_USTR *us, char *buffer, int size)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Write the contents of the string into a pre-allocated buffer of the │ │ │ │ given size in bytes. The result will always be NUL terminated, so a │ │ │ │ maximum of size - 1 bytes will be copied.

    │ │ │ │

    See also: al_cstr, al_cstr_dup

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_cstr_dup

    │ │ │ │ 
    char *al_cstr_dup(const ALLEGRO_USTR *us)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Create a NUL ('\0') terminated copy of the string. Any │ │ │ │ embedded NUL bytes will still be presented in the returned string. The │ │ │ │ new string must eventually be freed with al_free.

    │ │ │ │

    If an error occurs NULL is returned.

    │ │ │ │

    See also: al_cstr, al_ustr_to_buffer, al_free

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_dup

    │ │ │ │ 
    ALLEGRO_USTR *al_ustr_dup(const ALLEGRO_USTR *us)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return a duplicate copy of a string. The new string will need to be │ │ │ │ freed with al_ustr_free.

    │ │ │ │

    See also: al_ustr_dup_substr, al_ustr_free

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_dup_substr

    │ │ │ │ 
    ALLEGRO_USTR *al_ustr_dup_substr(const ALLEGRO_USTR *us, int start_pos,
│ │ │ │     int end_pos)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return a new copy of a string, containing its contents in the byte │ │ │ │ @@ -586,22 +656,32 @@ │ │ │ │ will be NUL terminated and will need to be freed with al_ustr_free.

    │ │ │ │

    If necessary, use al_ustr_offset to find the byte │ │ │ │ offsets for a given code point that you are interested in.

    │ │ │ │

    See also: al_ustr_dup, al_ustr_free

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Predefined strings

    │ │ │ │

    al_ustr_empty_string

    │ │ │ │ 
    const ALLEGRO_USTR *al_ustr_empty_string(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return a pointer to a static empty string. The string is read only │ │ │ │ and must not be freed.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Creating strings by │ │ │ │ referencing other data

    │ │ │ │

    al_ref_cstr

    │ │ │ │ 
    const ALLEGRO_USTR *al_ref_cstr(ALLEGRO_USTR_INFO *info, const char *s)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │ @@ -613,25 +693,41 @@ │ │ │ │ operation is required.

    │ │ │ │

    The string is valid until the underlying C string disappears.

    │ │ │ │

    Example:

    │ │ │ │ 
    ALLEGRO_USTR_INFO info;
│ │ │ │  ALLEGRO_USTR *us = al_ref_cstr(&info, "my string");
    │ │ │ │

    See also: al_ref_buffer, al_ref_ustr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ref_buffer

    │ │ │ │ 
    const ALLEGRO_USTR *al_ref_buffer(ALLEGRO_USTR_INFO *info, const char *s, size_t size)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Create a string that references the storage of an underlying buffer. │ │ │ │ The size of the buffer is given in bytes. You can use it to reference │ │ │ │ only part of a string or an arbitrary region of memory.

    │ │ │ │

    The string is valid while the underlying memory buffer is valid.

    │ │ │ │

    See also: al_ref_cstr, al_ref_ustr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ref_ustr

    │ │ │ │ 
    const ALLEGRO_USTR *al_ref_ustr(ALLEGRO_USTR_INFO *info, const ALLEGRO_USTR *us,
│ │ │ │     int start_pos, int end_pos)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Create a read-only string that references the storage of another The string is valid until the underlying string is modified or │ │ │ │ destroyed.

    │ │ │ │

    If you need a range of code-points instead of bytes, use al_ustr_offset to find the byte │ │ │ │ offsets.

    │ │ │ │

    See also: al_ref_cstr, al_ref_buffer

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ref_info

    │ │ │ │ 
    const ALLEGRO_USTR *al_ref_info(const ALLEGRO_USTR_INFO *info)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Create a read-only string that references the storage of another ALLEGRO_USTR string that has already │ │ │ │ @@ -670,35 +775,60 @@ │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the size of the string in bytes. This is equal to the number │ │ │ │ of code points in the string if the string is empty or contains only │ │ │ │ 7-bit ASCII characters.

    │ │ │ │

    See also: al_ustr_length

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_length

    │ │ │ │ 
    size_t al_ustr_length(const ALLEGRO_USTR *us)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the number of code points in the string.

    │ │ │ │

    See also: al_ustr_size, al_ustr_offset

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_offset

    │ │ │ │ 
    int al_ustr_offset(const ALLEGRO_USTR *us, int index)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the byte offset (from the start of the string) of the code │ │ │ │ point at the specified index in the string. A zero index parameter will │ │ │ │ return the first character of the string. If index is negative, it │ │ │ │ counts backward from the end of the string, so an index of -1 will │ │ │ │ return an offset to the last code point.

    │ │ │ │

    If the index is past the end of the string, returns the offset of the │ │ │ │ end of the string.

    │ │ │ │

    See also: al_ustr_length

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_next

    │ │ │ │ 
    bool al_ustr_next(const ALLEGRO_USTR *us, int *pos)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Find the byte offset of the next code point in string, beginning at │ │ │ │ *pos. *pos does not have to be at the │ │ │ │ @@ -708,14 +838,21 @@ │ │ │ │ *pos was already at the end of the string, and │ │ │ │ *pos is unmodified.

    │ │ │ │

    This function just looks for an appropriate byte; it doesn’t check if │ │ │ │ found offset is the beginning of a valid code point. If you are working │ │ │ │ with possibly invalid UTF-8 strings then it could skip over some invalid │ │ │ │ bytes.

    │ │ │ │

    See also: al_ustr_prev

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_prev

    │ │ │ │ 
    bool al_ustr_prev(const ALLEGRO_USTR *us, int *pos)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Find the byte offset of the previous code point in string, before │ │ │ │ *pos. *pos does not have to be at the │ │ │ │ @@ -724,41 +861,62 @@ │ │ │ │ Otherwise returns false if *pos was already at the end of │ │ │ │ the string, and *pos is unmodified.

    │ │ │ │

    This function just looks for an appropriate byte; it doesn’t check if │ │ │ │ found offset is the beginning of a valid code point. If you are working │ │ │ │ with possibly invalid UTF-8 strings then it could skip over some invalid │ │ │ │ bytes.

    │ │ │ │

    See also: al_ustr_next

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Getting code points

    │ │ │ │

    al_ustr_get

    │ │ │ │ 
    int32_t al_ustr_get(const ALLEGRO_USTR *ub, int pos)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return the code point in ub beginning at byte offset │ │ │ │ pos.

    │ │ │ │

    On success returns the code point value. If pos was out │ │ │ │ of bounds (e.g. past the end of the string), return -1. On an error, │ │ │ │ such as an invalid byte sequence, return -2.

    │ │ │ │

    See also: al_ustr_get_next, │ │ │ │ al_ustr_prev_get

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_get_next

    │ │ │ │ 
    int32_t al_ustr_get_next(const ALLEGRO_USTR *us, int *pos)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Find the code point in us beginning at byte offset │ │ │ │ *pos, then advance to the next code point.

    │ │ │ │

    On success return the code point value. If pos was out │ │ │ │ of bounds (e.g. past the end of the string), return -1. On an error, │ │ │ │ such as an invalid byte sequence, return -2. As with al_ustr_next, invalid byte sequences │ │ │ │ may be skipped while advancing.

    │ │ │ │

    See also: al_ustr_get, al_ustr_prev_get

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_prev_get

    │ │ │ │ 
    int32_t al_ustr_prev_get(const ALLEGRO_USTR *us, int *pos)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Find the beginning of a code point before byte offset │ │ │ │ *pos, then return it. Note this performs a │ │ │ │ @@ -766,14 +924,19 @@ │ │ │ │

    On success returns the code point value. If pos was out │ │ │ │ of bounds (e.g. past the end of the string), return -1. On an error, │ │ │ │ such as an invalid byte sequence, return -2. As with al_ustr_prev, invalid byte sequences │ │ │ │ may be skipped while advancing.

    │ │ │ │

    See also: al_ustr_get_next

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Inserting into strings

    │ │ │ │

    al_ustr_insert

    │ │ │ │ 
    bool al_ustr_insert(ALLEGRO_USTR *us1, int pos, const ALLEGRO_USTR *us2)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Insert us2 into us1 beginning at byte │ │ │ │ @@ -786,36 +949,55 @@ │ │ │ │ offset for a given code point index.

    │ │ │ │

    Returns true on success, false on error.

    │ │ │ │

    See also: al_ustr_insert_cstr, al_ustr_insert_chr, al_ustr_append, al_ustr_offset

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_insert_cstr

    │ │ │ │ 
    bool al_ustr_insert_cstr(ALLEGRO_USTR *us, int pos, const char *s)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Like al_ustr_insert but │ │ │ │ inserts a C-style string at byte offset pos.

    │ │ │ │

    See also: al_ustr_insert, al_ustr_insert_chr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_insert_chr

    │ │ │ │ 
    size_t al_ustr_insert_chr(ALLEGRO_USTR *us, int pos, int32_t c)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Insert a code point into us beginning at byte offset │ │ │ │ pos. pos cannot be less than 0. If │ │ │ │ pos is past the end of us then the space │ │ │ │ between the end of the string and pos will be padded with │ │ │ │ NUL ('\0') bytes.

    │ │ │ │

    Returns the number of bytes inserted, or 0 on error.

    │ │ │ │

    See also: al_ustr_insert, al_ustr_insert_cstr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Appending to strings

    │ │ │ │

    al_ustr_append

    │ │ │ │ 
    bool al_ustr_append(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Append us2 to the end of us1.

    │ │ │ │ @@ -824,138 +1006,208 @@ │ │ │ │ 
      ALLEGRO_USTR_INFO info;
│ │ │ │    al_ustr_append(us, al_ref_buffer(&info, buf, size));
    │ │ │ │

    See also: al_ustr_append_cstr, al_ustr_append_chr, al_ustr_appendf, al_ustr_vappendf

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_append_cstr

    │ │ │ │ 
    bool al_ustr_append_cstr(ALLEGRO_USTR *us, const char *s)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Append C-style string s to the end of │ │ │ │ us.

    │ │ │ │

    Returns true on success, false on error.

    │ │ │ │

    See also: al_ustr_append

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_append_chr

    │ │ │ │ 
    size_t al_ustr_append_chr(ALLEGRO_USTR *us, int32_t c)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Append a code point to the end of us.

    │ │ │ │

    Returns the number of bytes added, or 0 on error.

    │ │ │ │

    See also: al_ustr_append

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_appendf

    │ │ │ │ 
    bool al_ustr_appendf(ALLEGRO_USTR *us, const char *fmt, ...)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    This function appends formatted output to the string us. │ │ │ │ fmt is a printf-style format string. See al_ustr_newf about the “%s” and “%c” │ │ │ │ specifiers.

    │ │ │ │

    Returns true on success, false on error.

    │ │ │ │

    See also: al_ustr_vappendf, │ │ │ │ al_ustr_append

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_vappendf

    │ │ │ │ 
    bool al_ustr_vappendf(ALLEGRO_USTR *us, const char *fmt, va_list ap)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Like al_ustr_appendf but you │ │ │ │ pass the variable argument list directly, instead of the arguments │ │ │ │ themselves. See al_ustr_newf about │ │ │ │ the “%s” and “%c” specifiers.

    │ │ │ │

    Returns true on success, false on error.

    │ │ │ │

    See also: al_ustr_appendf, al_ustr_append

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Removing parts of strings

    │ │ │ │

    al_ustr_remove_chr

    │ │ │ │ 
    bool al_ustr_remove_chr(ALLEGRO_USTR *us, int pos)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Remove the code point beginning at byte offset pos. │ │ │ │ Returns true on success. If pos is out of range or │ │ │ │ pos is not the beginning of a valid code point, returns │ │ │ │ false leaving the string unmodified.

    │ │ │ │

    Use al_ustr_offset to find the │ │ │ │ byte offset for a code-points offset.

    │ │ │ │

    See also: al_ustr_remove_range

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_remove_range

    │ │ │ │ 
    bool al_ustr_remove_range(ALLEGRO_USTR *us, int start_pos, int end_pos)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Remove the interval [start_pos, end_pos) │ │ │ │ from a string. start_pos and end_pos are byte │ │ │ │ offsets. Both may be past the end of the string but cannot be less than │ │ │ │ 0 (the start of the string).

    │ │ │ │

    Returns true on success, false on error.

    │ │ │ │

    See also: al_ustr_remove_chr, al_ustr_truncate

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_truncate

    │ │ │ │ 
    bool al_ustr_truncate(ALLEGRO_USTR *us, int start_pos)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Truncate a portion of a string from byte offset │ │ │ │ start_pos onwards. start_pos can be past the │ │ │ │ end of the string (has no effect) but cannot be less than 0.

    │ │ │ │

    Returns true on success, false on error.

    │ │ │ │

    See also: al_ustr_remove_range, al_ustr_ltrim_ws, al_ustr_rtrim_ws, al_ustr_trim_ws

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_ltrim_ws

    │ │ │ │ 
    bool al_ustr_ltrim_ws(ALLEGRO_USTR *us)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Remove leading whitespace characters from a string, as defined by the │ │ │ │ C function isspace().

    │ │ │ │

    Returns true on success, or false on error.

    │ │ │ │

    See also: al_ustr_rtrim_ws, │ │ │ │ al_ustr_trim_ws

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_rtrim_ws

    │ │ │ │ 
    bool al_ustr_rtrim_ws(ALLEGRO_USTR *us)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Remove trailing (“right”) whitespace characters from a string, as │ │ │ │ defined by the C function isspace().

    │ │ │ │

    Returns true on success, or false on error.

    │ │ │ │

    See also: al_ustr_ltrim_ws, │ │ │ │ al_ustr_trim_ws

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_trim_ws

    │ │ │ │ 
    bool al_ustr_trim_ws(ALLEGRO_USTR *us)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Remove both leading and trailing whitespace characters from a │ │ │ │ string.

    │ │ │ │

    Returns true on success, or false on error.

    │ │ │ │

    See also: al_ustr_ltrim_ws, │ │ │ │ al_ustr_rtrim_ws

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Assigning one string to │ │ │ │ another

    │ │ │ │

    al_ustr_assign

    │ │ │ │ 
    bool al_ustr_assign(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Overwrite the string us1 with another string │ │ │ │ us2. Returns true on success, false on error.

    │ │ │ │

    See also: al_ustr_assign_substr, al_ustr_assign_cstr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_assign_substr

    │ │ │ │ 
    bool al_ustr_assign_substr(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2,
│ │ │ │     int start_pos, int end_pos)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Overwrite the string us1 with the contents of │ │ │ │ @@ -964,25 +1216,35 @@ │ │ │ │ us2.

    │ │ │ │

    Usually you will first have to use al_ustr_offset to find the byte │ │ │ │ offsets.

    │ │ │ │

    Returns true on success, false on error.

    │ │ │ │

    See also: al_ustr_assign, al_ustr_assign_cstr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_assign_cstr

    │ │ │ │ 
    bool al_ustr_assign_cstr(ALLEGRO_USTR *us1, const char *s)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Overwrite the string us1 with the contents of the │ │ │ │ C-style string s. Returns true on success, false on │ │ │ │ error.

    │ │ │ │

    See also: al_ustr_assign_substr, al_ustr_assign_cstr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Replacing parts of string

    │ │ │ │

    al_ustr_set_chr

    │ │ │ │ 
    size_t al_ustr_set_chr(ALLEGRO_USTR *us, int start_pos, int32_t c)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Replace the code point beginning at byte offset │ │ │ │ @@ -992,14 +1254,21 @@ │ │ │ │ start_pos will be padded with NUL ('\0') │ │ │ │ bytes. If start_pos is not the start of a valid code point, │ │ │ │ that is an error and the string will be unmodified.

    │ │ │ │

    On success, returns the number of bytes written, i.e. the offset to │ │ │ │ the following code point. On error, returns 0.

    │ │ │ │

    See also: al_ustr_replace_range

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_replace_range

    │ │ │ │ 
    bool al_ustr_replace_range(ALLEGRO_USTR *us1, int start_pos1, int end_pos1,
│ │ │ │     const ALLEGRO_USTR *us2)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Replace the part of us1 in the byte interval │ │ │ │ @@ -1008,60 +1277,85 @@ │ │ │ │ start_pos1 is past the end of us1 then the │ │ │ │ space between the end of the string and start_pos1 will be │ │ │ │ padded with NUL ('\0') bytes.

    │ │ │ │

    Use al_ustr_offset to find the │ │ │ │ byte offsets.

    │ │ │ │

    Returns true on success, false on error.

    │ │ │ │

    See also: al_ustr_set_chr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Searching

    │ │ │ │

    al_ustr_find_chr

    │ │ │ │ 
    int al_ustr_find_chr(const ALLEGRO_USTR *us, int start_pos, int32_t c)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Search for the encoding of code point c in │ │ │ │ us from byte offset start_pos (inclusive).

    │ │ │ │

    Returns the position where it is found or -1 if it is not found.

    │ │ │ │

    See also: al_ustr_rfind_chr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_rfind_chr

    │ │ │ │ 
    int al_ustr_rfind_chr(const ALLEGRO_USTR *us, int end_pos, int32_t c)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Search for the encoding of code point c in │ │ │ │ us backwards from byte offset end_pos │ │ │ │ (exclusive). Returns the position where it is found or -1 if it is not │ │ │ │ found.

    │ │ │ │

    See also: al_ustr_find_chr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_find_set

    │ │ │ │ 
    int al_ustr_find_set(const ALLEGRO_USTR *us, int start_pos,
│ │ │ │     const ALLEGRO_USTR *accept)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    This function finds the first code point in us, │ │ │ │ beginning from byte offset start_pos, that matches any code │ │ │ │ point in accept. Returns the position if a code point was │ │ │ │ found. Otherwise returns -1.

    │ │ │ │

    See also: al_ustr_find_set_cstr, al_ustr_find_cset

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_find_set_cstr

    │ │ │ │ 
    int al_ustr_find_set_cstr(const ALLEGRO_USTR *us, int start_pos,
│ │ │ │     const char *accept)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Like al_ustr_find_set but │ │ │ │ takes a C-style string for accept.

    │ │ │ │

    See also: al_ustr_find_set, │ │ │ │ al_ustr_find_cset_cstr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_find_cset

    │ │ │ │ 
    int al_ustr_find_cset(const ALLEGRO_USTR *us, int start_pos,
│ │ │ │     const ALLEGRO_USTR *reject)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    This function finds the first code point in us, │ │ │ │ @@ -1069,186 +1363,275 @@ │ │ │ │ not match any code point in reject. In other words │ │ │ │ it finds a code point in the complementary set of reject. │ │ │ │ Returns the byte position of that code point, if any. Otherwise returns │ │ │ │ -1.

    │ │ │ │

    See also: al_ustr_find_cset_cstr, al_ustr_find_set

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_find_cset_cstr

    │ │ │ │ 
    int al_ustr_find_cset_cstr(const ALLEGRO_USTR *us, int start_pos,
│ │ │ │     const char *reject)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Like al_ustr_find_cset but │ │ │ │ takes a C-style string for reject.

    │ │ │ │

    See also: al_ustr_find_cset, al_ustr_find_set_cstr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_find_str

    │ │ │ │ 
    int al_ustr_find_str(const ALLEGRO_USTR *haystack, int start_pos,
│ │ │ │     const ALLEGRO_USTR *needle)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Find the first occurrence of string needle in │ │ │ │ haystack, beginning from byte offset start_pos │ │ │ │ (inclusive). Return the byte offset of the occurrence if it is found, │ │ │ │ otherwise return -1.

    │ │ │ │

    See also: al_ustr_find_cstr, al_ustr_rfind_str, al_ustr_find_replace

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_find_cstr

    │ │ │ │ 
    int al_ustr_find_cstr(const ALLEGRO_USTR *haystack, int start_pos,
│ │ │ │     const char *needle)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Like al_ustr_find_str but │ │ │ │ takes a C-style string for needle.

    │ │ │ │

    See also: al_ustr_find_str, │ │ │ │ al_ustr_rfind_cstr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_rfind_str

    │ │ │ │ 
    int al_ustr_rfind_str(const ALLEGRO_USTR *haystack, int end_pos,
│ │ │ │     const ALLEGRO_USTR *needle)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Find the last occurrence of string needle in │ │ │ │ haystack before byte offset end_pos │ │ │ │ (exclusive). Return the byte offset of the occurrence if it is found, │ │ │ │ otherwise return -1.

    │ │ │ │

    See also: al_ustr_rfind_cstr, al_ustr_find_str

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_rfind_cstr

    │ │ │ │ 
    int al_ustr_rfind_cstr(const ALLEGRO_USTR *haystack, int end_pos,
│ │ │ │     const char *needle)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Like al_ustr_rfind_str but │ │ │ │ takes a C-style string for needle.

    │ │ │ │

    See also: al_ustr_rfind_str, al_ustr_find_cstr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_find_replace

    │ │ │ │ 
    bool al_ustr_find_replace(ALLEGRO_USTR *us, int start_pos,
│ │ │ │     const ALLEGRO_USTR *find, const ALLEGRO_USTR *replace)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Replace all occurrences of find in us with │ │ │ │ replace, beginning at byte offset start_pos. │ │ │ │ The find string must be non-empty. Returns true on success, │ │ │ │ false on error.

    │ │ │ │

    See also: al_ustr_find_replace_cstr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_find_replace_cstr

    │ │ │ │ 
    bool al_ustr_find_replace_cstr(ALLEGRO_USTR *us, int start_pos,
│ │ │ │     const char *find, const char *replace)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Like al_ustr_find_replace but takes │ │ │ │ C-style strings for find and replace.

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Comparing

    │ │ │ │

    al_ustr_equal

    │ │ │ │ 
    bool al_ustr_equal(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Return true iff the two strings are equal. This function is more │ │ │ │ efficient than al_ustr_compare │ │ │ │ so is preferable if ordering is not important.

    │ │ │ │

    See also: al_ustr_compare

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_compare

    │ │ │ │ 
    int al_ustr_compare(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    This function compares us1 and us2 by code │ │ │ │ point values. Returns zero if the strings are equal, a positive number │ │ │ │ if us1 comes after us2, else a negative │ │ │ │ number.

    │ │ │ │

    This does not take into account locale-specific sorting │ │ │ │ rules. For that you will need to use another library.

    │ │ │ │

    See also: al_ustr_ncompare, │ │ │ │ al_ustr_equal

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_ncompare

    │ │ │ │ 
    int al_ustr_ncompare(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2, int n)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Like al_ustr_compare but only │ │ │ │ compares up to the first n code points of both strings.

    │ │ │ │

    Returns zero if the strings are equal, a positive number if │ │ │ │ us1 comes after us2, else a negative │ │ │ │ number.

    │ │ │ │

    See also: al_ustr_compare, al_ustr_equal

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_has_prefix

    │ │ │ │ 
    bool al_ustr_has_prefix(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true iff us1 begins with us2.

    │ │ │ │

    See also: al_ustr_has_prefix_cstr, al_ustr_has_suffix

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_has_prefix_cstr

    │ │ │ │ 
    bool al_ustr_has_prefix_cstr(const ALLEGRO_USTR *us1, const char *s2)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true iff us1 begins with s2.

    │ │ │ │

    See also: al_ustr_has_prefix, al_ustr_has_suffix_cstr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_has_suffix

    │ │ │ │ 
    bool al_ustr_has_suffix(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true iff us1 ends with us2.

    │ │ │ │

    See also: al_ustr_has_suffix_cstr, al_ustr_has_prefix

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_has_suffix_cstr

    │ │ │ │ 
    bool al_ustr_has_suffix_cstr(const ALLEGRO_USTR *us1, const char *s2)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true iff us1 ends with s2.

    │ │ │ │

    See also: al_ustr_has_suffix, al_ustr_has_prefix_cstr

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    UTF-16 conversion

    │ │ │ │

    al_ustr_new_from_utf16

    │ │ │ │ 
    ALLEGRO_USTR *al_ustr_new_from_utf16(uint16_t const *s)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Create a new string containing a copy of the 0-terminated string │ │ │ │ s which must be encoded as UTF-16. The string must │ │ │ │ eventually be freed with al_ustr_free.

    │ │ │ │

    See also: al_ustr_new

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_size_utf16

    │ │ │ │ 
    size_t al_ustr_size_utf16(const ALLEGRO_USTR *us)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the number of bytes required to encode the string in UTF-16 │ │ │ │ (including the terminating 0). Usually called before al_ustr_encode_utf16 to │ │ │ │ determine the size of the buffer to allocate.

    │ │ │ │

    See also: al_ustr_size

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_ustr_encode_utf16

    │ │ │ │ 
    size_t al_ustr_encode_utf16(const ALLEGRO_USTR *us, uint16_t *s,
│ │ │ │     size_t n)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Encode the string into the given buffer, in UTF-16. Returns the │ │ │ │ @@ -1256,37 +1639,56 @@ │ │ │ │ written. The minimum size to encode the complete string can be queried │ │ │ │ with al_ustr_size_utf16. If │ │ │ │ the n parameter is smaller than that, the string will be │ │ │ │ truncated but still always 0 terminated.

    │ │ │ │

    See also: al_ustr_size_utf16, al_utf16_encode

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Low-level UTF-8 routines

    │ │ │ │

    al_utf8_width

    │ │ │ │ 
    size_t al_utf8_width(int32_t c)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the number of bytes that would be occupied by the specified │ │ │ │ code point when encoded in UTF-8. This is between 1 and 4 bytes for │ │ │ │ legal code point values. Otherwise returns 0.

    │ │ │ │

    See also: al_utf8_encode, al_utf16_width

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_utf8_encode

    │ │ │ │ 
    size_t al_utf8_encode(char s[], int32_t c)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Encode the specified code point to UTF-8 into the buffer │ │ │ │ s. The buffer must have enough space to hold the encoding, │ │ │ │ which takes between 1 and 4 bytes. This routine will refuse to encode │ │ │ │ code points above 0x10FFFF.

    │ │ │ │

    Returns the number of bytes written, which is the same as that │ │ │ │ returned by al_utf8_width.

    │ │ │ │

    See also: al_utf16_encode

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    Low-level UTF-16 routines

    │ │ │ │

    al_utf16_width

    │ │ │ │ 
    size_t al_utf16_width(int c)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the number of bytes that would be occupied by the specified │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -195,35 +195,49 @@ │ │ │ │ │ ************ UUTTFF--88 ssttrriinngg ttyyppeess ************ │ │ │ │ │ ********** AALLLLEEGGRROO__UUSSTTRR ********** │ │ │ │ │ typedef struct _al_tagbstring ALLEGRO_USTR; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ An opaque type representing a string. ALLEGRO_USTRs normally contain UTF- │ │ │ │ │ 8 encoded strings, but they may be used to hold any byte sequences, including │ │ │ │ │ NULs. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t___m_u_l_t_i_l_i_n_e_._c_p_p │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ + * _e_x___b_l_e_n_d_._c │ │ │ │ │ ********** AALLLLEEGGRROO__UUSSTTRR__IINNFFOO ********** │ │ │ │ │ typedef struct _al_tagbstring ALLEGRO_USTR_INFO; │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ A type that holds additional information for an _A_L_L_E_G_R_O___U_S_T_R that references an │ │ │ │ │ external memory buffer. You can convert it back to _A_L_L_E_G_R_O___U_S_T_R via │ │ │ │ │ _a_l___r_e_f___i_n_f_o. │ │ │ │ │ See also: _a_l___r_e_f___c_s_t_r, _a_l___r_e_f___b_u_f_f_e_r, _a_l___r_e_f___i_n_f_o and _a_l___r_e_f___u_s_t_r. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t___m_u_l_t_i_l_i_n_e_._c_p_p │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ + * _e_x___b_l_e_n_d_._c │ │ │ │ │ ************ CCrreeaattiinngg aanndd ddeessttrrooyyiinngg ssttrriinnggss ************ │ │ │ │ │ ********** aall__uussttrr__nneeww ********** │ │ │ │ │ ALLEGRO_USTR *al_ustr_new(const char *s) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Create a new string containing a copy of the C-style string s. The string must │ │ │ │ │ eventually be freed with _a_l___u_s_t_r___f_r_e_e. │ │ │ │ │ See also: _a_l___u_s_t_r___n_e_w___f_r_o_m___b_u_f_f_e_r, _a_l___u_s_t_r___n_e_w_f, _a_l___u_s_t_r___d_u_p, │ │ │ │ │ _a_l___u_s_t_r___n_e_w___f_r_o_m___u_t_f_1_6 │ │ │ │ │ +Examples: │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ + * _e_x___l_o_a_d_i_n_g___t_h_r_e_a_d_._c │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__nneeww__ffrroomm__bbuuffffeerr ********** │ │ │ │ │ ALLEGRO_USTR *al_ustr_new_from_buffer(const char *s, size_t size) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Create a new string containing a copy of the buffer pointed to by s of the │ │ │ │ │ given size in bytes. The string must eventually be freed with _a_l___u_s_t_r___f_r_e_e. │ │ │ │ │ See also: _a_l___u_s_t_r___n_e_w │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__nneewwff ********** │ │ │ │ │ ALLEGRO_USTR *al_ustr_newf(const char *fmt, ...) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Create a new string using a printf-style format string. │ │ │ │ │ NNootteess:: │ │ │ │ │ The “%s” specifier takes C string arguments, not ALLEGRO_USTRs. Therefore to │ │ │ │ │ pass an ALLEGRO_USTR as a parameter you must use _a_l___c_s_t_r, and it must be NUL │ │ │ │ │ @@ -231,19 +245,25 @@ │ │ │ │ │ byte onwards will be ignored. │ │ │ │ │ The “%c” specifier outputs a single byte, not the UTF-8 encoding of a code │ │ │ │ │ point. Therefore it is only usable for ASCII characters (value <= 127) or if │ │ │ │ │ you really mean to output byte values from 128–255. To insert the UTF- │ │ │ │ │ 8 encoding of a code point, encode it into a memory buffer using _a_l___u_t_f_8___e_n_c_o_d_e │ │ │ │ │ then use the “%s” specifier. Remember to NUL terminate the buffer. │ │ │ │ │ See also: _a_l___u_s_t_r___n_e_w, _a_l___u_s_t_r___a_p_p_e_n_d_f │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__ffrreeee ********** │ │ │ │ │ void al_ustr_free(ALLEGRO_USTR *us) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Free a previously allocated string. Does nothing if the argument is NULL. │ │ │ │ │ See also: _a_l___u_s_t_r___n_e_w, _a_l___u_s_t_r___n_e_w___f_r_o_m___b_u_f_f_e_r, _a_l___u_s_t_r___n_e_w_f │ │ │ │ │ +Examples: │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ + * _e_x___l_o_a_d_i_n_g___t_h_r_e_a_d_._c │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__ccssttrr ********** │ │ │ │ │ const char *al_cstr(const ALLEGRO_USTR *us) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get a char * pointer to the data in a string. This pointer will only be valid │ │ │ │ │ while the _A_L_L_E_G_R_O___U_S_T_R object is not modified and not destroyed. The pointer │ │ │ │ │ may be passed to functions expecting C-style strings, with the following │ │ │ │ │ caveats: │ │ │ │ │ @@ -253,74 +273,95 @@ │ │ │ │ │ terminated. A string which is dynamically allocated will always be NUL │ │ │ │ │ terminated, but a string which references the middle of another string or │ │ │ │ │ region of memory will nnoott be NUL terminated. │ │ │ │ │ * If the ALLEGRO_USTR references another string, the returned C string will │ │ │ │ │ point into the referenced string. Again, no NUL terminator will be added │ │ │ │ │ to the referenced string. │ │ │ │ │ See also: _a_l___u_s_t_r___t_o___b_u_f_f_e_r, _a_l___c_s_t_r___d_u_p │ │ │ │ │ +Examples: │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ + * _e_x___l_o_a_d_i_n_g___t_h_r_e_a_d_._c │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__ttoo__bbuuffffeerr ********** │ │ │ │ │ void al_ustr_to_buffer(const ALLEGRO_USTR *us, char *buffer, int size) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Write the contents of the string into a pre-allocated buffer of the given size │ │ │ │ │ in bytes. The result will always be NUL terminated, so a maximum of size - 1 │ │ │ │ │ bytes will be copied. │ │ │ │ │ See also: _a_l___c_s_t_r, _a_l___c_s_t_r___d_u_p │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__ccssttrr__dduupp ********** │ │ │ │ │ char *al_cstr_dup(const ALLEGRO_USTR *us) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Create a NUL ('\0') terminated copy of the string. Any embedded NUL bytes will │ │ │ │ │ still be presented in the returned string. The new string must eventually be │ │ │ │ │ freed with _a_l___f_r_e_e. │ │ │ │ │ If an error occurs NULL is returned. │ │ │ │ │ See also: _a_l___c_s_t_r, _a_l___u_s_t_r___t_o___b_u_f_f_e_r, _a_l___f_r_e_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__dduupp ********** │ │ │ │ │ ALLEGRO_USTR *al_ustr_dup(const ALLEGRO_USTR *us) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return a duplicate copy of a string. The new string will need to be freed with │ │ │ │ │ _a_l___u_s_t_r___f_r_e_e. │ │ │ │ │ See also: _a_l___u_s_t_r___d_u_p___s_u_b_s_t_r, _a_l___u_s_t_r___f_r_e_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__dduupp__ssuubbssttrr ********** │ │ │ │ │ ALLEGRO_USTR *al_ustr_dup_substr(const ALLEGRO_USTR *us, int start_pos, │ │ │ │ │ int end_pos) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return a new copy of a string, containing its contents in the byte interval │ │ │ │ │ [start_pos, end_pos). The new string will be NUL terminated and will need to be │ │ │ │ │ freed with _a_l___u_s_t_r___f_r_e_e. │ │ │ │ │ If necessary, use _a_l___u_s_t_r___o_f_f_s_e_t to find the byte offsets for a given code │ │ │ │ │ point that you are interested in. │ │ │ │ │ See also: _a_l___u_s_t_r___d_u_p, _a_l___u_s_t_r___f_r_e_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ************ PPrreeddeeffiinneedd ssttrriinnggss ************ │ │ │ │ │ ********** aall__uussttrr__eemmppttyy__ssttrriinngg ********** │ │ │ │ │ const ALLEGRO_USTR *al_ustr_empty_string(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return a pointer to a static empty string. The string is read only and must not │ │ │ │ │ be freed. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ************ CCrreeaattiinngg ssttrriinnggss bbyy rreeffeerreenncciinngg ootthheerr ddaattaa ************ │ │ │ │ │ ********** aall__rreeff__ccssttrr ********** │ │ │ │ │ const ALLEGRO_USTR *al_ref_cstr(ALLEGRO_USTR_INFO *info, const char *s) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Create a string that references the storage of a C-style string. The │ │ │ │ │ information about the string (e.g. its size) is stored in the structure pointed │ │ │ │ │ to by the info parameter. The string will not have any other storage allocated │ │ │ │ │ of its own, so if you allocate the info structure on the stack then no explicit │ │ │ │ │ “free” operation is required. │ │ │ │ │ The string is valid until the underlying C string disappears. │ │ │ │ │ Example: │ │ │ │ │ ALLEGRO_USTR_INFO info; │ │ │ │ │ ALLEGRO_USTR *us = al_ref_cstr(&info, "my string"); │ │ │ │ │ See also: _a_l___r_e_f___b_u_f_f_e_r, _a_l___r_e_f___u_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___b_l_e_n_d_._c │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ********** aall__rreeff__bbuuffffeerr ********** │ │ │ │ │ const ALLEGRO_USTR *al_ref_buffer(ALLEGRO_USTR_INFO *info, const char *s, │ │ │ │ │ size_t size) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Create a string that references the storage of an underlying buffer. The size │ │ │ │ │ of the buffer is given in bytes. You can use it to reference only part of a │ │ │ │ │ string or an arbitrary region of memory. │ │ │ │ │ The string is valid while the underlying memory buffer is valid. │ │ │ │ │ See also: _a_l___r_e_f___c_s_t_r, _a_l___r_e_f___u_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___f_o_n_t___m_u_l_t_i_l_i_n_e_._c_p_p │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__rreeff__uussttrr ********** │ │ │ │ │ const ALLEGRO_USTR *al_ref_ustr(ALLEGRO_USTR_INFO *info, const ALLEGRO_USTR │ │ │ │ │ *us, │ │ │ │ │ int start_pos, int end_pos) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Create a read-only string that references the storage of another _A_L_L_E_G_R_O___U_S_T_R │ │ │ │ │ string. The information about the string (e.g. its size) is stored in the │ │ │ │ │ @@ -328,14 +369,18 @@ │ │ │ │ │ other storage allocated of its own, so if you allocate the info structure on │ │ │ │ │ the stack then no explicit “free” operation is required. │ │ │ │ │ The referenced interval is [start_pos, end_pos). Both are byte offsets. │ │ │ │ │ The string is valid until the underlying string is modified or destroyed. │ │ │ │ │ If you need a range of code-points instead of bytes, use _a_l___u_s_t_r___o_f_f_s_e_t to find │ │ │ │ │ the byte offsets. │ │ │ │ │ See also: _a_l___r_e_f___c_s_t_r, _a_l___r_e_f___b_u_f_f_e_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ + * _e_x___b_l_e_n_d_._c │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__rreeff__iinnffoo ********** │ │ │ │ │ const ALLEGRO_USTR *al_ref_info(const ALLEGRO_USTR_INFO *info) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Create a read-only string that references the storage of another _A_L_L_E_G_R_O___U_S_T_R │ │ │ │ │ string that has already been stored in the _A_L_L_E_G_R_O___U_S_T_R___I_N_F_O structure. │ │ │ │ │ The string is valid until the underlying string is modified or destroyed. │ │ │ │ │ See also: _a_l___r_e_f___c_s_t_r, _a_l___r_e_f___b_u_f_f_e_r, _a_l___r_e_f___u_s_t_r │ │ │ │ │ @@ -343,405 +388,528 @@ │ │ │ │ │ ********** aall__uussttrr__ssiizzee ********** │ │ │ │ │ size_t al_ustr_size(const ALLEGRO_USTR *us) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the size of the string in bytes. This is equal to the number of code │ │ │ │ │ points in the string if the string is empty or contains only 7-bit ASCII │ │ │ │ │ characters. │ │ │ │ │ See also: _a_l___u_s_t_r___l_e_n_g_t_h │ │ │ │ │ +Examples: │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__lleennggtthh ********** │ │ │ │ │ size_t al_ustr_length(const ALLEGRO_USTR *us) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the number of code points in the string. │ │ │ │ │ See also: _a_l___u_s_t_r___s_i_z_e, _a_l___u_s_t_r___o_f_f_s_e_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___b_l_e_n_d_._c │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ********** aall__uussttrr__ooffffsseett ********** │ │ │ │ │ int al_ustr_offset(const ALLEGRO_USTR *us, int index) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the byte offset (from the start of the string) of the code point at the │ │ │ │ │ specified index in the string. A zero index parameter will return the first │ │ │ │ │ character of the string. If index is negative, it counts backward from the end │ │ │ │ │ of the string, so an index of -1 will return an offset to the last code point. │ │ │ │ │ If the index is past the end of the string, returns the offset of the end of │ │ │ │ │ the string. │ │ │ │ │ See also: _a_l___u_s_t_r___l_e_n_g_t_h │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___b_l_e_n_d_._c │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ********** aall__uussttrr__nneexxtt ********** │ │ │ │ │ bool al_ustr_next(const ALLEGRO_USTR *us, int *pos) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Find the byte offset of the next code point in string, beginning at *pos. *pos │ │ │ │ │ does not have to be at the beginning of a code point. │ │ │ │ │ Returns true on success, and the value pointed to by pos will be updated to the │ │ │ │ │ found offset. Otherwise returns false if *pos was already at the end of the │ │ │ │ │ string, and *pos is unmodified. │ │ │ │ │ This function just looks for an appropriate byte; it doesn’t check if found │ │ │ │ │ offset is the beginning of a valid code point. If you are working with possibly │ │ │ │ │ invalid UTF-8 strings then it could skip over some invalid bytes. │ │ │ │ │ See also: _a_l___u_s_t_r___p_r_e_v │ │ │ │ │ +Examples: │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__pprreevv ********** │ │ │ │ │ bool al_ustr_prev(const ALLEGRO_USTR *us, int *pos) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Find the byte offset of the previous code point in string, before *pos. *pos │ │ │ │ │ does not have to be at the beginning of a code point. Returns true on success, │ │ │ │ │ and the value pointed to by pos will be updated to the found offset. Otherwise │ │ │ │ │ returns false if *pos was already at the end of the string, and *pos is │ │ │ │ │ unmodified. │ │ │ │ │ This function just looks for an appropriate byte; it doesn’t check if found │ │ │ │ │ offset is the beginning of a valid code point. If you are working with possibly │ │ │ │ │ invalid UTF-8 strings then it could skip over some invalid bytes. │ │ │ │ │ See also: _a_l___u_s_t_r___n_e_x_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ + * _e_x___l_o_g_o_._c │ │ │ │ │ ************ GGeettttiinngg ccooddee ppooiinnttss ************ │ │ │ │ │ ********** aall__uussttrr__ggeett ********** │ │ │ │ │ int32_t al_ustr_get(const ALLEGRO_USTR *ub, int pos) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return the code point in ub beginning at byte offset pos. │ │ │ │ │ On success returns the code point value. If pos was out of bounds (e.g. past │ │ │ │ │ the end of the string), return -1. On an error, such as an invalid byte │ │ │ │ │ sequence, return -2. │ │ │ │ │ See also: _a_l___u_s_t_r___g_e_t___n_e_x_t, _a_l___u_s_t_r___p_r_e_v___g_e_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ + * _e_x___t_t_f_._c │ │ │ │ │ ********** aall__uussttrr__ggeett__nneexxtt ********** │ │ │ │ │ int32_t al_ustr_get_next(const ALLEGRO_USTR *us, int *pos) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Find the code point in us beginning at byte offset *pos, then advance to the │ │ │ │ │ next code point. │ │ │ │ │ On success return the code point value. If pos was out of bounds (e.g. past the │ │ │ │ │ end of the string), return -1. On an error, such as an invalid byte sequence, │ │ │ │ │ return -2. As with _a_l___u_s_t_r___n_e_x_t, invalid byte sequences may be skipped while │ │ │ │ │ advancing. │ │ │ │ │ See also: _a_l___u_s_t_r___g_e_t, _a_l___u_s_t_r___p_r_e_v___g_e_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__pprreevv__ggeett ********** │ │ │ │ │ int32_t al_ustr_prev_get(const ALLEGRO_USTR *us, int *pos) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Find the beginning of a code point before byte offset *pos, then return it. │ │ │ │ │ Note this performs a pprree--iinnccrreemmeenntt. │ │ │ │ │ On success returns the code point value. If pos was out of bounds (e.g. past │ │ │ │ │ the end of the string), return -1. On an error, such as an invalid byte │ │ │ │ │ sequence, return -2. As with _a_l___u_s_t_r___p_r_e_v, invalid byte sequences may be │ │ │ │ │ skipped while advancing. │ │ │ │ │ See also: _a_l___u_s_t_r___g_e_t___n_e_x_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ************ IInnsseerrttiinngg iinnttoo ssttrriinnggss ************ │ │ │ │ │ ********** aall__uussttrr__iinnsseerrtt ********** │ │ │ │ │ bool al_ustr_insert(ALLEGRO_USTR *us1, int pos, const ALLEGRO_USTR *us2) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Insert us2 into us1 beginning at byte offset pos. pos cannot be less than 0. If │ │ │ │ │ pos is past the end of us1 then the space between the end of the string and pos │ │ │ │ │ will be padded with NUL ('\0') bytes. │ │ │ │ │ If required, use _a_l___u_s_t_r___o_f_f_s_e_t to find the byte offset for a given code point │ │ │ │ │ index. │ │ │ │ │ Returns true on success, false on error. │ │ │ │ │ See also: _a_l___u_s_t_r___i_n_s_e_r_t___c_s_t_r, _a_l___u_s_t_r___i_n_s_e_r_t___c_h_r, _a_l___u_s_t_r___a_p_p_e_n_d, │ │ │ │ │ _a_l___u_s_t_r___o_f_f_s_e_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__iinnsseerrtt__ccssttrr ********** │ │ │ │ │ bool al_ustr_insert_cstr(ALLEGRO_USTR *us, int pos, const char *s) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___u_s_t_r___i_n_s_e_r_t but inserts a C-style string at byte offset pos. │ │ │ │ │ See also: _a_l___u_s_t_r___i_n_s_e_r_t, _a_l___u_s_t_r___i_n_s_e_r_t___c_h_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__iinnsseerrtt__cchhrr ********** │ │ │ │ │ size_t al_ustr_insert_chr(ALLEGRO_USTR *us, int pos, int32_t c) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Insert a code point into us beginning at byte offset pos. pos cannot be less │ │ │ │ │ than 0. If pos is past the end of us then the space between the end of the │ │ │ │ │ string and pos will be padded with NUL ('\0') bytes. │ │ │ │ │ Returns the number of bytes inserted, or 0 on error. │ │ │ │ │ See also: _a_l___u_s_t_r___i_n_s_e_r_t, _a_l___u_s_t_r___i_n_s_e_r_t___c_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ************ AAppppeennddiinngg ttoo ssttrriinnggss ************ │ │ │ │ │ ********** aall__uussttrr__aappppeenndd ********** │ │ │ │ │ bool al_ustr_append(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Append us2 to the end of us1. │ │ │ │ │ Returns true on success, false on error. │ │ │ │ │ This function can be used to append an arbitrary buffer: │ │ │ │ │ ALLEGRO_USTR_INFO info; │ │ │ │ │ al_ustr_append(us, al_ref_buffer(&info, buf, size)); │ │ │ │ │ See also: _a_l___u_s_t_r___a_p_p_e_n_d___c_s_t_r, _a_l___u_s_t_r___a_p_p_e_n_d___c_h_r, _a_l___u_s_t_r___a_p_p_e_n_d_f, │ │ │ │ │ _a_l___u_s_t_r___v_a_p_p_e_n_d_f │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___l_o_a_d_i_n_g___t_h_r_e_a_d_._c │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__aappppeenndd__ccssttrr ********** │ │ │ │ │ bool al_ustr_append_cstr(ALLEGRO_USTR *us, const char *s) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Append C-style string s to the end of us. │ │ │ │ │ Returns true on success, false on error. │ │ │ │ │ See also: _a_l___u_s_t_r___a_p_p_e_n_d │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___l_o_a_d_i_n_g___t_h_r_e_a_d_._c │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__aappppeenndd__cchhrr ********** │ │ │ │ │ size_t al_ustr_append_chr(ALLEGRO_USTR *us, int32_t c) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Append a code point to the end of us. │ │ │ │ │ Returns the number of bytes added, or 0 on error. │ │ │ │ │ See also: _a_l___u_s_t_r___a_p_p_e_n_d │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__aappppeennddff ********** │ │ │ │ │ bool al_ustr_appendf(ALLEGRO_USTR *us, const char *fmt, ...) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This function appends formatted output to the string us. fmt is a printf-style │ │ │ │ │ format string. See _a_l___u_s_t_r___n_e_w_f about the “%s” and “%c” specifiers. │ │ │ │ │ Returns true on success, false on error. │ │ │ │ │ See also: _a_l___u_s_t_r___v_a_p_p_e_n_d_f, _a_l___u_s_t_r___a_p_p_e_n_d │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__vvaappppeennddff ********** │ │ │ │ │ bool al_ustr_vappendf(ALLEGRO_USTR *us, const char *fmt, va_list ap) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___u_s_t_r___a_p_p_e_n_d_f but you pass the variable argument list directly, instead │ │ │ │ │ of the arguments themselves. See _a_l___u_s_t_r___n_e_w_f about the “%s” and “%c” │ │ │ │ │ specifiers. │ │ │ │ │ Returns true on success, false on error. │ │ │ │ │ See also: _a_l___u_s_t_r___a_p_p_e_n_d_f, _a_l___u_s_t_r___a_p_p_e_n_d │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ************ RReemmoovviinngg ppaarrttss ooff ssttrriinnggss ************ │ │ │ │ │ ********** aall__uussttrr__rreemmoovvee__cchhrr ********** │ │ │ │ │ bool al_ustr_remove_chr(ALLEGRO_USTR *us, int pos) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Remove the code point beginning at byte offset pos. Returns true on success. If │ │ │ │ │ pos is out of range or pos is not the beginning of a valid code point, returns │ │ │ │ │ false leaving the string unmodified. │ │ │ │ │ Use _a_l___u_s_t_r___o_f_f_s_e_t to find the byte offset for a code-points offset. │ │ │ │ │ See also: _a_l___u_s_t_r___r_e_m_o_v_e___r_a_n_g_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ + * _e_x___l_o_g_o_._c │ │ │ │ │ ********** aall__uussttrr__rreemmoovvee__rraannggee ********** │ │ │ │ │ bool al_ustr_remove_range(ALLEGRO_USTR *us, int start_pos, int end_pos) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Remove the interval [start_pos, end_pos) from a string. start_pos and end_pos │ │ │ │ │ are byte offsets. Both may be past the end of the string but cannot be less │ │ │ │ │ than 0 (the start of the string). │ │ │ │ │ Returns true on success, false on error. │ │ │ │ │ See also: _a_l___u_s_t_r___r_e_m_o_v_e___c_h_r, _a_l___u_s_t_r___t_r_u_n_c_a_t_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__ttrruunnccaattee ********** │ │ │ │ │ bool al_ustr_truncate(ALLEGRO_USTR *us, int start_pos) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Truncate a portion of a string from byte offset start_pos onwards. start_pos │ │ │ │ │ can be past the end of the string (has no effect) but cannot be less than 0. │ │ │ │ │ Returns true on success, false on error. │ │ │ │ │ See also: _a_l___u_s_t_r___r_e_m_o_v_e___r_a_n_g_e, _a_l___u_s_t_r___l_t_r_i_m___w_s, _a_l___u_s_t_r___r_t_r_i_m___w_s, │ │ │ │ │ _a_l___u_s_t_r___t_r_i_m___w_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__llttrriimm__wwss ********** │ │ │ │ │ bool al_ustr_ltrim_ws(ALLEGRO_USTR *us) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Remove leading whitespace characters from a string, as defined by the C │ │ │ │ │ function isspace(). │ │ │ │ │ Returns true on success, or false on error. │ │ │ │ │ See also: _a_l___u_s_t_r___r_t_r_i_m___w_s, _a_l___u_s_t_r___t_r_i_m___w_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__rrttrriimm__wwss ********** │ │ │ │ │ bool al_ustr_rtrim_ws(ALLEGRO_USTR *us) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Remove trailing (“right”) whitespace characters from a string, as defined by │ │ │ │ │ the C function isspace(). │ │ │ │ │ Returns true on success, or false on error. │ │ │ │ │ See also: _a_l___u_s_t_r___l_t_r_i_m___w_s, _a_l___u_s_t_r___t_r_i_m___w_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__ttrriimm__wwss ********** │ │ │ │ │ bool al_ustr_trim_ws(ALLEGRO_USTR *us) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Remove both leading and trailing whitespace characters from a string. │ │ │ │ │ Returns true on success, or false on error. │ │ │ │ │ See also: _a_l___u_s_t_r___l_t_r_i_m___w_s, _a_l___u_s_t_r___r_t_r_i_m___w_s │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___l_o_a_d_i_n_g___t_h_r_e_a_d_._c │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ************ AAssssiiggnniinngg oonnee ssttrriinngg ttoo aannootthheerr ************ │ │ │ │ │ ********** aall__uussttrr__aassssiiggnn ********** │ │ │ │ │ bool al_ustr_assign(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Overwrite the string us1 with another string us2. Returns true on success, │ │ │ │ │ false on error. │ │ │ │ │ See also: _a_l___u_s_t_r___a_s_s_i_g_n___s_u_b_s_t_r, _a_l___u_s_t_r___a_s_s_i_g_n___c_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__aassssiiggnn__ssuubbssttrr ********** │ │ │ │ │ bool al_ustr_assign_substr(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2, │ │ │ │ │ int start_pos, int end_pos) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Overwrite the string us1 with the contents of us2 in the byte interval │ │ │ │ │ [start_pos, end_pos). The end points will be clamped to the bounds of us2. │ │ │ │ │ Usually you will first have to use _a_l___u_s_t_r___o_f_f_s_e_t to find the byte offsets. │ │ │ │ │ Returns true on success, false on error. │ │ │ │ │ See also: _a_l___u_s_t_r___a_s_s_i_g_n, _a_l___u_s_t_r___a_s_s_i_g_n___c_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__aassssiiggnn__ccssttrr ********** │ │ │ │ │ bool al_ustr_assign_cstr(ALLEGRO_USTR *us1, const char *s) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Overwrite the string us1 with the contents of the C-style string s. Returns │ │ │ │ │ true on success, false on error. │ │ │ │ │ See also: _a_l___u_s_t_r___a_s_s_i_g_n___s_u_b_s_t_r, _a_l___u_s_t_r___a_s_s_i_g_n___c_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ************ RReeppllaacciinngg ppaarrttss ooff ssttrriinngg ************ │ │ │ │ │ ********** aall__uussttrr__sseett__cchhrr ********** │ │ │ │ │ size_t al_ustr_set_chr(ALLEGRO_USTR *us, int start_pos, int32_t c) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Replace the code point beginning at byte offset start_pos with c. start_pos │ │ │ │ │ cannot be less than 0. If start_pos is past the end of us then the space │ │ │ │ │ between the end of the string and start_pos will be padded with NUL ('\0') │ │ │ │ │ bytes. If start_pos is not the start of a valid code point, that is an error │ │ │ │ │ and the string will be unmodified. │ │ │ │ │ On success, returns the number of bytes written, i.e. the offset to the │ │ │ │ │ following code point. On error, returns 0. │ │ │ │ │ See also: _a_l___u_s_t_r___r_e_p_l_a_c_e___r_a_n_g_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ + * _e_x___l_o_g_o_._c │ │ │ │ │ ********** aall__uussttrr__rreeppllaaccee__rraannggee ********** │ │ │ │ │ bool al_ustr_replace_range(ALLEGRO_USTR *us1, int start_pos1, int end_pos1, │ │ │ │ │ const ALLEGRO_USTR *us2) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Replace the part of us1 in the byte interval [start_pos1, end_pos1) with the │ │ │ │ │ contents of us2. start_pos1 cannot be less than 0. If start_pos1 is past the │ │ │ │ │ end of us1 then the space between the end of the string and start_pos1 will be │ │ │ │ │ padded with NUL ('\0') bytes. │ │ │ │ │ Use _a_l___u_s_t_r___o_f_f_s_e_t to find the byte offsets. │ │ │ │ │ Returns true on success, false on error. │ │ │ │ │ See also: _a_l___u_s_t_r___s_e_t___c_h_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ************ SSeeaarrcchhiinngg ************ │ │ │ │ │ ********** aall__uussttrr__ffiinndd__cchhrr ********** │ │ │ │ │ int al_ustr_find_chr(const ALLEGRO_USTR *us, int start_pos, int32_t c) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Search for the encoding of code point c in us from byte offset start_pos │ │ │ │ │ (inclusive). │ │ │ │ │ Returns the position where it is found or -1 if it is not found. │ │ │ │ │ See also: _a_l___u_s_t_r___r_f_i_n_d___c_h_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__rrffiinndd__cchhrr ********** │ │ │ │ │ int al_ustr_rfind_chr(const ALLEGRO_USTR *us, int end_pos, int32_t c) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Search for the encoding of code point c in us backwards from byte offset │ │ │ │ │ end_pos (exclusive). Returns the position where it is found or -1 if it is not │ │ │ │ │ found. │ │ │ │ │ See also: _a_l___u_s_t_r___f_i_n_d___c_h_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__ffiinndd__sseett ********** │ │ │ │ │ int al_ustr_find_set(const ALLEGRO_USTR *us, int start_pos, │ │ │ │ │ const ALLEGRO_USTR *accept) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This function finds the first code point in us, beginning from byte offset │ │ │ │ │ start_pos, that matches any code point in accept. Returns the position if a │ │ │ │ │ code point was found. Otherwise returns -1. │ │ │ │ │ See also: _a_l___u_s_t_r___f_i_n_d___s_e_t___c_s_t_r, _a_l___u_s_t_r___f_i_n_d___c_s_e_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__ffiinndd__sseett__ccssttrr ********** │ │ │ │ │ int al_ustr_find_set_cstr(const ALLEGRO_USTR *us, int start_pos, │ │ │ │ │ const char *accept) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___u_s_t_r___f_i_n_d___s_e_t but takes a C-style string for accept. │ │ │ │ │ See also: _a_l___u_s_t_r___f_i_n_d___s_e_t, _a_l___u_s_t_r___f_i_n_d___c_s_e_t___c_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__ffiinndd__ccsseett ********** │ │ │ │ │ int al_ustr_find_cset(const ALLEGRO_USTR *us, int start_pos, │ │ │ │ │ const ALLEGRO_USTR *reject) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This function finds the first code point in us, beginning from byte offset │ │ │ │ │ start_pos, that does nnoott match any code point in reject. In other words it │ │ │ │ │ finds a code point in the complementary set of reject. Returns the byte │ │ │ │ │ position of that code point, if any. Otherwise returns -1. │ │ │ │ │ See also: _a_l___u_s_t_r___f_i_n_d___c_s_e_t___c_s_t_r, _a_l___u_s_t_r___f_i_n_d___s_e_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__ffiinndd__ccsseett__ccssttrr ********** │ │ │ │ │ int al_ustr_find_cset_cstr(const ALLEGRO_USTR *us, int start_pos, │ │ │ │ │ const char *reject) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___u_s_t_r___f_i_n_d___c_s_e_t but takes a C-style string for reject. │ │ │ │ │ See also: _a_l___u_s_t_r___f_i_n_d___c_s_e_t, _a_l___u_s_t_r___f_i_n_d___s_e_t___c_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__ffiinndd__ssttrr ********** │ │ │ │ │ int al_ustr_find_str(const ALLEGRO_USTR *haystack, int start_pos, │ │ │ │ │ const ALLEGRO_USTR *needle) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Find the first occurrence of string needle in haystack, beginning from byte │ │ │ │ │ offset start_pos (inclusive). Return the byte offset of the occurrence if it is │ │ │ │ │ found, otherwise return -1. │ │ │ │ │ See also: _a_l___u_s_t_r___f_i_n_d___c_s_t_r, _a_l___u_s_t_r___r_f_i_n_d___s_t_r, _a_l___u_s_t_r___f_i_n_d___r_e_p_l_a_c_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__ffiinndd__ccssttrr ********** │ │ │ │ │ int al_ustr_find_cstr(const ALLEGRO_USTR *haystack, int start_pos, │ │ │ │ │ const char *needle) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___u_s_t_r___f_i_n_d___s_t_r but takes a C-style string for needle. │ │ │ │ │ See also: _a_l___u_s_t_r___f_i_n_d___s_t_r, _a_l___u_s_t_r___r_f_i_n_d___c_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__rrffiinndd__ssttrr ********** │ │ │ │ │ int al_ustr_rfind_str(const ALLEGRO_USTR *haystack, int end_pos, │ │ │ │ │ const ALLEGRO_USTR *needle) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Find the last occurrence of string needle in haystack before byte offset │ │ │ │ │ end_pos (exclusive). Return the byte offset of the occurrence if it is found, │ │ │ │ │ otherwise return -1. │ │ │ │ │ See also: _a_l___u_s_t_r___r_f_i_n_d___c_s_t_r, _a_l___u_s_t_r___f_i_n_d___s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__rrffiinndd__ccssttrr ********** │ │ │ │ │ int al_ustr_rfind_cstr(const ALLEGRO_USTR *haystack, int end_pos, │ │ │ │ │ const char *needle) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___u_s_t_r___r_f_i_n_d___s_t_r but takes a C-style string for needle. │ │ │ │ │ See also: _a_l___u_s_t_r___r_f_i_n_d___s_t_r, _a_l___u_s_t_r___f_i_n_d___c_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__ffiinndd__rreeppllaaccee ********** │ │ │ │ │ bool al_ustr_find_replace(ALLEGRO_USTR *us, int start_pos, │ │ │ │ │ const ALLEGRO_USTR *find, const ALLEGRO_USTR *replace) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Replace all occurrences of find in us with replace, beginning at byte offset │ │ │ │ │ start_pos. The find string must be non-empty. Returns true on success, false on │ │ │ │ │ error. │ │ │ │ │ See also: _a_l___u_s_t_r___f_i_n_d___r_e_p_l_a_c_e___c_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___l_o_a_d_i_n_g___t_h_r_e_a_d_._c │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__ffiinndd__rreeppllaaccee__ccssttrr ********** │ │ │ │ │ bool al_ustr_find_replace_cstr(ALLEGRO_USTR *us, int start_pos, │ │ │ │ │ const char *find, const char *replace) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___u_s_t_r___f_i_n_d___r_e_p_l_a_c_e but takes C-style strings for find and replace. │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___l_o_a_d_i_n_g___t_h_r_e_a_d_._c │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ************ CCoommppaarriinngg ************ │ │ │ │ │ ********** aall__uussttrr__eeqquuaall ********** │ │ │ │ │ bool al_ustr_equal(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Return true iff the two strings are equal. This function is more efficient than │ │ │ │ │ _a_l___u_s_t_r___c_o_m_p_a_r_e so is preferable if ordering is not important. │ │ │ │ │ See also: _a_l___u_s_t_r___c_o_m_p_a_r_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__ccoommppaarree ********** │ │ │ │ │ int al_ustr_compare(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This function compares us1 and us2 by code point values. Returns zero if the │ │ │ │ │ strings are equal, a positive number if us1 comes after us2, else a negative │ │ │ │ │ number. │ │ │ │ │ This does nnoott take into account locale-specific sorting rules. For that you │ │ │ │ │ will need to use another library. │ │ │ │ │ See also: _a_l___u_s_t_r___n_c_o_m_p_a_r_e, _a_l___u_s_t_r___e_q_u_a_l │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__nnccoommppaarree ********** │ │ │ │ │ int al_ustr_ncompare(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2, int n) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___u_s_t_r___c_o_m_p_a_r_e but only compares up to the first n code points of both │ │ │ │ │ strings. │ │ │ │ │ Returns zero if the strings are equal, a positive number if us1 comes after │ │ │ │ │ us2, else a negative number. │ │ │ │ │ See also: _a_l___u_s_t_r___c_o_m_p_a_r_e, _a_l___u_s_t_r___e_q_u_a_l │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__hhaass__pprreeffiixx ********** │ │ │ │ │ bool al_ustr_has_prefix(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true iff us1 begins with us2. │ │ │ │ │ See also: _a_l___u_s_t_r___h_a_s___p_r_e_f_i_x___c_s_t_r, _a_l___u_s_t_r___h_a_s___s_u_f_f_i_x │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__hhaass__pprreeffiixx__ccssttrr ********** │ │ │ │ │ bool al_ustr_has_prefix_cstr(const ALLEGRO_USTR *us1, const char *s2) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true iff us1 begins with s2. │ │ │ │ │ See also: _a_l___u_s_t_r___h_a_s___p_r_e_f_i_x, _a_l___u_s_t_r___h_a_s___s_u_f_f_i_x___c_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__hhaass__ssuuffffiixx ********** │ │ │ │ │ bool al_ustr_has_suffix(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true iff us1 ends with us2. │ │ │ │ │ See also: _a_l___u_s_t_r___h_a_s___s_u_f_f_i_x___c_s_t_r, _a_l___u_s_t_r___h_a_s___p_r_e_f_i_x │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__hhaass__ssuuffffiixx__ccssttrr ********** │ │ │ │ │ bool al_ustr_has_suffix_cstr(const ALLEGRO_USTR *us1, const char *s2) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true iff us1 ends with s2. │ │ │ │ │ See also: _a_l___u_s_t_r___h_a_s___s_u_f_f_i_x, _a_l___u_s_t_r___h_a_s___p_r_e_f_i_x___c_s_t_r │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ************ UUTTFF--1166 ccoonnvveerrssiioonn ************ │ │ │ │ │ ********** aall__uussttrr__nneeww__ffrroomm__uuttff1166 ********** │ │ │ │ │ ALLEGRO_USTR *al_ustr_new_from_utf16(uint16_t const *s) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Create a new string containing a copy of the 0-terminated string s which must │ │ │ │ │ be encoded as UTF-16. The string must eventually be freed with _a_l___u_s_t_r___f_r_e_e. │ │ │ │ │ See also: _a_l___u_s_t_r___n_e_w │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__ssiizzee__uuttff1166 ********** │ │ │ │ │ size_t al_ustr_size_utf16(const ALLEGRO_USTR *us) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the number of bytes required to encode the string in UTF-16 (including │ │ │ │ │ the terminating 0). Usually called before _a_l___u_s_t_r___e_n_c_o_d_e___u_t_f_1_6 to determine the │ │ │ │ │ size of the buffer to allocate. │ │ │ │ │ See also: _a_l___u_s_t_r___s_i_z_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uussttrr__eennccooddee__uuttff1166 ********** │ │ │ │ │ size_t al_ustr_encode_utf16(const ALLEGRO_USTR *us, uint16_t *s, │ │ │ │ │ size_t n) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Encode the string into the given buffer, in UTF-16. Returns the number of bytes │ │ │ │ │ written. There are never more than n bytes written. The minimum size to encode │ │ │ │ │ the complete string can be queried with _a_l___u_s_t_r___s_i_z_e___u_t_f_1_6. If the n parameter │ │ │ │ │ is smaller than that, the string will be truncated but still always 0 │ │ │ │ │ terminated. │ │ │ │ │ See also: _a_l___u_s_t_r___s_i_z_e___u_t_f_1_6, _a_l___u_t_f_1_6___e_n_c_o_d_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ************ LLooww--lleevveell UUTTFF--88 rroouuttiinneess ************ │ │ │ │ │ ********** aall__uuttff88__wwiiddtthh ********** │ │ │ │ │ size_t al_utf8_width(int32_t c) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the number of bytes that would be occupied by the specified code point │ │ │ │ │ when encoded in UTF-8. This is between 1 and 4 bytes for legal code point │ │ │ │ │ values. Otherwise returns 0. │ │ │ │ │ See also: _a_l___u_t_f_8___e_n_c_o_d_e, _a_l___u_t_f_1_6___w_i_d_t_h │ │ │ │ │ +Examples: │ │ │ │ │ + * _n_i_h_g_u_i_._c_p_p │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ********** aall__uuttff88__eennccooddee ********** │ │ │ │ │ size_t al_utf8_encode(char s[], int32_t c) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Encode the specified code point to UTF-8 into the buffer s. The buffer must │ │ │ │ │ have enough space to hold the encoding, which takes between 1 and 4 bytes. This │ │ │ │ │ routine will refuse to encode code points above 0x10FFFF. │ │ │ │ │ Returns the number of bytes written, which is the same as that returned by │ │ │ │ │ _a_l___u_t_f_8___w_i_d_t_h. │ │ │ │ │ See also: _a_l___u_t_f_1_6___e_n_c_o_d_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___k_e_y_b_o_a_r_d___e_v_e_n_t_s_._c │ │ │ │ │ + * _e_x___u_t_f_8_._c │ │ │ │ │ ************ LLooww--lleevveell UUTTFF--1166 rroouuttiinneess ************ │ │ │ │ │ ********** aall__uuttff1166__wwiiddtthh ********** │ │ │ │ │ size_t al_utf16_width(int c) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the number of bytes that would be occupied by the specified code point │ │ │ │ │ when encoded in UTF-16. This is either 2 or 4 bytes for legal code point │ │ │ │ │ values. Otherwise returns 0. │ │ │ ├── ./usr/share/doc/allegro5-doc/refman/video.html │ │ │ │ @@ -290,14 +290,19 @@ │ │ │ │

    al_init_video_addon

    │ │ │ │ 
    bool al_init_video_addon(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Initializes the video addon.

    │ │ │ │

    Since: 5.1.12

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_is_video_addon_initialized

    │ │ │ │ 
    bool al_is_video_addon_initialized(void)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true if the video addon is initialized, otherwise returns │ │ │ │ @@ -323,14 +328,19 @@ │ │ │ │ 

    ALLEGRO_VIDEO *al_open_video(char const *filename)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Reads a video file. This does not start playing yet but reads the │ │ │ │ meta info so you can query e.g. the size or audio rate.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_identify_video

    │ │ │ │ 
    char const *al_identify_video(char const *filename)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    This works exactly as al_identify_video_f but you │ │ │ │ @@ -362,21 +372,31 @@ │ │ │ │ 

    void al_close_video(ALLEGRO_VIDEO *video)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Closes the video and frees all allocated resources. The video pointer │ │ │ │ is invalid after the function returns.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_start_video

    │ │ │ │ 
    void al_start_video(ALLEGRO_VIDEO *video, ALLEGRO_MIXER *mixer)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Starts playing the video from the beginning.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_start_video_with_voice

    │ │ │ │ 
    void al_start_video_with_voice(ALLEGRO_VIDEO *video, ALLEGRO_VOICE *voice)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Like al_start_video but audio │ │ │ │ is routed to the provided voice.

    │ │ │ │ @@ -386,65 +406,100 @@ │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Get an event source for the video. The possible events are described │ │ │ │ under ALLEGRO_VIDEO_EVENT_TYPE.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_set_video_playing

    │ │ │ │ 
    void al_set_video_playing(ALLEGRO_VIDEO *video, bool play)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Paused or resumes playback.

    │ │ │ │

    Since: 5.1.12

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_is_video_playing

    │ │ │ │ 
    bool al_is_video_playing(ALLEGRO_VIDEO *video)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns true if the video is currently playing.

    │ │ │ │

    Since: 5.1.12

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_video_audio_rate

    │ │ │ │ 
    double al_get_video_audio_rate(ALLEGRO_VIDEO *video)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the audio rate of the video, in Hz.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_video_fps

    │ │ │ │ 
    double al_get_video_fps(ALLEGRO_VIDEO *video)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the speed of the video in frames per second. Often this will │ │ │ │ not be an integer value.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_video_scaled_width

    │ │ │ │ 
    float al_get_video_scaled_width(ALLEGRO_VIDEO *video)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the width with which the video frame should be drawn. Videos │ │ │ │ often do not use square pixels, so this will may return a value larger │ │ │ │ than the width of the frame bitmap.

    │ │ │ │

    Since: 5.1.12

    │ │ │ │

    See also: al_get_video_frame

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_video_scaled_height

    │ │ │ │ 
    float al_get_video_scaled_height(ALLEGRO_VIDEO *video)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the height with which the video frame should be drawn. Videos │ │ │ │ often do not use square pixels, so this will may return a value larger │ │ │ │ than the height of the frame bitmap.

    │ │ │ │

    See also: al_get_video_frame

    │ │ │ │

    Since: 5.1.12

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_video_frame

    │ │ │ │ 
    ALLEGRO_BITMAP *al_get_video_frame(ALLEGRO_VIDEO *video)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the current video frame. The bitmap is owned by the video so │ │ │ │ do not attempt to free it. The bitmap will stay valid until the next │ │ │ │ @@ -459,29 +514,47 @@ │ │ │ │ float dh = scale * al_get_video_scaled_height(video); │ │ │ │ al_draw_scaled_bitmap(frame, 0, 0, sw, sh, 0, 0, dw, dh, 0); │ │ │ │

    Since: 5.1.0

    │ │ │ │

    See also: al_get_video_scaled_width, │ │ │ │ al_get_video_scaled_height

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_get_video_position

    │ │ │ │ 
    double al_get_video_position(ALLEGRO_VIDEO *video, ALLEGRO_VIDEO_POSITION_TYPE which)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Returns the current position of the video stream in seconds since the │ │ │ │ beginning. The parameter is one of the ALLEGRO_VIDEO_POSITION_TYPE │ │ │ │ constants.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │

    al_seek_video

    │ │ │ │ 
    bool al_seek_video(ALLEGRO_VIDEO *video, double pos_in_seconds)
    │ │ │ │

    Source │ │ │ │ Code

    │ │ │ │

    Seek to a different position in the video. Currently only seeking to │ │ │ │ the beginning of the video is supported.

    │ │ │ │

    Since: 5.1.0

    │ │ │ │ - │ │ │ │ +

    Examples:

    │ │ │ │ + │ │ │ │ +

    │ │ │ │ +Allegro version 5.2.10 │ │ │ │ + - Last updated: 2025-01-09 13:52:42 UTC │ │ │ │ +

    │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ├── html2text {} │ │ │ │ │ @@ -109,14 +109,16 @@ │ │ │ │ │ in sync. │ │ │ │ │ Since: 5.1.11 │ │ │ │ │ ************ aall__iinniitt__vviiddeeoo__aaddddoonn ************ │ │ │ │ │ bool al_init_video_addon(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Initializes the video addon. │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___v_i_d_e_o_._c │ │ │ │ │ ************ aall__iiss__vviiddeeoo__aaddddoonn__iinniittiiaalliizzeedd ************ │ │ │ │ │ bool al_is_video_addon_initialized(void) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true if the video addon is initialized, otherwise returns false. │ │ │ │ │ Since: 5.2.6 │ │ │ │ │ ************ aall__sshhuuttddoowwnn__vviiddeeoo__aaddddoonn ************ │ │ │ │ │ void al_shutdown_video_addon(void) │ │ │ │ │ @@ -132,14 +134,16 @@ │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ ************ aall__ooppeenn__vviiddeeoo ************ │ │ │ │ │ ALLEGRO_VIDEO *al_open_video(char const *filename) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Reads a video file. This does not start playing yet but reads the meta info so │ │ │ │ │ you can query e.g. the size or audio rate. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___v_i_d_e_o_._c │ │ │ │ │ ************ aall__iiddeennttiiffyy__vviiddeeoo ************ │ │ │ │ │ char const *al_identify_video(char const *filename) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ This works exactly as _a_l___i_d_e_n_t_i_f_y___v_i_d_e_o___f but you specify the filename of the │ │ │ │ │ file for which to detect the type and not a file handle. The extension, if any, │ │ │ │ │ of the passed filename is not taken into account - only the file contents. │ │ │ │ │ Since: 5.2.8 │ │ │ │ │ @@ -157,67 +161,85 @@ │ │ │ │ │ See also: _a_l___i_n_i_t___v_i_d_e_o___a_d_d_o_n, _a_l___i_d_e_n_t_i_f_y___v_i_d_e_o │ │ │ │ │ ************ aall__cclloossee__vviiddeeoo ************ │ │ │ │ │ void al_close_video(ALLEGRO_VIDEO *video) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Closes the video and frees all allocated resources. The video pointer is │ │ │ │ │ invalid after the function returns. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___v_i_d_e_o_._c │ │ │ │ │ ************ aall__ssttaarrtt__vviiddeeoo ************ │ │ │ │ │ void al_start_video(ALLEGRO_VIDEO *video, ALLEGRO_MIXER *mixer) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Starts playing the video from the beginning. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___v_i_d_e_o_._c │ │ │ │ │ ************ aall__ssttaarrtt__vviiddeeoo__wwiitthh__vvooiiccee ************ │ │ │ │ │ void al_start_video_with_voice(ALLEGRO_VIDEO *video, ALLEGRO_VOICE *voice) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Like _a_l___s_t_a_r_t___v_i_d_e_o but audio is routed to the provided voice. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ ************ aall__ggeett__vviiddeeoo__eevveenntt__ssoouurrccee ************ │ │ │ │ │ ALLEGRO_EVENT_SOURCE *al_get_video_event_source(ALLEGRO_VIDEO *video) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Get an event source for the video. The possible events are described under │ │ │ │ │ _A_L_L_E_G_R_O___V_I_D_E_O___E_V_E_N_T___T_Y_P_E. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___v_i_d_e_o_._c │ │ │ │ │ ************ aall__sseett__vviiddeeoo__ppllaayyiinngg ************ │ │ │ │ │ void al_set_video_playing(ALLEGRO_VIDEO *video, bool play) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Paused or resumes playback. │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___v_i_d_e_o_._c │ │ │ │ │ ************ aall__iiss__vviiddeeoo__ppllaayyiinngg ************ │ │ │ │ │ bool al_is_video_playing(ALLEGRO_VIDEO *video) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns true if the video is currently playing. │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___v_i_d_e_o_._c │ │ │ │ │ ************ aall__ggeett__vviiddeeoo__aauuddiioo__rraattee ************ │ │ │ │ │ double al_get_video_audio_rate(ALLEGRO_VIDEO *video) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the audio rate of the video, in Hz. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___v_i_d_e_o_._c │ │ │ │ │ ************ aall__ggeett__vviiddeeoo__ffppss ************ │ │ │ │ │ double al_get_video_fps(ALLEGRO_VIDEO *video) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the speed of the video in frames per second. Often this will not be an │ │ │ │ │ integer value. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___v_i_d_e_o_._c │ │ │ │ │ ************ aall__ggeett__vviiddeeoo__ssccaalleedd__wwiiddtthh ************ │ │ │ │ │ float al_get_video_scaled_width(ALLEGRO_VIDEO *video) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the width with which the video frame should be drawn. Videos often do │ │ │ │ │ not use square pixels, so this will may return a value larger than the width of │ │ │ │ │ the frame bitmap. │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ See also: _a_l___g_e_t___v_i_d_e_o___f_r_a_m_e │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___v_i_d_e_o_._c │ │ │ │ │ ************ aall__ggeett__vviiddeeoo__ssccaalleedd__hheeiigghhtt ************ │ │ │ │ │ float al_get_video_scaled_height(ALLEGRO_VIDEO *video) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the height with which the video frame should be drawn. Videos often do │ │ │ │ │ not use square pixels, so this will may return a value larger than the height │ │ │ │ │ of the frame bitmap. │ │ │ │ │ See also: _a_l___g_e_t___v_i_d_e_o___f_r_a_m_e │ │ │ │ │ Since: 5.1.12 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___v_i_d_e_o_._c │ │ │ │ │ ************ aall__ggeett__vviiddeeoo__ffrraammee ************ │ │ │ │ │ ALLEGRO_BITMAP *al_get_video_frame(ALLEGRO_VIDEO *video) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the current video frame. The bitmap is owned by the video so do not │ │ │ │ │ attempt to free it. The bitmap will stay valid until the next call to │ │ │ │ │ al_get_video_frame. │ │ │ │ │ Videos often do not use square pixels so the recommended way to draw a video │ │ │ │ │ @@ -227,20 +249,27 @@ │ │ │ │ │ float sw = al_get_bitmap_width(frame); │ │ │ │ │ float sh = al_get_bitmap_height(frame); │ │ │ │ │ float dw = scale * al_get_video_scaled_width(video); │ │ │ │ │ float dh = scale * al_get_video_scaled_height(video); │ │ │ │ │ al_draw_scaled_bitmap(frame, 0, 0, sw, sh, 0, 0, dw, dh, 0); │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ See also: _a_l___g_e_t___v_i_d_e_o___s_c_a_l_e_d___w_i_d_t_h, _a_l___g_e_t___v_i_d_e_o___s_c_a_l_e_d___h_e_i_g_h_t │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___v_i_d_e_o_._c │ │ │ │ │ ************ aall__ggeett__vviiddeeoo__ppoossiittiioonn ************ │ │ │ │ │ double al_get_video_position(ALLEGRO_VIDEO *video, ALLEGRO_VIDEO_POSITION_TYPE │ │ │ │ │ which) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Returns the current position of the video stream in seconds since the │ │ │ │ │ beginning. The parameter is one of the _A_L_L_E_G_R_O___V_I_D_E_O___P_O_S_I_T_I_O_N___T_Y_P_E constants. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___v_i_d_e_o_._c │ │ │ │ │ ************ aall__sseeeekk__vviiddeeoo ************ │ │ │ │ │ bool al_seek_video(ALLEGRO_VIDEO *video, double pos_in_seconds) │ │ │ │ │ _S_o_u_r_c_e_ _C_o_d_e │ │ │ │ │ Seek to a different position in the video. Currently only seeking to the │ │ │ │ │ beginning of the video is supported. │ │ │ │ │ Since: 5.1.0 │ │ │ │ │ +Examples: │ │ │ │ │ + * _e_x___v_i_d_e_o_._c │ │ │ │ │ +Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC ├── liballegro5-dev_5.2.10.1+dfsg-1_amd64.deb │ ├── control.tar.xz │ │ ├── control.tar │ │ │ ├── ./md5sums │ │ │ │ ├── ./md5sums │ │ │ │ │┄ Files differ │ ├── data.tar.xz │ │ ├── data.tar │ │ │ ├── file list │ │ │ │ @@ -93,15 +93,15 @@ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/include/x86_64-linux-gnu/allegro5/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/include/x86_64-linux-gnu/allegro5/platform/ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 3996 2025-01-09 13:52:42.000000 ./usr/include/x86_64-linux-gnu/allegro5/platform/alplatf.h │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/lib/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/cmake/ │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/cmake/allegro/ │ │ │ │ --rw-r--r-- 0 root (0) root (0) 1609 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/cmake/allegro/AllegroConfig.cmake │ │ │ │ +-rw-r--r-- 0 root (0) root (0) 1606 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/cmake/allegro/AllegroConfig.cmake │ │ │ │ -rw-r--r-- 0 root (0) root (0) 1862 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/cmake/allegro/AllegroConfigVersion.cmake │ │ │ │ -rw-r--r-- 0 root (0) root (0) 7642 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/cmake/allegro/AllegroTargets-none.cmake │ │ │ │ -rw-r--r-- 0 root (0) root (0) 9526 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/cmake/allegro/AllegroTargets.cmake │ │ │ │ drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/pkgconfig/ │ │ │ │ -rw-r--r-- 0 root (0) root (0) 315 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/pkgconfig/allegro-5.pc │ │ │ │ -rw-r--r-- 0 root (0) root (0) 378 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/pkgconfig/allegro_color-5.pc │ │ │ │ -rw-r--r-- 0 root (0) root (0) 374 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/pkgconfig/allegro_font-5.pc │ │ │ ├── ./usr/lib/x86_64-linux-gnu/cmake/allegro/AllegroConfig.cmake │ │ │ │ @@ -31,11 +31,11 @@ │ │ │ │ set(ALLEGRO_PKG_VERSION_PATCH 10) │ │ │ │ set(ALLEGRO_PKG_VERSION 5.2.10) │ │ │ │ │ │ │ │ # Architecture, compiler and other low level flags │ │ │ │ set(ALLEGRO_PKG_LIBRARY_ARCHITECTURE "x86_64-linux-gnu") │ │ │ │ set(ALLEGRO_PKG_COMPILER "GNU") │ │ │ │ set(ALLEGRO_PKG_COMPILER_VERSION "14.2.0") │ │ │ │ -set(ALLEGRO_PKG_HOST_SYSTEM "Linux-6.12.12+bpo-amd64") │ │ │ │ +set(ALLEGRO_PKG_HOST_SYSTEM "Linux-6.1.0-31-amd64") │ │ │ │ │ │ │ │ # Targets │ │ │ │ include("${CMAKE_CURRENT_LIST_DIR}/AllegroTargets.cmake")