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

\n

  • .voc file streaming is unimplemented.

    • \n \n

    Return true on success.

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_file.c
      • \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    \n al_is_acodec_addon_initialized\n 
    bool al_is_acodec_addon_initialized(void)
    \n

    Source\n Code

    \n

    Returns true if the acodec addon is initialized, otherwise returns\n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -64,14 +64,18 @@\n * Module files (.it, .mod, .s3m, .xm) are often composed with streaming in\n mind, and sometimes cannot be easily rendered into a finite length\n sample. Therefore they cannot be loaded with _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bs_\ba_\bm_\bp_\bl_\be/\n _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bf and must be streamed with _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm or\n _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf.\n * .voc file streaming is unimplemented.\n Return true on success.\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_a\bac\bco\bod\bde\bec\bc_\b_a\bad\bdd\bdo\bon\bn_\b_i\bin\bni\bit\bti\bia\bal\bli\biz\bze\bed\bd *\b**\b**\b**\b**\b**\b*\n bool al_is_acodec_addon_initialized(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if the acodec addon is initialized, otherwise returns false.\n Since: 5.2.6\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bal\bll\ble\beg\bgr\bro\bo_\b_a\bac\bco\bod\bde\bec\bc_\b_v\bve\ber\brs\bsi\bio\bon\bn *\b**\b**\b**\b**\b**\b*\n uint32_t al_get_allegro_acodec_version(void)\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/audio.html", "source2": "./usr/share/doc/allegro5-doc/refman/audio.html", "unified_diff": "@@ -564,14 +564,19 @@\n Code

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_simple.c
      • \n+
    \n

    al_install_audio

    \n 
    bool al_install_audio(void)
    \n

    Source\n Code

    \n

    Install the audio subsystem.

    \n

    Returns true on success, false on failure.

    \n@@ -582,22 +587,40 @@\n this.

    \n \n

    See also: al_reserve_samples, al_uninstall_audio, al_is_audio_installed, al_init_acodec_addon

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_devices.c
      • \n+
    • ex_saw.c
      • \n+
    • ex_stream_file.c
      • \n+
    \n

    al_uninstall_audio

    \n 
    void al_uninstall_audio(void)
    \n

    Source\n Code

    \n

    Uninstalls the audio subsystem.

    \n

    See also: al_install_audio

    \n+

    Examples:

    \n+
      \n+
    • ex_saw.c
      • \n+
    • ex_stream_file.c
      • \n+
    • ex_acodec_multi.c
      • \n+
    \n

    al_is_audio_installed

    \n 
    bool al_is_audio_installed(void)
    \n

    Source\n Code

    \n

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

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

    \n

    See also: al_set_default_mixer, al_play_sample

    \n+

    Examples:

    \n+
      \n+
    • ex_saw.c
      • \n+
    • ex_audio_props.cpp
      • \n+
    • ex_resample_test.c
      • \n+
    \n

    al_play_sample

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

    Source\n Code

    \n

    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.

    \n+

    Examples:

    \n+
      \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n

    al_stop_sample

    \n 
    void al_stop_sample(ALLEGRO_SAMPLE_ID *spl_id)
    \n

    Source\n Code

    \n

    Stop the sample started by al_play_sample.

    \n

    See also: al_stop_samples

    \n+

    Examples:

    \n+
      \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n

    al_stop_samples

    \n 
    void al_stop_samples(void)
    \n

    Source\n Code

    \n

    Stop all samples started by al_play_sample.

    \n

    See also: al_stop_sample

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_simple.c
      • \n+
    \n

    al_lock_sample_id

    \n 
    ALLEGRO_SAMPLE_INSTANCE* al_lock_sample_id(ALLEGRO_SAMPLE_ID *spl_id)
    \n

    Source\n Code

    \n

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

    \n

    Since: 5.2.3

    \n
    \n

    Unstable\n API: New API.

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_audio_simple.c
      • \n+
    \n

    al_unlock_sample_id

    \n 
    void al_unlock_sample_id(ALLEGRO_SAMPLE_ID *spl_id)
    \n

    Source\n Code

    \n

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

    See also: al_play_sample, al_lock_sample_id

    \n

    Since: 5.2.3

    \n
    \n

    Unstable\n API: New API.

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_audio_simple.c
      • \n+
    \n

    al_play_audio_stream

    \n 
    ALLEGRO_AUDIO_STREAM *al_play_audio_stream(const char *filename)
    \n

    Source\n Code

    \n

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

    \n

    Since: 5.2.8

    \n
    \n

    Unstable\n API: New API.

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_audio_simple.c
      • \n+
    \n

    al_play_audio_stream_f

    \n 
    ALLEGRO_AUDIO_STREAM *al_play_audio_stream_f(ALLEGRO_FILE *fp, const char *ident)
    \n

    Source\n Code

    \n

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

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

    \n

    See also: ALLEGRO_SAMPLE_INSTANCE

    \n+

    Examples:

    \n+
      \n+
    • ex_glext.c
      • \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    \n

    al_create_sample

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

    Source\n Code

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

    See also: al_destroy_sample, ALLEGRO_AUDIO_DEPTH, ALLEGRO_CHANNEL_CONF

    \n+

    Examples:

    \n+
      \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n

    al_load_sample

    \n 
    ALLEGRO_SAMPLE *al_load_sample(const char *filename)
    \n

    Source\n Code

    \n

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

    \n@@ -843,14 +931,23 @@\n

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

    \n \n

    See also: al_register_sample_loader,\n al_init_acodec_addon

    \n+

    Examples:

    \n+
      \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n

    al_load_sample_f

    \n 
    ALLEGRO_SAMPLE *al_load_sample_f(ALLEGRO_FILE* fp, const char *ident)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_destroy_sample_instance,\n al_stop_sample, al_stop_samples

    \n+

    Examples:

    \n+
      \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n

    al_get_sample_channels

    \n 
    ALLEGRO_CHANNEL_CONF al_get_sample_channels(const ALLEGRO_SAMPLE *spl)
    \n

    Source\n Code

    \n

    Return the channel configuration of the sample.

    \n

    See also:

    \n

    Return a pointer to the raw sample data.

    \n

    See also: al_get_sample_channels, al_get_sample_depth, al_get_sample_frequency,\n al_get_sample_length

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_timer.c
      • \n+
    \n

    Advanced Audio

    \n

    For more fine-grained control over audio output, here\u2019s a short\n description of the basic concepts:

    \n

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

    \n

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

    \n

    See also: ALLEGRO_SAMPLE

    \n+

    Examples:

    \n+
      \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n

    al_create_sample_instance

    \n 
    ALLEGRO_SAMPLE_INSTANCE *al_create_sample_instance(ALLEGRO_SAMPLE *sample_data)
    \n

    Source\n Code

    \n

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

    \n

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

    \n

    See also: al_destroy_sample_instance

    \n+

    Examples:

    \n+
      \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n

    al_destroy_sample_instance

    \n 
    void al_destroy_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_create_sample_instance

    \n+

    Examples:

    \n+
      \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n

    al_play_sample_instance

    \n 
    bool al_play_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_stop_sample_instance

    \n+

    Examples:

    \n+
      \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n

    al_stop_sample_instance

    \n 
    bool al_stop_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

    Stop an sample instance playing.

    \n

    See also: al_play_sample_instance

    \n+

    Examples:

    \n+
      \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n al_get_sample_instance_channels\n 
    ALLEGRO_CHANNEL_CONF al_get_sample_instance_channels(\n    const ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

    Return the channel configuration of the sample instance\u2019s sample\n data.

    \n

    See also: ALLEGRO_CHANNEL_CONF.

    \n+

    Examples:

    \n+
      \n+
    • ex_kcm_direct.c
      • \n+
    • ex_acodec.c
      • \n+
    \n

    al_get_sample_instance_depth

    \n 
    ALLEGRO_AUDIO_DEPTH al_get_sample_instance_depth(const ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

    Return the audio depth of the sample instance\u2019s sample data.

    \n

    See also: ALLEGRO_AUDIO_DEPTH.

    \n+

    Examples:

    \n+
      \n+
    • ex_kcm_direct.c
      • \n+
    \n al_get_sample_instance_frequency\n 
    unsigned int al_get_sample_instance_frequency(const ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

    Return the frequency (in Hz) of the sample instance\u2019s sample\n data.

    \n+

    Examples:

    \n+
      \n+
    • ex_kcm_direct.c
      • \n+
    \n al_get_sample_instance_length\n 
    unsigned int al_get_sample_instance_length(const ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

    Return the length of the sample instance in sample values. This\n property may differ from the length of the instance\u2019s sample data.

    \n

    See also: al_set_sample_instance_length,\n al_get_sample_instance_time

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_props.cpp
      • \n+
    • ex_audio_simple.c
      • \n+
    \n al_set_sample_instance_length\n 
    bool al_set_sample_instance_length(ALLEGRO_SAMPLE_INSTANCE *spl,\n    unsigned int val)
    \n

    Source\n Code

    \n

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

    \n

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

    \n

    See also: al_get_sample_instance_length

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_props.cpp
      • \n+
    \n al_get_sample_instance_position\n 
    unsigned int al_get_sample_instance_position(const ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

    Get the playback position of a sample instance.

    \n

    See also: al_set_sample_instance_position

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_chain.cpp
      • \n+
    \n al_set_sample_instance_position\n 
    bool al_set_sample_instance_position(ALLEGRO_SAMPLE_INSTANCE *spl,\n    unsigned int val)
    \n

    Source\n Code

    \n

    Set the playback position of a sample instance.

    \n

    Returns true on success, false on failure.

    \n

    See also: al_get_sample_instance_position

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_simple.c
      • \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_get_sample_instance_speed

    \n 
    float al_get_sample_instance_speed(const ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

    Return the relative playback speed of the sample instance.

    \n

    See also:

    \n

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

    \n

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

    \n

    See also: al_get_sample_instance_speed

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_props.cpp
      • \n+
    • ex_audio_simple.c
      • \n+
    \n

    al_get_sample_instance_gain

    \n 
    float al_get_sample_instance_gain(const ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

    Return the playback gain of the sample instance.

    \n

    See also: al_set_sample_instance_gain

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_set_sample_instance_gain

    \n 
    bool al_set_sample_instance_gain(ALLEGRO_SAMPLE_INSTANCE *spl, float val)
    \n

    Source\n Code

    \n

    Set the playback gain of the sample instance.

    \n

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

    \n

    See also: al_get_sample_instance_gain

    \n+

    Examples:

    \n+
      \n+
    • ex_mixer_chain.c
      • \n+
    • ex_acodec.c
      • \n+
    • ex_audio_props.cpp
      • \n+
    \n

    al_get_sample_instance_pan

    \n 
    float al_get_sample_instance_pan(const ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

    Get the pan value of the sample instance.

    \n

    See also: \n

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

    \n

    See also: al_get_sample_instance_pan,\n ALLEGRO_AUDIO_PAN_NONE

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_props.cpp
      • \n+
    • ex_audio_simple.c
      • \n+
    \n

    al_get_sample_instance_time

    \n 
    float al_get_sample_instance_time(const ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_get_sample_instance_length

    \n+

    Examples:

    \n+
      \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n al_get_sample_instance_playmode\n 
    ALLEGRO_PLAYMODE al_get_sample_instance_playmode(const ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

    Return the playback mode of the sample instance.

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

    \n

    Set the playback mode of the sample instance.

    \n

    Returns true on success, false on failure.

    \n

    See also: ALLEGRO_PLAYMODE,\n al_get_sample_instance_playmode

    \n+

    Examples:

    \n+
      \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    • ex_acodec.c
      • \n+
    \n al_get_sample_instance_playing\n 
    bool al_get_sample_instance_playing(const ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_set_sample_instance_playing

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_chain.cpp
      • \n+
    \n al_set_sample_instance_playing\n 
    bool al_set_sample_instance_playing(ALLEGRO_SAMPLE_INSTANCE *spl, bool val)
    \n

    Source\n Code

    \n

    Change whether the sample instance is playing.

    \n

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

    \n

    Returns true on success, false on failure.

    \n

    See also: al_get_sample_instance_playing

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_props.cpp
      • \n+
    • ex_audio_chain.cpp
      • \n+
    \n al_get_sample_instance_attached\n 
    bool al_get_sample_instance_attached(const ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

    Return whether the sample instance is attached to something.

    \n@@ -1343,14 +1598,19 @@\n

    Returns true on success.

    \n

    See also: al_attach_sample_instance_to_mixer,\n al_attach_sample_instance_to_voice,\n al_get_sample_instance_attached

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_get_sample

    \n 
    ALLEGRO_SAMPLE *al_get_sample(ALLEGRO_SAMPLE_INSTANCE *spl)
    \n

    Source\n Code

    \n

    Return the sample data that the sample instance plays.

    \n

    Note this returns a pointer to an internal structure, not\n@@ -1358,14 +1618,23 @@\n have passed to al_set_sample.\n However, the sample buffer of the returned ALLEGRO_SAMPLE will be the\n 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\n return value to retrieve and compare it.

    \n

    See also: al_set_sample

    \n+

    Examples:

    \n+
      \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n

    al_set_sample

    \n 
    bool al_set_sample(ALLEGRO_SAMPLE_INSTANCE *spl, ALLEGRO_SAMPLE *data)
    \n

    Source\n Code

    \n

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

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

    \n

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

    \n

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

    \n

    See also: al_get_sample

    \n+

    Examples:

    \n+
      \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    • ex_acodec.c
      • \n+
    \n al_set_sample_instance_channel_matrix\n 
    bool al_set_sample_instance_channel_matrix(ALLEGRO_SAMPLE_INSTANCE *spl, const float *matrix)
    \n

    Source\n Code

    \n

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

    Returns true on success, false on failure (e.g.\u00a0if this is not\n attached to a mixer).

    \n

    Since: 5.2.3

    \n
    \n

    Unstable\n API: New API.

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_acodec.c
      • \n+
    \n

    Audio streams

    \n

    ALLEGRO_AUDIO_STREAM

    \n 
    typedef struct ALLEGRO_AUDIO_STREAM ALLEGRO_AUDIO_STREAM;
    \n

    Source\n Code

    \n

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

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

    \n+

    Examples:

    \n+
      \n+
    • ex_saw.c
      • \n+
    • ex_stream_file.c
      • \n+
    • ex_resample_test.c
      • \n+
    \n

    al_create_audio_stream

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

    Source\n Code

    \n@@ -1523,14 +1815,23 @@\n
    \n

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

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_saw.c
      • \n+
    • ex_resample_test.c
      • \n+
    • ex_synth.cpp
      • \n+
    \n

    al_load_audio_stream

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

    Source\n Code

    \n

    Loads an audio file from disk as it is needed.

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

    \n \n

    See also: al_load_audio_stream_f, al_register_audio_stream_loader,\n al_init_acodec_addon

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_file.c
      • \n+
    • ex_mixer_pp.c
      • \n+
    • ex_stream_seek.c
      • \n+
    \n

    al_load_audio_stream_f

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

    Source\n Code

    \n

    Loads an audio file from \n

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

    \n \n

    See also: al_drain_audio_stream.

    \n+

    Examples:

    \n+
      \n+
    • ex_saw.c
      • \n+
    • ex_stream_file.c
      • \n+
    • ex_resample_test.c
      • \n+
    \n al_get_audio_stream_event_source\n 
    ALLEGRO_EVENT_SOURCE *al_get_audio_stream_event_source(\n    ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

    Retrieve the associated event source.

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_saw.c
      • \n+
    • ex_stream_file.c
      • \n+
    • ex_resample_test.c
      • \n+
    \n

    al_drain_audio_stream

    \n 
    void al_drain_audio_stream(ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_destroy_audio_stream

    \n+

    Examples:

    \n+
      \n+
    • ex_saw.c
      • \n+
    • ex_resample_test.c
      • \n+
    • ex_record.c
      • \n+
    \n

    al_rewind_audio_stream

    \n 
    bool al_rewind_audio_stream(ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_seek.c
      • \n+
    \n al_get_audio_stream_frequency\n 
    unsigned int al_get_audio_stream_frequency(const ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

    Return the stream frequency (in Hz).

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

    \n

    al_get_audio_stream_length

    \n 
    unsigned int al_get_audio_stream_length(const ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

    Return the stream length in samples.

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_seek.c
      • \n+
    \n

    al_get_audio_stream_speed

    \n 
    float al_get_audio_stream_speed(const ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

    Return the relative playback speed of the stream.

    \n

    See also: 

    float al_get_audio_stream_gain(const ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

    Return the playback gain of the stream.

    \n

    See also: al_set_audio_stream_gain.

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_set_audio_stream_gain

    \n 
    bool al_set_audio_stream_gain(ALLEGRO_AUDIO_STREAM *stream, float val)
    \n

    Source\n Code

    \n

    Set the playback gain of the stream.

    \n

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

    \n

    See also: al_get_audio_stream_gain.

    \n+

    Examples:

    \n+
      \n+
    • ex_synth.cpp
      • \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_get_audio_stream_pan

    \n 
    float al_get_audio_stream_pan(const ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

    Get the pan value of the stream.

    \n

    See also: \n

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

    \n

    See also: al_get_audio_stream_pan,\n ALLEGRO_AUDIO_PAN_NONE

    \n+

    Examples:

    \n+
      \n+
    • ex_synth.cpp
      • \n+
    \n

    al_get_audio_stream_playing

    \n 
    bool al_get_audio_stream_playing(const ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

    Return true if the stream is playing.

    \n

    See also: al_set_audio_stream_playing.

    \n+

    Examples:

    \n+
      \n+
    • ex_record.c
      • \n+
    • ex_stream_seek.c
      • \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_set_audio_stream_playing

    \n 
    bool al_set_audio_stream_playing(ALLEGRO_AUDIO_STREAM *stream, bool val)
    \n

    Source\n Code

    \n

    Change whether the stream is playing.

    \n

    Returns true on success, false on failure.

    \n

    See also: al_get_audio_stream_playing

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_simple.c
      • \n+
    • ex_record.c
      • \n+
    • ex_stream_seek.c
      • \n+
    \n

    al_get_audio_stream_playmode

    \n 
    ALLEGRO_PLAYMODE al_get_audio_stream_playmode(\n    const ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

    Return the playback mode of the stream.

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

    \n

    Set the playback mode of the stream.

    \n

    Returns true on success, false on failure.

    \n

    See also: ALLEGRO_PLAYMODE,\n al_get_audio_stream_playmode.

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_file.c
      • \n+
    • ex_mixer_pp.c
      • \n+
    • ex_stream_seek.c
      • \n+
    \n

    al_get_audio_stream_attached

    \n 
    bool al_get_audio_stream_attached(const ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

    Return whether the stream is attached to something.

    \n

    See also: Detach the stream from whatever it\u2019s attached to, if anything.

    \n

    See also: al_attach_audio_stream_to_mixer,\n al_attach_audio_stream_to_voice,\n al_get_audio_stream_attached.

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_chain.cpp
      • \n+
    \n al_get_audio_stream_played_samples\n 
    uint64_t al_get_audio_stream_played_samples(const ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_saw.c
      • \n+
    • ex_resample_test.c
      • \n+
    • ex_synth.cpp
      • \n+
    \n

    al_set_audio_stream_fragment

    \n 
    bool al_set_audio_stream_fragment(ALLEGRO_AUDIO_STREAM *stream, void *val)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_get_audio_stream_fragment

    \n+

    Examples:

    \n+
      \n+
    • ex_saw.c
      • \n+
    • ex_resample_test.c
      • \n+
    • ex_synth.cpp
      • \n+
    \n al_get_audio_stream_fragments\n 
    unsigned int al_get_audio_stream_fragments(const ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_get_audio_stream_position_secs,\n al_get_audio_stream_length_secs

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_seek.c
      • \n+
    \n al_get_audio_stream_position_secs\n 
    double al_get_audio_stream_position_secs(ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_get_audio_stream_length_secs

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_seek.c
      • \n+
    \n al_get_audio_stream_length_secs\n 
    double al_get_audio_stream_length_secs(ALLEGRO_AUDIO_STREAM *stream)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_get_audio_stream_position_secs

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_seek.c
      • \n+
    \n al_set_audio_stream_loop_secs\n 
    bool al_set_audio_stream_loop_secs(ALLEGRO_AUDIO_STREAM *stream,\n    double start, double end)
    \n

    Source\n Code

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_seek.c
      • \n+
    \n al_set_audio_stream_channel_matrix\n

    Source Code

    \n

    Like al_set_sample_instance_channel_matrix\n but for streams.

    \n

    Since: 5.2.3

    \n@@ -2145,14 +2579,21 @@\n Code

    \n

    An opaque datatype that represents a recording device.

    \n

    Since: 5.1.1

    \n
    \n

    Unstable\n API: The API may need a slight redesign.

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_record_name.c
      • \n+
    • ex_record.c
      • \n+
    \n

    ALLEGRO_AUDIO_RECORDER_EVENT

    \n
    typedef struct ALLEGRO_AUDIO_RECORDER_EVENT ALLEGRO_AUDIO_RECORDER_EVENT;
    \n

    Source\n Code

    \n

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

    Since 5.1.1

    \n

    See also: al_get_audio_recorder_event

    \n
    \n

    Unstable\n API: The API may need a slight redesign.

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_record_name.c
      • \n+
    • ex_record.c
      • \n+
    \n

    al_create_audio_recorder

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

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

    \n

    On failure, returns NULL.

    \n

    Since: 5.1.1

    \n
    \n

    Unstable\n API: The API may need a slight redesign.

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_record_name.c
      • \n+
    • ex_record.c
      • \n+
    \n

    al_start_audio_recorder

    \n
    bool al_start_audio_recorder(ALLEGRO_AUDIO_RECORDER *r)
    \n

    Source\n Code

    \n

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

    \n

    Returns true if it was able to begin recording.

    \n

    Since: 5.1.1

    \n
    \n

    Unstable\n API: The API may need a slight redesign.

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_record_name.c
      • \n+
    • ex_record.c
      • \n+
    \n

    al_stop_audio_recorder

    \n
    void al_stop_audio_recorder(ALLEGRO_AUDIO_RECORDER *r)
    \n

    Source\n Code

    \n

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

    Returns the event as an ALLEGRO_AUDIO_RECORDER_EVENT.

    \n

    Since: 5.1.1

    \n
    \n

    Unstable\n API: The API may need a slight redesign.

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_record_name.c
      • \n+
    • ex_record.c
      • \n+
    \n al_get_audio_recorder_event_source\n
    ALLEGRO_EVENT_SOURCE *al_get_audio_recorder_event_source(ALLEGRO_AUDIO_RECORDER *r)
    \n

    Source\n Code

    \n

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

    \n

    Since: 5.1.1

    \n
    \n

    Unstable\n API: The API may need a slight redesign.

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_record_name.c
      • \n+
    • ex_record.c
      • \n+
    \n

    al_destroy_audio_recorder

    \n
    void al_destroy_audio_recorder(ALLEGRO_AUDIO_RECORDER *r)
    \n

    Source\n Code

    \n

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

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

    \n

    Since: 5.1.1

    \n
    \n

    Unstable\n API: The API may need a slight redesign.

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_record_name.c
      • \n+
    • ex_record.c
      • \n+
    \n

    Audio devices

    \n

    ALLEGRO_AUDIO_DEVICE

    \n
    typedef struct ALLEGRO_AUDIO_DEVICE ALLEGRO_AUDIO_DEVICE;
    \n

    Source\n Code

    \n

    An opaque datatype that represents an audio device.

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_devices.c
      • \n+
    \n al_get_num_audio_output_devices\n
    int al_get_num_audio_output_devices()
    \n

    Source\n Code

    \n

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

    \n

    Since: 5.2.8

    \n

    return -1 for unsupported drivers.

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_devices.c
      • \n+
    \n

    al_get_audio_output_device

    \n
    const ALLEGRO_AUDIO_DEVICE* al_get_audio_output_device(int index)
    \n

    Source\n Code

    \n

    Get the output audio device of the specified index.

    \n

    Since: 5.2.8

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_devices.c
      • \n+
    \n

    al_get_audio_device_name

    \n
    const char* al_get_audio_device_name(const ALLEGRO_AUDIO_DEVICE * device)
    \n

    Source\n Code

    \n

    Get the user friendly display name of the device.

    \n

    Since: 5.2.8

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_devices.c
      • \n+
    \n

    Voices

    \n

    ALLEGRO_VOICE

    \n
    typedef struct ALLEGRO_VOICE ALLEGRO_VOICE;
    \n

    Source\n Code

    \n

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

    \n

    See also: ALLEGRO_MIXER, ALLEGRO_SAMPLE, ALLEGRO_AUDIO_STREAM

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_file.c
      • \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    \n

    al_create_voice

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

    Source\n Code

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

    \n

    Reasonable default arguments are:

    \n
    al_create_voice(44100, ALLEGRO_AUDIO_DEPTH_INT16, ALLEGRO_CHANNEL_CONF_2)
    \n

    See also: al_destroy_voice

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_file.c
      • \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    \n

    al_destroy_voice

    \n
    void al_destroy_voice(ALLEGRO_VOICE *voice)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_create_voice

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_file.c
      • \n+
    • ex_acodec_multi.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    \n

    al_detach_voice

    \n
    void al_detach_voice(ALLEGRO_VOICE *voice)
    \n

    Source\n Code

    \n

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

    \n

    Returns true on success, false on failure.

    \n

    See also: al_detach_voice,\n al_voice_has_attachments

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_file.c
      • \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_attach_mixer_to_voice

    \n
    bool al_attach_mixer_to_voice(ALLEGRO_MIXER *mixer, ALLEGRO_VOICE *voice)
    \n

    Source\n Code

    \n

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

    \n

    Returns true on success, false on failure.

    \n

    See also: al_detach_voice,\n al_voice_has_attachments

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_file.c
      • \n+
    • ex_acodec_multi.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n al_attach_sample_instance_to_voice\n
    bool al_attach_sample_instance_to_voice(ALLEGRO_SAMPLE_INSTANCE *spl,\n ALLEGRO_VOICE *voice)
    \n

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

    \n

    At this time, we don\u2019t recommend attaching sample instances directly\n to voices. Use a mixer inbetween.

    \n

    Returns true on success, false on failure.

    \n

    See also: al_detach_voice,\n al_voice_has_attachments

    \n+

    Examples:

    \n+
      \n+
    • ex_kcm_direct.c
      • \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_get_voice_frequency

    \n
    unsigned int al_get_voice_frequency(const ALLEGRO_VOICE *voice)
    \n

    Source\n Code

    \n

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

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

    Source\n Code

    \n

    Return true if the voice is currently playing.

    \n

    See also: al_set_voice_playing

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_set_voice_playing

    \n
    bool al_set_voice_playing(ALLEGRO_VOICE *voice, bool val)
    \n

    Source\n Code

    \n

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

    \n

    Returns true on success, false on failure.

    \n

    See also: al_get_voice_playing

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_get_voice_position

    \n
    unsigned int al_get_voice_position(const ALLEGRO_VOICE *voice)
    \n

    Source\n Code

    \n

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

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_stream_file.c
      • \n+
    • ex_acodec_multi.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n

    ALLEGRO_MIXER_QUALITY

    \n
    enum ALLEGRO_MIXER_QUALITY
    \n

    Source\n Code

    \n
      \n@@ -2581,23 +3153,41 @@\n

      Reasonable default arguments are:

      \n
      al_create_mixer(44100, ALLEGRO_AUDIO_DEPTH_FLOAT32, ALLEGRO_CHANNEL_CONF_2)
      \n

      Returns true on success, false on error.

      \n

      See also: al_destroy_mixer,\n ALLEGRO_AUDIO_DEPTH, ALLEGRO_CHANNEL_CONF

      \n+

      Examples:

      \n+
        \n+
      • ex_stream_file.c
        • \n+
      • ex_acodec_multi.c
        • \n+
      • ex_mixer_chain.c
        • \n+
      \n

      al_destroy_mixer

      \n
      void al_destroy_mixer(ALLEGRO_MIXER *mixer)
      \n

      Source\n Code

      \n

      Destroys the mixer.

      \n

      See also: al_create_mixer

      \n+

      Examples:

      \n+
        \n+
      • ex_stream_file.c
        • \n+
      • ex_acodec_multi.c
        • \n+
      • ex_mixer_chain.c
        • \n+
      \n

      al_get_default_mixer

      \n
      ALLEGRO_MIXER *al_get_default_mixer(void)
      \n

      Source\n Code

      \n

      Return the default mixer, or NULL if one has not been set. Although\n@@ -2605,14 +3195,23 @@\n a single mixer attached to a voice is what you want. The default mixer\n is used by al_play_sample.

      \n

      See also: al_reserve_samples, al_play_sample, al_set_default_mixer, al_restore_default_mixer

      \n+

      Examples:

      \n+
        \n+
      • ex_saw.c
        • \n+
      • ex_audio_props.cpp
        • \n+
      • ex_resample_test.c
        • \n+
      \n

      al_set_default_mixer

      \n
      bool al_set_default_mixer(ALLEGRO_MIXER *mixer)
      \n

      Source\n Code

      \n

      Sets the default mixer. All samples started with \n

      Returns true on success, false on error.

      \n

      It is invalid to attach a mixer to itself.

      \n

      See also: al_detach_mixer.

      \n+

      Examples:

      \n+
        \n+
      • ex_mixer_chain.c
        • \n+
      • ex_audio_chain.cpp
        • \n+
      \n al_attach_sample_instance_to_mixer\n
      bool al_attach_sample_instance_to_mixer(ALLEGRO_SAMPLE_INSTANCE *spl,\n ALLEGRO_MIXER *mixer)
      \n

      Source\n Code

      \n

      Attach a sample instance to a mixer. The instance must not already be\n attached to anything.

      \n

      Returns true on success, false on failure.

      \n

      See also: al_detach_sample_instance.

      \n+

      Examples:

      \n+
        \n+
      • ex_acodec_multi.c
        • \n+
      • ex_mixer_chain.c
        • \n+
      • ex_acodec.c
        • \n+
      \n al_attach_audio_stream_to_mixer\n
      bool al_attach_audio_stream_to_mixer(ALLEGRO_AUDIO_STREAM *stream, ALLEGRO_MIXER *mixer)
      \n

      Source\n Code

      \n

      Attach an audio stream to a mixer. The stream must not already be\n attached to anything.

      \n

      Returns true on success, false on failure.

      \n

      See also: al_detach_audio_stream.

      \n+

      Examples:

      \n+
        \n+
      • ex_saw.c
        • \n+
      • ex_stream_file.c
        • \n+
      • ex_resample_test.c
        • \n+
      \n

      al_get_mixer_frequency

      \n
      unsigned int al_get_mixer_frequency(const ALLEGRO_MIXER *mixer)
      \n

      Source\n Code

      \n

      Return the mixer frequency (in Hz).

      \n@@ -2734,44 +3358,66 @@\n class=\"sourceCode c\">ALLEGRO_CHANNEL_CONF al_get_mixer_channels(const ALLEGRO_MIXER *mixer)\n

      Source\n Code

      \n

      Return the mixer channel configuration.

      \n

      See also: ALLEGRO_CHANNEL_CONF.

      \n+

      Examples:

      \n+
        \n+
      • ex_synth.cpp
        • \n+
      \n

      al_get_mixer_depth

      \n
      ALLEGRO_AUDIO_DEPTH al_get_mixer_depth(const ALLEGRO_MIXER *mixer)
      \n

      Source\n Code

      \n

      Return the mixer audio depth.

      \n

      See also: ALLEGRO_AUDIO_DEPTH.

      \n+

      Examples:

      \n+
        \n+
      • ex_synth.cpp
        • \n+
      \n

      al_get_mixer_gain

      \n
      float al_get_mixer_gain(const ALLEGRO_MIXER *mixer)
      \n

      Source\n Code

      \n

      Return the mixer gain (amplification factor). The default is 1.0.

      \n

      Since: 5.0.6, 5.1.0

      \n

      See also: al_set_mixer_gain.

      \n+

      Examples:

      \n+
        \n+
      • ex_audio_chain.cpp
        • \n+
      \n

      al_set_mixer_gain

      \n
      bool al_set_mixer_gain(ALLEGRO_MIXER *mixer, float new_gain)
      \n

      Source\n Code

      \n

      Set the mixer gain (amplification factor).

      \n

      Returns true on success, false on failure.

      \n

      Since: 5.0.6, 5.1.0

      \n

      See also: al_get_mixer_gain

      \n+

      Examples:

      \n+
        \n+
      • ex_audio_props.cpp
        • \n+
      • ex_audio_chain.cpp
        • \n+
      \n

      al_get_mixer_quality

      \n
      ALLEGRO_MIXER_QUALITY al_get_mixer_quality(const ALLEGRO_MIXER *mixer)
      \n

      Source\n Code

      \n

      Return the mixer quality.

      \n@@ -2795,24 +3441,34 @@\n class=\"sourceCode c\">bool al_get_mixer_playing(const ALLEGRO_MIXER *mixer)\n

      Source\n Code

      \n

      Return true if the mixer is playing.

      \n

      See also: al_set_mixer_playing.

      \n+

      Examples:

      \n+
        \n+
      • ex_audio_chain.cpp
        • \n+
      \n

      al_set_mixer_playing

      \n
      bool al_set_mixer_playing(ALLEGRO_MIXER *mixer, bool val)
      \n

      Source\n Code

      \n

      Change whether the mixer is playing.

      \n

      Returns true on success, false on failure.

      \n

      See also: al_get_mixer_playing.

      \n+

      Examples:

      \n+
        \n+
      • ex_audio_chain.cpp
        • \n+
      \n

      al_get_mixer_attached

      \n
      bool al_get_mixer_attached(const ALLEGRO_MIXER *mixer)
      \n

      Source\n Code

      \n

      Return true if the mixer is attached to something.

      \n@@ -2846,14 +3502,19 @@\n class=\"sourceCode c\">bool al_detach_mixer(ALLEGRO_MIXER *mixer)\n

      Source\n Code

      \n

      Detach the mixer from whatever it is attached to, if anything.

      \n

      See also: al_attach_mixer_to_mixer.

      \n+

      Examples:

      \n+
        \n+
      • ex_audio_chain.cpp
        • \n+
      \n al_set_mixer_postprocess_callback\n
      bool al_set_mixer_postprocess_callback(ALLEGRO_MIXER *mixer,\n void (*pp_callback)(void *buf, unsigned int samples, void *data),\n void *pp_callback_userdata)
      \n

      \n

      \n

      Note: The callback is called from a dedicated audio\n thread.

      \n
      \n+

      Examples:

      \n+
        \n+
      • ex_resample_test.c
        • \n+
      • ex_synth.cpp
        • \n+
      • ex_mixer_pp.c
        • \n+
      \n

      Miscelaneous

      \n

      ALLEGRO_AUDIO_DEPTH

      \n
      enum ALLEGRO_AUDIO_DEPTH
      \n

      Source\n Code

      \n@@ -2886,14 +3556,23 @@\n
    \n

    For convenience:

    \n
      \n
    • ALLEGRO_AUDIO_DEPTH_UINT8
      • \n
    • ALLEGRO_AUDIO_DEPTH_UINT16
      • \n
    • ALLEGRO_AUDIO_DEPTH_UINT24
      • \n
    \n+

    Examples:

    \n+
      \n+
    • ex_saw.c
      • \n+
    • ex_stream_file.c
      • \n+
    • ex_acodec_multi.c
      • \n+
    \n

    ALLEGRO_AUDIO_PAN_NONE

    \n
    #define ALLEGRO_AUDIO_PAN_NONE (-1000.0f)
    \n

    Source\n Code

    \n

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

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

    \n

    (Please correct us if this is wrong.)

    \n+

    Examples:

    \n+
      \n+
    • ex_audio_props.cpp
      • \n+
    \n

    ALLEGRO_CHANNEL_CONF

    \n
    enum ALLEGRO_CHANNEL_CONF
    \n

    Source\n Code

    \n

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

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

    Examples:

    \n+
      \n+
    • ex_saw.c
      • \n+
    • ex_stream_file.c
      • \n+
    • ex_acodec_multi.c
      • \n+
    \n

    ALLEGRO_PLAYMODE

    \n
    enum ALLEGRO_PLAYMODE
    \n

    Source\n Code

    \n

    Sample and stream playback mode.

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

    Examples:

    \n+
      \n+
    • ex_stream_file.c
      • \n+
    • ex_kcm_direct.c
      • \n+
    • ex_mixer_chain.c
      • \n+
    \n

    ALLEGRO_AUDIO_EVENT_TYPE

    \n
    enum ALLEGRO_AUDIO_EVENT_TYPE
    \n

    Source\n Code

    \n

    Events sent by size_t al_get_audio_depth_size(ALLEGRO_AUDIO_DEPTH depth)\n

    Source\n Code

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_synth.cpp
      • \n+
    \n

    al_get_channel_count

    \n
    size_t al_get_channel_count(ALLEGRO_CHANNEL_CONF conf)
    \n

    Source\n Code

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_acodec.c
      • \n+
    \n

    al_fill_silence

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

    Source\n Code

    \n

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

    \n

    Since: 5.1.8

    \n+

    Examples:

    \n+
      \n+
    • ex_saw.c
      • \n+
    • ex_synth.cpp
      • \n+
    \n

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

    \n \n \n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -232,28 +232,38 @@\n the basic API only supports one such audio stream playing at once.\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_S\bSA\bAM\bMP\bPL\bLE\bE_\b_I\bID\bD *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_SAMPLE_ID ALLEGRO_SAMPLE_ID;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An ALLEGRO_SAMPLE_ID represents a sample being played via _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\bs_\ba_\bm_\bp_\bl_\be. It\n can be used to later stop the sample with _\ba_\bl_\b__\bs_\bt_\bo_\bp_\b__\bs_\ba_\bm_\bp_\bl_\be. The underlying\n ALLEGRO_SAMPLE_INSTANCE can be extracted using _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bd.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bi_\bm_\bp_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bns\bst\bta\bal\bll\bl_\b_a\bau\bud\bdi\bio\bo *\b**\b**\b**\b**\b*\n bool al_install_audio(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Install the audio subsystem.\n Returns true on success, false on failure.\n Note: most users will call _\ba_\bl_\b__\br_\be_\bs_\be_\br_\bv_\be_\b__\bs_\ba_\bm_\bp_\bl_\be_\bs and\n _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\ba_\bd_\bd_\bo_\bn after this.\n See also: _\ba_\bl_\b__\br_\be_\bs_\be_\br_\bv_\be_\b__\bs_\ba_\bm_\bp_\bl_\be_\bs, _\ba_\bl_\b__\bu_\bn_\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\ba_\bu_\bd_\bi_\bo, _\ba_\bl_\b__\bi_\bs_\b__\ba_\bu_\bd_\bi_\bo_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\be_\bd,\n _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\ba_\bd_\bd_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bd_\be_\bv_\bi_\bc_\be_\bs_\b._\bc\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bni\bin\bns\bst\bta\bal\bll\bl_\b_a\bau\bud\bdi\bio\bo *\b**\b**\b**\b**\b*\n void al_uninstall_audio(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Uninstalls the audio subsystem.\n See also: _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\ba_\bu_\bd_\bi_\bo\n+Examples:\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_a\bau\bud\bdi\bio\bo_\b_i\bin\bns\bst\bta\bal\bll\ble\bed\bd *\b**\b**\b**\b**\b*\n bool al_is_audio_installed(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\ba_\bu_\bd_\bi_\bo was called previously and returned\n successfully.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bes\bse\ber\brv\bve\be_\b_s\bsa\bam\bmp\bpl\ble\bes\bs *\b**\b**\b**\b**\b*\n bool al_reserve_samples(int reserve_samples)\n@@ -270,14 +280,18 @@\n / sample instance 2\n default voice <-- default mixer <--- .\n \\ .\n sample instance N\n Returns true on success, false on error. _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\ba_\bu_\bd_\bi_\bo must have been called\n first.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bd_\be_\bf_\ba_\bu_\bl_\bt_\b__\bm_\bi_\bx_\be_\br, _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\bs_\ba_\bm_\bp_\bl_\be\n+Examples:\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bp_\br_\bo_\bp_\bs_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\br_\be_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_p\bpl\bla\bay\by_\b_s\bsa\bam\bmp\bpl\ble\be *\b**\b**\b**\b**\b*\n bool al_play_sample(ALLEGRO_SAMPLE *spl, float gain, float pan, float speed,\n ALLEGRO_PLAYMODE loop, ALLEGRO_SAMPLE_ID *ret_id)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Plays a sample on one of the sample instances created by _\ba_\bl_\b__\br_\be_\bs_\be_\br_\bv_\be_\b__\bs_\ba_\bm_\bp_\bl_\be_\bs.\n Returns true on success, false on failure. Playback may fail because all the\n reserved sample instances are currently used.\n@@ -290,24 +304,34 @@\n ALLEGRO_PLAYMODE_BIDIR\n * ret_id - if non-NULL the variable which this points to will be assigned\n an id representing the sample being played. If _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\bs_\ba_\bm_\bp_\bl_\be returns\n false, then the contents of ret_id are invalid and must not be used as\n argument to other functions.\n See also: _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bs_\ba_\bm_\bp_\bl_\be, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bL_\bA_\bY_\bM_\bO_\bD_\bE, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bP_\bA_\bN_\b__\bN_\bO_\bN_\bE,\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bA_\bM_\bP_\bL_\bE_\b__\bI_\bD, _\ba_\bl_\b__\bs_\bt_\bo_\bp_\b__\bs_\ba_\bm_\bp_\bl_\be, _\ba_\bl_\b__\bs_\bt_\bo_\bp_\b__\bs_\ba_\bm_\bp_\bl_\be_\bs, _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bd.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bst\bto\bop\bp_\b_s\bsa\bam\bmp\bpl\ble\be *\b**\b**\b**\b**\b*\n void al_stop_sample(ALLEGRO_SAMPLE_ID *spl_id)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Stop the sample started by _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\bs_\ba_\bm_\bp_\bl_\be.\n See also: _\ba_\bl_\b__\bs_\bt_\bo_\bp_\b__\bs_\ba_\bm_\bp_\bl_\be_\bs\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bst\bto\bop\bp_\b_s\bsa\bam\bmp\bpl\ble\bes\bs *\b**\b**\b**\b**\b*\n void al_stop_samples(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Stop all samples started by _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\bs_\ba_\bm_\bp_\bl_\be.\n See also: _\ba_\bl_\b__\bs_\bt_\bo_\bp_\b__\bs_\ba_\bm_\bp_\bl_\be\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bi_\bm_\bp_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boc\bck\bk_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bid\bd *\b**\b**\b**\b**\b*\n ALLEGRO_SAMPLE_INSTANCE* al_lock_sample_id(ALLEGRO_SAMPLE_ID *spl_id)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Locks a _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bA_\bM_\bP_\bL_\bE_\b__\bI_\bD, returning the underlying _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bA_\bM_\bP_\bL_\bE_\b__\bI_\bN_\bS_\bT_\bA_\bN_\bC_\bE.\n This allows you to adjust the various properties of the instance (such as\n volume, pan, etc) while the sound is playing.\n This function will return NULL if the sound corresponding to the id is no\n@@ -315,24 +339,28 @@\n While locked, ALLEGRO_SAMPLE_ID will be unavailable to additional calls to\n _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\bs_\ba_\bm_\bp_\bl_\be, even if the sound stops while locked. To put the\n ALLEGRO_SAMPLE_ID back into the pool for reuse, make sure to call\n al_unlock_sample_id when you\u2019re done with the instance.\n See also: _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\bs_\ba_\bm_\bp_\bl_\be, _\ba_\bl_\b__\bu_\bn_\bl_\bo_\bc_\bk_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bd\n Since: 5.2.3\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: New API.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bi_\bm_\bp_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bnl\blo\boc\bck\bk_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bid\bd *\b**\b**\b**\b**\b*\n void al_unlock_sample_id(ALLEGRO_SAMPLE_ID *spl_id)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Unlocks a _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bA_\bM_\bP_\bL_\bE_\b__\bI_\bD, allowing future calls to _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\bs_\ba_\bm_\bp_\bl_\be to reuse\n it if possible. Note that after the id is unlocked, the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bA_\bM_\bP_\bL_\bE_\b__\bI_\bN_\bS_\bT_\bA_\bN_\bC_\bE\n that was previously returned by _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bd will possibly be playing a\n different sound, so you should only use it after locking the id again.\n See also: _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\bs_\ba_\bm_\bp_\bl_\be, _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bd\n Since: 5.2.3\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: New API.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bi_\bm_\bp_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_p\bpl\bla\bay\by_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm *\b**\b**\b**\b**\b*\n ALLEGRO_AUDIO_STREAM *al_play_audio_stream(const char *filename)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Loads and plays an audio file, streaming from disk as it is needed. This API\n can only play one audio stream at a time. This requires a default mixer to be\n set, which is typically done via _\ba_\bl_\b__\br_\be_\bs_\be_\br_\bv_\be_\b__\bs_\ba_\bm_\bp_\bl_\be_\bs, but can also be done via\n _\ba_\bl_\b__\bs_\be_\bt_\b__\bd_\be_\bf_\ba_\bu_\bl_\bt_\b__\bm_\bi_\bx_\be_\br.\n@@ -341,14 +369,16 @@\n down.\n N\bNo\bot\bte\be:\b: the allegro_audio library does not support any audio file\n formats by default. You must use the allegro_acodec addon, or\n register your own format handler.\n See also: _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf, _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm\n Since: 5.2.8\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: New API.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bi_\bm_\bp_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_p\bpl\bla\bay\by_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_f\bf *\b**\b**\b**\b**\b*\n ALLEGRO_AUDIO_STREAM *al_play_audio_stream_f(ALLEGRO_FILE *fp, const char\n *ident)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Loads and plays an audio file from _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bF_\bI_\bL_\bE stream, streaming it is needed.\n This API can only play one audio stream at a time. This requires a default\n mixer to be set, which is typically done via _\ba_\bl_\b__\br_\be_\bs_\be_\br_\bv_\be_\b__\bs_\ba_\bm_\bp_\bl_\be_\bs, but can also\n@@ -371,14 +401,18 @@\n typedef struct ALLEGRO_SAMPLE ALLEGRO_SAMPLE;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An ALLEGRO_SAMPLE object stores the data necessary for playing pre-defined\n digital audio. It holds a user-specified PCM data buffer and information about\n its format (data length, depth, frequency, channel configuration). You can have\n the same ALLEGRO_SAMPLE playing multiple times simultaneously.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bA_\bM_\bP_\bL_\bE_\b__\bI_\bN_\bS_\bT_\bA_\bN_\bC_\bE\n+Examples:\n+ * _\be_\bx_\b__\bg_\bl_\be_\bx_\bt_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_s\bsa\bam\bmp\bpl\ble\be *\b**\b**\b**\b**\b*\n ALLEGRO_SAMPLE *al_create_sample(void *buf, unsigned int samples,\n unsigned int freq, ALLEGRO_AUDIO_DEPTH depth,\n ALLEGRO_CHANNEL_CONF chan_conf, bool free_buf)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a sample data structure from the supplied buffer. If free_buf is true\n then the buffer will be freed with _\ba_\bl_\b__\bf_\br_\be_\be when the sample data structure is\n@@ -392,26 +426,34 @@\n A single sample, then, refers to the LR pair in this example.\n To allocate a buffer of the correct size, you can use something like this:\n int sample_size = al_get_channel_count(chan_conf)\n * al_get_audio_depth_size(depth);\n int bytes = samples * sample_size;\n void *buffer = al_malloc(bytes);\n See also: _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bs_\ba_\bm_\bp_\bl_\be, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bD_\bE_\bP_\bT_\bH, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bH_\bA_\bN_\bN_\bE_\bL_\b__\bC_\bO_\bN_\bF\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boa\bad\bd_\b_s\bsa\bam\bmp\bpl\ble\be *\b**\b**\b**\b**\b*\n ALLEGRO_SAMPLE *al_load_sample(const char *filename)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Loads a few different audio file formats based on their extension.\n Note that this stores the entire file in memory at once, which may be time\n consuming. To read the file as it is needed, use _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm or\n _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm.\n Returns the sample on success, NULL on failure.\n N\bNo\bot\bte\be:\b: the allegro_audio library does not support any audio file\n formats by default. You must use the allegro_acodec addon, or\n register your own format handler.\n See also: _\ba_\bl_\b__\br_\be_\bg_\bi_\bs_\bt_\be_\br_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bl_\bo_\ba_\bd_\be_\br, _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\ba_\bd_\bd_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boa\bad\bd_\b_s\bsa\bam\bmp\bpl\ble\be_\b_f\bf *\b**\b**\b**\b**\b*\n ALLEGRO_SAMPLE *al_load_sample_f(ALLEGRO_FILE* fp, const char *ident)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Loads an audio file from an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bF_\bI_\bL_\bE stream into an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bA_\bM_\bP_\bL_\bE. The\n file type is determined by the passed \u2018ident\u2019 parameter, which is a file name\n extension including the leading dot.\n Note that this stores the entire file in memory at once, which may be time\n@@ -447,14 +489,18 @@\n void al_destroy_sample(ALLEGRO_SAMPLE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Free the sample data structure. If it was created with the free_buf parameter\n set to true, then the buffer will be freed with _\ba_\bl_\b__\bf_\br_\be_\be.\n This function will stop any sample instances which may be playing the buffer\n referenced by the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bA_\bM_\bP_\bL_\bE.\n See also: _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be, _\ba_\bl_\b__\bs_\bt_\bo_\bp_\b__\bs_\ba_\bm_\bp_\bl_\be, _\ba_\bl_\b__\bs_\bt_\bo_\bp_\b__\bs_\ba_\bm_\bp_\bl_\be_\bs\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_c\bch\bha\ban\bnn\bne\bel\bls\bs *\b**\b**\b**\b**\b*\n ALLEGRO_CHANNEL_CONF al_get_sample_channels(const ALLEGRO_SAMPLE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the channel configuration of the sample.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bH_\bA_\bN_\bN_\bE_\bL_\b__\bC_\bO_\bN_\bF, _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bd_\be_\bp_\bt_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bf_\br_\be_\bq_\bu_\be_\bn_\bc_\by,\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bl_\be_\bn_\bg_\bt_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bd_\ba_\bt_\ba\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_d\bde\bep\bpt\bth\bh *\b**\b**\b**\b**\b*\n@@ -477,14 +523,16 @@\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bd_\ba_\bt_\ba\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_d\bda\bat\bta\ba *\b**\b**\b**\b**\b*\n void *al_get_sample_data(const ALLEGRO_SAMPLE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return a pointer to the raw sample data.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bc_\bh_\ba_\bn_\bn_\be_\bl_\bs, _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bd_\be_\bp_\bt_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bf_\br_\be_\bq_\bu_\be_\bn_\bc_\by,\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bl_\be_\bn_\bg_\bt_\bh\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bt_\bi_\bm_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAd\bdv\bva\ban\bnc\bce\bed\bd A\bAu\bud\bdi\bio\bo *\b**\b**\b**\b**\b**\b*\n For more fine-grained control over audio output, here\u2019s a short description of\n the basic concepts:\n Voices represent audio devices on the system. Basically, every audio output\n chain that you want to be heard needs to end up in a voice. As voices are on\n the hardware/driver side of things, there is only limited control over their\n parameters (frequency, sample format, channel configuration). The number of\n@@ -564,108 +612,154 @@\n instance is currently playing or paused is also one of its properties.\n An instance uses the data from an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bA_\bM_\bP_\bL_\bE object. Multiple instances may\n be created from the same ALLEGRO_SAMPLE. An ALLEGRO_SAMPLE must not be\n destroyed while there are instances which reference it.\n To actually produce audio output, an ALLEGRO_SAMPLE_INSTANCE must be attached\n to an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bM_\bI_\bX_\bE_\bR which eventually reaches an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bO_\bI_\bC_\bE object.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bA_\bM_\bP_\bL_\bE\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be *\b**\b**\b**\b**\b*\n ALLEGRO_SAMPLE_INSTANCE *al_create_sample_instance(ALLEGRO_SAMPLE *sample_data)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Creates a sample instance, using the supplied sample data. The instance must be\n attached to a mixer (or voice) in order to actually produce output.\n The argument may be NULL. You can then set the sample data later with\n _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be.\n See also: _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be *\b**\b**\b**\b**\b*\n void al_destroy_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Detaches the sample instance from anything it may be attached to and frees it\n (the sample data, i.e.\u00a0its ALLEGRO_SAMPLE, is n\bno\bot\bt freed!).\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_p\bpl\bla\bay\by_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be *\b**\b**\b**\b**\b*\n bool al_play_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Play the sample instance. Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bs_\bt_\bo_\bp_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bst\bto\bop\bp_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be *\b**\b**\b**\b**\b*\n bool al_stop_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Stop an sample instance playing.\n See also: _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_c\bch\bha\ban\bnn\bne\bel\bls\bs *\b**\b**\b**\b**\b*\n ALLEGRO_CHANNEL_CONF al_get_sample_instance_channels(\n const ALLEGRO_SAMPLE_INSTANCE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the channel configuration of the sample instance\u2019s sample data.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bH_\bA_\bN_\bN_\bE_\bL_\b__\bC_\bO_\bN_\bF.\n+Examples:\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_d\bde\bep\bpt\bth\bh *\b**\b**\b**\b**\b*\n ALLEGRO_AUDIO_DEPTH al_get_sample_instance_depth(const ALLEGRO_SAMPLE_INSTANCE\n *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the audio depth of the sample instance\u2019s sample data.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bD_\bE_\bP_\bT_\bH.\n+Examples:\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_f\bfr\bre\beq\bqu\bue\ben\bnc\bcy\by *\b**\b**\b**\b**\b*\n unsigned int al_get_sample_instance_frequency(const ALLEGRO_SAMPLE_INSTANCE\n *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the frequency (in Hz) of the sample instance\u2019s sample data.\n+Examples:\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_l\ble\ben\bng\bgt\bth\bh *\b**\b**\b**\b**\b*\n unsigned int al_get_sample_instance_length(const ALLEGRO_SAMPLE_INSTANCE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the length of the sample instance in sample values. This property may\n differ from the length of the instance\u2019s sample data.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bl_\be_\bn_\bg_\bt_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bt_\bi_\bm_\be\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bp_\br_\bo_\bp_\bs_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bi_\bm_\bp_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_l\ble\ben\bng\bgt\bth\bh *\b**\b**\b**\b**\b*\n bool al_set_sample_instance_length(ALLEGRO_SAMPLE_INSTANCE *spl,\n unsigned int val)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the length of the sample instance in sample values. This can be used to\n play only parts of the underlying sample. Be careful not to exceed the actual\n length of the sample data, though.\n Return true on success, false on failure. Will fail if the sample instance is\n currently playing.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bl_\be_\bn_\bg_\bt_\bh\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bp_\br_\bo_\bp_\bs_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_p\bpo\bos\bsi\bit\bti\bio\bon\bn *\b**\b**\b**\b**\b*\n unsigned int al_get_sample_instance_position(const ALLEGRO_SAMPLE_INSTANCE\n *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get the playback position of a sample instance.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bp_\bo_\bs_\bi_\bt_\bi_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_p\bpo\bos\bsi\bit\bti\bio\bon\bn *\b**\b**\b**\b**\b*\n bool al_set_sample_instance_position(ALLEGRO_SAMPLE_INSTANCE *spl,\n unsigned int val)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the playback position of a sample instance.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bp_\bo_\bs_\bi_\bt_\bi_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bi_\bm_\bp_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_s\bsp\bpe\bee\bed\bd *\b**\b**\b**\b**\b*\n float al_get_sample_instance_speed(const ALLEGRO_SAMPLE_INSTANCE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the relative playback speed of the sample instance.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bs_\bp_\be_\be_\bd\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_s\bsp\bpe\bee\bed\bd *\b**\b**\b**\b**\b*\n bool al_set_sample_instance_speed(ALLEGRO_SAMPLE_INSTANCE *spl, float val)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the relative playback speed of the sample instance. 1.0 means normal speed.\n Return true on success, false on failure. Will fail if the sample instance is\n attached directly to a voice.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bs_\bp_\be_\be_\bd\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bp_\br_\bo_\bp_\bs_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bi_\bm_\bp_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_g\bga\bai\bin\bn *\b**\b**\b**\b**\b*\n float al_get_sample_instance_gain(const ALLEGRO_SAMPLE_INSTANCE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the playback gain of the sample instance.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bg_\ba_\bi_\bn\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_g\bga\bai\bin\bn *\b**\b**\b**\b**\b*\n bool al_set_sample_instance_gain(ALLEGRO_SAMPLE_INSTANCE *spl, float val)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the playback gain of the sample instance.\n Returns true on success, false on failure. Will fail if the sample instance is\n attached directly to a voice.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bg_\ba_\bi_\bn\n+Examples:\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bp_\br_\bo_\bp_\bs_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_p\bpa\ban\bn *\b**\b**\b**\b**\b*\n float al_get_sample_instance_pan(const ALLEGRO_SAMPLE_INSTANCE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get the pan value of the sample instance.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bp_\ba_\bn.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_p\bpa\ban\bn *\b**\b**\b**\b**\b*\n bool al_set_sample_instance_pan(ALLEGRO_SAMPLE_INSTANCE *spl, float val)\n@@ -675,69 +769,91 @@\n speaker; 0.0 means the sample is centre balanced. A special value\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bP_\bA_\bN_\b__\bN_\bO_\bN_\bE disables panning and plays the sample at its original\n level. This will be louder than a pan value of 0.0.\n Note: panning samples with more than two channels doesn\u2019t work yet.\n Returns true on success, false on failure. Will fail if the sample instance is\n attached directly to a voice.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bp_\ba_\bn, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bP_\bA_\bN_\b__\bN_\bO_\bN_\bE\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bp_\br_\bo_\bp_\bs_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bi_\bm_\bp_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_t\bti\bim\bme\be *\b**\b**\b**\b**\b*\n float al_get_sample_instance_time(const ALLEGRO_SAMPLE_INSTANCE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the length of the sample instance in seconds, assuming a playback speed\n of 1.0.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bl_\be_\bn_\bg_\bt_\bh\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_p\bpl\bla\bay\bym\bmo\bod\bde\be *\b**\b**\b**\b**\b*\n ALLEGRO_PLAYMODE al_get_sample_instance_playmode(const ALLEGRO_SAMPLE_INSTANCE\n *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the playback mode of the sample instance.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bL_\bA_\bY_\bM_\bO_\bD_\bE, _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bp_\bl_\ba_\by_\bm_\bo_\bd_\be\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_p\bpl\bla\bay\bym\bmo\bod\bde\be *\b**\b**\b**\b**\b*\n bool al_set_sample_instance_playmode(ALLEGRO_SAMPLE_INSTANCE *spl,\n ALLEGRO_PLAYMODE val)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the playback mode of the sample instance.\n Returns true on success, false on failure.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bL_\bA_\bY_\bM_\bO_\bD_\bE, _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bp_\bl_\ba_\by_\bm_\bo_\bd_\be\n+Examples:\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_p\bpl\bla\bay\byi\bin\bng\bg *\b**\b**\b**\b**\b*\n bool al_get_sample_instance_playing(const ALLEGRO_SAMPLE_INSTANCE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return true if the sample instance is in the playing state. This may be true\n even if the instance is not attached to anything.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bp_\bl_\ba_\by_\bi_\bn_\bg\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_p\bpl\bla\bay\byi\bin\bng\bg *\b**\b**\b**\b**\b*\n bool al_set_sample_instance_playing(ALLEGRO_SAMPLE_INSTANCE *spl, bool val)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Change whether the sample instance is playing.\n The instance does not need to be attached to anything (since: 5.1.8).\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bp_\bl_\ba_\by_\bi_\bn_\bg\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bp_\br_\bo_\bp_\bs_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_a\bat\btt\bta\bac\bch\bhe\bed\bd *\b**\b**\b**\b**\b*\n bool al_get_sample_instance_attached(const ALLEGRO_SAMPLE_INSTANCE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return whether the sample instance is attached to something.\n See also: _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bt_\bo_\b__\bm_\bi_\bx_\be_\br,\n _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bt_\bo_\b__\bv_\bo_\bi_\bc_\be, _\ba_\bl_\b__\bd_\be_\bt_\ba_\bc_\bh_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bet\bta\bac\bch\bh_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be *\b**\b**\b**\b**\b*\n bool al_detach_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Detach the sample instance from whatever it\u2019s attached to, if anything.\n Returns true on success.\n See also: _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bt_\bo_\b__\bm_\bi_\bx_\be_\br,\n _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bt_\bo_\b__\bv_\bo_\bi_\bc_\be, _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\ba_\bt_\bt_\ba_\bc_\bh_\be_\bd\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be *\b**\b**\b**\b**\b*\n ALLEGRO_SAMPLE *al_get_sample(ALLEGRO_SAMPLE_INSTANCE *spl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the sample data that the sample instance plays.\n Note this returns a pointer to an internal structure, n\bno\bot\bt the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bA_\bM_\bP_\bL_\bE\n that you may have passed to _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be. However, the sample buffer of the\n returned ALLEGRO_SAMPLE will be the same as the one that was used to create the\n sample (passed to _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bs_\ba_\bm_\bp_\bl_\be). You can use _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bd_\ba_\bt_\ba on the\n return value to retrieve and compare it.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be *\b**\b**\b**\b**\b*\n bool al_set_sample(ALLEGRO_SAMPLE_INSTANCE *spl, ALLEGRO_SAMPLE *data)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Change the sample data that a sample instance plays. This can be quite an\n involved process.\n First, the sample is stopped if it is not already.\n Next, if data is NULL, the sample is detached from its parent (if any).\n@@ -746,14 +862,18 @@\n the same frequency, depth and channel configuration. Reattaching may not always\n succeed.\n On success, the sample remains stopped. The playback position and loop end\n points are reset to their default values. The loop mode remains unchanged.\n Returns true on success, false on failure. On failure, the sample will be\n stopped and detached from its parent.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be\n+Examples:\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_c\bch\bha\ban\bnn\bne\bel\bl_\b_m\bma\bat\btr\bri\bix\bx *\b**\b**\b**\b**\b*\n bool al_set_sample_instance_channel_matrix(ALLEGRO_SAMPLE_INSTANCE *spl, const\n float *matrix)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the matrix used to mix the channels coming from this instance into the\n mixer it is attached to. Normally Allegro derives the values of this matrix\n from the gain and pan settings, as well as the channel configurations of this\n@@ -773,14 +893,16 @@\n };\n \n al_set_sample_instance_channel_matrix(instance, matrix);\n Returns true on success, false on failure (e.g.\u00a0if this is not attached to a\n mixer).\n Since: 5.2.3\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: New API.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAu\bud\bdi\bio\bo s\bst\btr\bre\bea\bam\bms\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_A\bAU\bUD\bDI\bIO\bO_\b_S\bST\bTR\bRE\bEA\bAM\bM *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_AUDIO_STREAM ALLEGRO_AUDIO_STREAM;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An ALLEGRO_AUDIO_STREAM object is used to stream generated audio to the sound\n device, in real-time. This is done by reading from a buffer, which is split\n into a number of fragments. Whenever a fragment has finished playing, the user\n@@ -811,14 +933,18 @@\n while ((buf = al_get_audio_stream_fragment(stream))) {\n al_fill_silence(buf, samples_per_buffer, depth, channel_conf);\n al_set_audio_stream_fragment(stream, buf);\n }\n If the stream is created by _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm or _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm then\n it will also generate an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bA_\bU_\bD_\bI_\bO_\b__\bS_\bT_\bR_\bE_\bA_\bM_\b__\bF_\bI_\bN_\bI_\bS_\bH_\bE_\bD event if it\n reaches the end of the file and is not set to loop.\n+Examples:\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm *\b**\b**\b**\b**\b*\n ALLEGRO_AUDIO_STREAM *al_create_audio_stream(size_t fragment_count,\n unsigned int frag_samples, unsigned int freq, ALLEGRO_AUDIO_DEPTH depth,\n ALLEGRO_CHANNEL_CONF chan_conf)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Creates an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bS_\bT_\bR_\bE_\bA_\bM. The stream will be set to play by default. It\n will feed audio data from a buffer, which is split into a number of fragments.\n@@ -851,14 +977,18 @@\n al_get_audio_depth_size(depth);\n samples = bytes_per_fragment / sample_size;\n The size of the complete buffer is:\n buffer_size = bytes_per_fragment * fragment_count\n N\bNo\bot\bte\be:\b: Unlike many Allegro objects, audio streams are not implicitly\n destroyed when Allegro is shut down. You must destroy them manually\n with _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm before the audio system is shut down.\n+Examples:\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boa\bad\bd_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm *\b**\b**\b**\b**\b*\n ALLEGRO_AUDIO_STREAM *al_load_audio_stream(const char *filename,\n size_t buffer_count, unsigned int samples)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Loads an audio file from disk as it is needed.\n Unlike regular streams, the one returned by this function need not be fed by\n the user; the library will automatically read more of the file as it is needed.\n@@ -868,14 +998,18 @@\n details.\n Returns the stream on success, NULL on failure.\n N\bNo\bot\bte\be:\b: the allegro_audio library does not support any audio file\n formats by default. You must use the allegro_acodec addon, or\n register your own format handler.\n See also: _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf, _\ba_\bl_\b__\br_\be_\bg_\bi_\bs_\bt_\be_\br_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bl_\bo_\ba_\bd_\be_\br,\n _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\ba_\bd_\bd_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bp_\bp_\b._\bc\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\be_\be_\bk_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boa\bad\bd_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_f\bf *\b**\b**\b**\b**\b*\n ALLEGRO_AUDIO_STREAM *al_load_audio_stream_f(ALLEGRO_FILE* fp, const char\n *ident,\n size_t buffer_count, unsigned int samples)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Loads an audio file from _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bF_\bI_\bL_\bE stream as it is needed.\n Unlike regular streams, the one returned by this function need not be fed by\n@@ -898,35 +1032,49 @@\n void al_destroy_audio_stream(ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Destroy an audio stream which was created with _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm or\n _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm.\n N\bNo\bot\bte\be:\b: If the stream is still attached to a mixer or voice,\n _\ba_\bl_\b__\bd_\be_\bt_\ba_\bc_\bh_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm is automatically called on it first.\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bi_\bn_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm.\n+Examples:\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_e\bev\bve\ben\bnt\bt_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b*\n ALLEGRO_EVENT_SOURCE *al_get_audio_stream_event_source(\n ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Retrieve the associated event source.\n See _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\br_\ba_\bg_\bm_\be_\bn_\bt for a description of the\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bA_\bU_\bD_\bI_\bO_\b__\bS_\bT_\bR_\bE_\bA_\bM_\b__\bF_\bR_\bA_\bG_\bM_\bE_\bN_\bT event that audio streams emit.\n+Examples:\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\bai\bin\bn_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm *\b**\b**\b**\b**\b*\n void al_drain_audio_stream(ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n You should call this to finalise an audio stream that you will no longer be\n feeding, to wait for all pending buffers to finish playing. The stream\u2019s\n playing state will change to false.\n See also: _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm\n+Examples:\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bew\bwi\bin\bnd\bd_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm *\b**\b**\b**\b**\b*\n bool al_rewind_audio_stream(ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the streaming file playing position to the beginning. Returns true on\n success. Currently this can only be called on streams created with\n _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm, _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm, _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf or\n _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf.\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\be_\be_\bk_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_f\bfr\bre\beq\bqu\bue\ben\bnc\bcy\by *\b**\b**\b**\b**\b*\n unsigned int al_get_audio_stream_frequency(const ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the stream frequency (in Hz).\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_c\bch\bha\ban\bnn\bne\bel\bls\bs *\b**\b**\b**\b**\b*\n ALLEGRO_CHANNEL_CONF al_get_audio_stream_channels(\n const ALLEGRO_AUDIO_STREAM *stream)\n@@ -939,14 +1087,16 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the stream audio depth.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bD_\bE_\bP_\bT_\bH.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_l\ble\ben\bng\bgt\bth\bh *\b**\b**\b**\b**\b*\n unsigned int al_get_audio_stream_length(const ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the stream length in samples.\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\be_\be_\bk_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_s\bsp\bpe\bee\bed\bd *\b**\b**\b**\b**\b*\n float al_get_audio_stream_speed(const ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the relative playback speed of the stream.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\bp_\be_\be_\bd.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_s\bsp\bpe\bee\bed\bd *\b**\b**\b**\b**\b*\n bool al_set_audio_stream_speed(ALLEGRO_AUDIO_STREAM *stream, float val)\n@@ -956,21 +1106,26 @@\n attached directly to a voice.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\bp_\be_\be_\bd.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_g\bga\bai\bin\bn *\b**\b**\b**\b**\b*\n float al_get_audio_stream_gain(const ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the playback gain of the stream.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bg_\ba_\bi_\bn.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_g\bga\bai\bin\bn *\b**\b**\b**\b**\b*\n bool al_set_audio_stream_gain(ALLEGRO_AUDIO_STREAM *stream, float val)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the playback gain of the stream.\n Returns true on success, false on failure. Will fail if the audio stream is\n attached directly to a voice.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bg_\ba_\bi_\bn.\n+Examples:\n+ * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_p\bpa\ban\bn *\b**\b**\b**\b**\b*\n float al_get_audio_stream_pan(const ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get the pan value of the stream.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bp_\ba_\bn.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_p\bpa\ban\bn *\b**\b**\b**\b**\b*\n bool al_set_audio_stream_pan(ALLEGRO_AUDIO_STREAM *stream, float val)\n@@ -979,50 +1134,66 @@\n only through the left speaker; +1.0 means only through the right speaker; 0.0\n means the sample is centre balanced. A special value _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bP_\bA_\bN_\b__\bN_\bO_\bN_\bE\n disables panning and plays the stream at its original level. This will be\n louder than a pan value of 0.0.\n Returns true on success, false on failure. Will fail if the audio stream is\n attached directly to a voice.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bp_\ba_\bn, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bP_\bA_\bN_\b__\bN_\bO_\bN_\bE\n+Examples:\n+ * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_p\bpl\bla\bay\byi\bin\bng\bg *\b**\b**\b**\b**\b*\n bool al_get_audio_stream_playing(const ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return true if the stream is playing.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bp_\bl_\ba_\by_\bi_\bn_\bg.\n+Examples:\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b._\bc\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\be_\be_\bk_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_p\bpl\bla\bay\byi\bin\bng\bg *\b**\b**\b**\b**\b*\n bool al_set_audio_stream_playing(ALLEGRO_AUDIO_STREAM *stream, bool val)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Change whether the stream is playing.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bp_\bl_\ba_\by_\bi_\bn_\bg\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bi_\bm_\bp_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b._\bc\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\be_\be_\bk_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_p\bpl\bla\bay\bym\bmo\bod\bde\be *\b**\b**\b**\b**\b*\n ALLEGRO_PLAYMODE al_get_audio_stream_playmode(\n const ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the playback mode of the stream.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bL_\bA_\bY_\bM_\bO_\bD_\bE, _\ba_\bl_\b__\bs_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bp_\bl_\ba_\by_\bm_\bo_\bd_\be.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_p\bpl\bla\bay\bym\bmo\bod\bde\be *\b**\b**\b**\b**\b*\n bool al_set_audio_stream_playmode(ALLEGRO_AUDIO_STREAM *stream,\n ALLEGRO_PLAYMODE val)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the playback mode of the stream.\n Returns true on success, false on failure.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bL_\bA_\bY_\bM_\bO_\bD_\bE, _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bp_\bl_\ba_\by_\bm_\bo_\bd_\be.\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bp_\bp_\b._\bc\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\be_\be_\bk_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_a\bat\btt\bta\bac\bch\bhe\bed\bd *\b**\b**\b**\b**\b*\n bool al_get_audio_stream_attached(const ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return whether the stream is attached to something.\n See also: _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bt_\bo_\b__\bm_\bi_\bx_\be_\br, _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bt_\bo_\b__\bv_\bo_\bi_\bc_\be,\n _\ba_\bl_\b__\bd_\be_\bt_\ba_\bc_\bh_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bet\bta\bac\bch\bh_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm *\b**\b**\b**\b**\b*\n bool al_detach_audio_stream(ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Detach the stream from whatever it\u2019s attached to, if anything.\n See also: _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bt_\bo_\b__\bm_\bi_\bx_\be_\br, _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bt_\bo_\b__\bv_\bo_\bi_\bc_\be,\n _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\ba_\bt_\bt_\ba_\bc_\bh_\be_\bd.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_p\bpl\bla\bay\bye\bed\bd_\b_s\bsa\bam\bmp\bpl\ble\bes\bs *\b**\b**\b**\b**\b*\n uint64_t al_get_audio_stream_played_samples(const ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get the number of samples consumed by the parent since the audio stream was\n started.\n Since: 5.1.8\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_f\bfr\bra\bag\bgm\bme\ben\bnt\bt *\b**\b**\b**\b**\b*\n@@ -1040,21 +1211,29 @@\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bA_\bU_\bD_\bI_\bO_\b__\bS_\bT_\bR_\bE_\bA_\bM_\b__\bF_\bR_\bA_\bG_\bM_\bE_\bN_\bT event will be generated whenever\n a new fragment is ready. However, getting an event is n\bno\bot\bt a guarantee\n that _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\br_\ba_\bg_\bm_\be_\bn_\bt will not return NULL, so you still\n must check for it.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\br_\ba_\bg_\bm_\be_\bn_\bt, _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be,\n _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\br_\be_\bq_\bu_\be_\bn_\bc_\by, _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bc_\bh_\ba_\bn_\bn_\be_\bl_\bs,\n _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bd_\be_\bp_\bt_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bl_\be_\bn_\bg_\bt_\bh\n+Examples:\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_f\bfr\bra\bag\bgm\bme\ben\bnt\bt *\b**\b**\b**\b**\b*\n bool al_set_audio_stream_fragment(ALLEGRO_AUDIO_STREAM *stream, void *val)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This function needs to be called for every successful call of\n _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\br_\ba_\bg_\bm_\be_\bn_\bt to indicate that the buffer (pointed to by val) is\n filled with new data.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\br_\ba_\bg_\bm_\be_\bn_\bt\n+Examples:\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_f\bfr\bra\bag\bgm\bme\ben\bnt\bts\bs *\b**\b**\b**\b**\b*\n unsigned int al_get_audio_stream_fragments(const ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the number of fragments this stream uses. This is the same value as\n passed to _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm when a new stream is created.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bv_\ba_\bi_\bl_\ba_\bb_\bl_\be_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\br_\ba_\bg_\bm_\be_\bn_\bt_\bs\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bav\bva\bai\bil\bla\bab\bbl\ble\be_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_f\bfr\bra\bag\bgm\bme\ben\bnt\bts\bs *\b**\b**\b**\b**\b*\n@@ -1067,35 +1246,43 @@\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bee\bek\bk_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_s\bse\bec\bcs\bs *\b**\b**\b**\b**\b*\n bool al_seek_audio_stream_secs(ALLEGRO_AUDIO_STREAM *stream, double time)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the streaming file playing position to time. Returns true on success.\n Currently this can only be called on streams created with _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm,\n _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm, _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf or _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bp_\bo_\bs_\bi_\bt_\bi_\bo_\bn_\b__\bs_\be_\bc_\bs, _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bl_\be_\bn_\bg_\bt_\bh_\b__\bs_\be_\bc_\bs\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\be_\be_\bk_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_p\bpo\bos\bsi\bit\bti\bio\bon\bn_\b_s\bse\bec\bcs\bs *\b**\b**\b**\b**\b*\n double al_get_audio_stream_position_secs(ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the position of the stream in seconds. Currently this can only be called\n on streams created with _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm, _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm,\n _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf or _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bl_\be_\bn_\bg_\bt_\bh_\b__\bs_\be_\bc_\bs\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\be_\be_\bk_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_l\ble\ben\bng\bgt\bth\bh_\b_s\bse\bec\bcs\bs *\b**\b**\b**\b**\b*\n double al_get_audio_stream_length_secs(ALLEGRO_AUDIO_STREAM *stream)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the length of the stream in seconds, if known. Otherwise returns zero.\n Currently this can only be called on streams created with _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm,\n _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm, _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf or _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bp_\bo_\bs_\bi_\bt_\bi_\bo_\bn_\b__\bs_\be_\bc_\bs\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\be_\be_\bk_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_l\blo\boo\bop\bp_\b_s\bse\bec\bcs\bs *\b**\b**\b**\b**\b*\n bool al_set_audio_stream_loop_secs(ALLEGRO_AUDIO_STREAM *stream,\n double start, double end)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets the loop points for the stream in seconds. Currently this can only be\n called on streams created with _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm, _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm,\n _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf or _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf.\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\be_\be_\bk_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_c\bch\bha\ban\bnn\bne\bel\bl_\b_m\bma\bat\btr\bri\bix\bx *\b**\b**\b**\b**\b*\n Source Code\n Like _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bc_\bh_\ba_\bn_\bn_\be_\bl_\b__\bm_\ba_\bt_\br_\bi_\bx but for streams.\n Since: 5.2.3\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: New API.\n *\b**\b**\b**\b**\b**\b* A\bAd\bdv\bva\ban\bnc\bce\bed\bd a\bau\bud\bdi\bio\bo f\bfi\bil\ble\be I\bI/\b/O\bO *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\beg\bgi\bis\bst\bte\ber\br_\b_s\bsa\bam\bmp\bpl\ble\be_\b_l\blo\boa\bad\bde\ber\br *\b**\b**\b**\b**\b*\n@@ -1225,26 +1412,32 @@\n drivers. Enumerating or choosing other recording devices is not yet supported.\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_A\bAU\bUD\bDI\bIO\bO_\b_R\bRE\bEC\bCO\bOR\bRD\bDE\bER\bR *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_AUDIO_RECORDER ALLEGRO_AUDIO_RECORDER;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An opaque datatype that represents a recording device.\n Since: 5.1.1\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: The API may need a slight redesign.\n+Examples:\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bn_\ba_\bm_\be_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_A\bAU\bUD\bDI\bIO\bO_\b_R\bRE\bEC\bCO\bOR\bRD\bDE\bER\bR_\b_E\bEV\bVE\bEN\bNT\bT *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_AUDIO_RECORDER_EVENT ALLEGRO_AUDIO_RECORDER_EVENT;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Structure that holds the audio recorder event data. Every event type will\n contain:\n * .source: pointer to the audio recorder\n The following will be available depending on the event type:\n * .buffer: pointer to buffer containing the audio samples\n * .samples: number of samples (not bytes) that are available\n Since 5.1.1\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\br_\be_\bc_\bo_\br_\bd_\be_\br_\b__\be_\bv_\be_\bn_\bt\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: The API may need a slight redesign.\n+Examples:\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bn_\ba_\bm_\be_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_a\bau\bud\bdi\bio\bo_\b_r\bre\bec\bco\bor\brd\bde\ber\br *\b**\b**\b**\b**\b*\n ALLEGRO_AUDIO_RECORDER *al_create_audio_recorder(size_t fragment_count,\n unsigned int samples, unsigned int frequency,\n ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Creates an audio recorder using the system\u2019s default recording device. (So if\n the returned device does not work, try updating the system\u2019s default recording\n@@ -1267,23 +1460,29 @@\n * 44100 - CD quality music (if 16-bit, stereo)\n For maximum compatibility, use a depth of ALLEGRO_AUDIO_DEPTH_UINT8 or\n ALLEGRO_AUDIO_DEPTH_INT16, and a single (mono) channel.\n The recorder will not record until you start it with _\ba_\bl_\b__\bs_\bt_\ba_\br_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\br_\be_\bc_\bo_\br_\bd_\be_\br.\n On failure, returns NULL.\n Since: 5.1.1\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: The API may need a slight redesign.\n+Examples:\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bn_\ba_\bm_\be_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bst\bta\bar\brt\bt_\b_a\bau\bud\bdi\bio\bo_\b_r\bre\bec\bco\bor\brd\bde\ber\br *\b**\b**\b**\b**\b*\n bool al_start_audio_recorder(ALLEGRO_AUDIO_RECORDER *r)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Begin recording into the fragment buffer. Once a complete fragment has been\n captured (as specified in _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\ba_\bu_\bd_\bi_\bo_\b__\br_\be_\bc_\bo_\br_\bd_\be_\br), an\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bA_\bU_\bD_\bI_\bO_\b__\bR_\bE_\bC_\bO_\bR_\bD_\bE_\bR_\b__\bF_\bR_\bA_\bG_\bM_\bE_\bN_\bT event will be triggered.\n Returns true if it was able to begin recording.\n Since: 5.1.1\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: The API may need a slight redesign.\n+Examples:\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bn_\ba_\bm_\be_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bst\bto\bop\bp_\b_a\bau\bud\bdi\bio\bo_\b_r\bre\bec\bco\bor\brd\bde\ber\br *\b**\b**\b**\b**\b*\n void al_stop_audio_recorder(ALLEGRO_AUDIO_RECORDER *r)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Stop capturing audio data. Note that the audio recorder is still active and\n consuming resources, so if you are finished recording you should destroy it\n with _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\ba_\bu_\bd_\bi_\bo_\b__\br_\be_\bc_\bo_\br_\bd_\be_\br.\n You may still receive a few events after you call this function as the device\n@@ -1301,60 +1500,81 @@\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: The API may need a slight redesign.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_r\bre\bec\bco\bor\brd\bde\ber\br_\b_e\bev\bve\ben\bnt\bt *\b**\b**\b**\b**\b*\n ALLEGRO_AUDIO_RECORDER_EVENT *al_get_audio_recorder_event(ALLEGRO_EVENT *event)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the event as an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bR_\bE_\bC_\bO_\bR_\bD_\bE_\bR_\b__\bE_\bV_\bE_\bN_\bT.\n Since: 5.1.1\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: The API may need a slight redesign.\n+Examples:\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bn_\ba_\bm_\be_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_r\bre\bec\bco\bor\brd\bde\ber\br_\b_e\bev\bve\ben\bnt\bt_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b*\n ALLEGRO_EVENT_SOURCE *al_get_audio_recorder_event_source(ALLEGRO_AUDIO_RECORDER\n *r)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the event source for the recorder that generates the various recording\n events.\n Since: 5.1.1\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: The API may need a slight redesign.\n+Examples:\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bn_\ba_\bm_\be_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_a\bau\bud\bdi\bio\bo_\b_r\bre\bec\bco\bor\brd\bde\ber\br *\b**\b**\b**\b**\b*\n void al_destroy_audio_recorder(ALLEGRO_AUDIO_RECORDER *r)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Destroys the audio recorder and frees all resources associated with it. It is\n safe to destroy a recorder that is recording.\n You may receive events after the recorder has been destroyed. They must be\n ignored, as the fragment buffer will no longer be valid.\n Since: 5.1.1\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: The API may need a slight redesign.\n+Examples:\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bn_\ba_\bm_\be_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAu\bud\bdi\bio\bo d\bde\bev\bvi\bic\bce\bes\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_A\bAU\bUD\bDI\bIO\bO_\b_D\bDE\bEV\bVI\bIC\bCE\bE *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_AUDIO_DEVICE ALLEGRO_AUDIO_DEVICE;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An opaque datatype that represents an audio device.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bd_\be_\bv_\bi_\bc_\be_\bs_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_n\bnu\bum\bm_\b_a\bau\bud\bdi\bio\bo_\b_o\bou\but\btp\bpu\but\bt_\b_d\bde\bev\bvi\bic\bce\bes\bs *\b**\b**\b**\b**\b*\n int al_get_num_audio_output_devices()\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get the number of available audio output devices on the system.\n Since: 5.2.8\n return -1 for unsupported drivers.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bd_\be_\bv_\bi_\bc_\be_\bs_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_o\bou\but\btp\bpu\but\bt_\b_d\bde\bev\bvi\bic\bce\be *\b**\b**\b**\b**\b*\n const ALLEGRO_AUDIO_DEVICE* al_get_audio_output_device(int index)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get the output audio device of the specified index.\n Since: 5.2.8\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bd_\be_\bv_\bi_\bc_\be_\bs_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_d\bde\bev\bvi\bic\bce\be_\b_n\bna\bam\bme\be *\b**\b**\b**\b**\b*\n const char* al_get_audio_device_name(const ALLEGRO_AUDIO_DEVICE * device)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get the user friendly display name of the device.\n Since: 5.2.8\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bd_\be_\bv_\bi_\bc_\be_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* V\bVo\boi\bic\bce\bes\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_V\bVO\bOI\bIC\bCE\bE *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_VOICE ALLEGRO_VOICE;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n A voice represents an audio device on the system, which may be a real device,\n or an abstract device provided by the operating system. To play back audio, you\n would attach a mixer, sample instance or audio stream to a voice.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bM_\bI_\bX_\bE_\bR, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bA_\bM_\bP_\bL_\bE, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bS_\bT_\bR_\bE_\bA_\bM\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_v\bvo\boi\bic\bce\be *\b**\b**\b**\b**\b*\n ALLEGRO_VOICE *al_create_voice(unsigned int freq,\n ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Creates a voice structure and allocates a voice from the digital sound driver.\n The passed frequency (in Hz), sample format and channel configuration are used\n as a hint to what kind of data will be sent to the voice. However, the\n@@ -1364,20 +1584,28 @@\n all its input streams to the voice format and care does not have to be taken\n for this. However if you access the voice directly, make sure to not rely on\n the parameters passed to this function, but instead query the returned voice\n for the actual settings.\n Reasonable default arguments are:\n al_create_voice(44100, ALLEGRO_AUDIO_DEPTH_INT16, ALLEGRO_CHANNEL_CONF_2)\n See also: _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bv_\bo_\bi_\bc_\be\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_v\bvo\boi\bic\bce\be *\b**\b**\b**\b**\b*\n void al_destroy_voice(ALLEGRO_VOICE *voice)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Destroys the voice and deallocates it from the digital driver. Does nothing if\n the voice is NULL.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bv_\bo_\bi_\bc_\be\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bet\bta\bac\bch\bh_\b_v\bvo\boi\bic\bce\be *\b**\b**\b**\b**\b*\n void al_detach_voice(ALLEGRO_VOICE *voice)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Detaches the mixer, sample instance or audio stream from the voice.\n See also: _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bm_\bi_\bx_\be_\br_\b__\bt_\bo_\b__\bv_\bo_\bi_\bc_\be, _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bt_\bo_\b__\bv_\bo_\bi_\bc_\be,\n _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bt_\bo_\b__\bv_\bo_\bi_\bc_\be\n *\b**\b**\b**\b**\b* a\bal\bl_\b_a\bat\btt\bta\bac\bch\bh_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_t\bto\bo_\b_v\bvo\boi\bic\bce\be *\b**\b**\b**\b**\b*\n@@ -1389,34 +1617,44 @@\n create a voice with the buffer count and buffer size the stream uses.\n An audio stream attached directly to a voice has a number of limitations: The\n audio stream plays immediately and cannot be stopped. The stream position,\n speed, gain and panning cannot be changed. At this time, we don\u2019t recommend\n attaching audio streams directly to voices. Use a mixer inbetween.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bd_\be_\bt_\ba_\bc_\bh_\b__\bv_\bo_\bi_\bc_\be, _\ba_\bl_\b__\bv_\bo_\bi_\bc_\be_\b__\bh_\ba_\bs_\b__\ba_\bt_\bt_\ba_\bc_\bh_\bm_\be_\bn_\bt_\bs\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_a\bat\btt\bta\bac\bch\bh_\b_m\bmi\bix\bxe\ber\br_\b_t\bto\bo_\b_v\bvo\boi\bic\bce\be *\b**\b**\b**\b**\b*\n bool al_attach_mixer_to_voice(ALLEGRO_MIXER *mixer, ALLEGRO_VOICE *voice)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Attaches a mixer to a voice. It must have the same frequency and channel\n configuration, but the depth may be different.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bd_\be_\bt_\ba_\bc_\bh_\b__\bv_\bo_\bi_\bc_\be, _\ba_\bl_\b__\bv_\bo_\bi_\bc_\be_\b__\bh_\ba_\bs_\b__\ba_\bt_\bt_\ba_\bc_\bh_\bm_\be_\bn_\bt_\bs\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_a\bat\btt\bta\bac\bch\bh_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_t\bto\bo_\b_v\bvo\boi\bic\bce\be *\b**\b**\b**\b**\b*\n bool al_attach_sample_instance_to_voice(ALLEGRO_SAMPLE_INSTANCE *spl,\n ALLEGRO_VOICE *voice)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Attaches a sample instance to a voice, and allows it to play. The instance\u2019s\n gain and loop mode will be ignored, and it must have the same frequency,\n channel configuration and depth (including signed-ness) as the voice. This\n function may fail if the selected driver doesn\u2019t support preloading sample\n data.\n At this time, we don\u2019t recommend attaching sample instances directly to voices.\n Use a mixer inbetween.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bd_\be_\bt_\ba_\bc_\bh_\b__\bv_\bo_\bi_\bc_\be, _\ba_\bl_\b__\bv_\bo_\bi_\bc_\be_\b__\bh_\ba_\bs_\b__\ba_\bt_\bt_\ba_\bc_\bh_\bm_\be_\bn_\bt_\bs\n+Examples:\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_v\bvo\boi\bic\bce\be_\b_f\bfr\bre\beq\bqu\bue\ben\bnc\bcy\by *\b**\b**\b**\b**\b*\n unsigned int al_get_voice_frequency(const ALLEGRO_VOICE *voice)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the frequency of the voice (in Hz), e.g.\u00a044100.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_v\bvo\boi\bic\bce\be_\b_c\bch\bha\ban\bnn\bne\bel\bls\bs *\b**\b**\b**\b**\b*\n ALLEGRO_CHANNEL_CONF al_get_voice_channels(const ALLEGRO_VOICE *voice)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n@@ -1428,22 +1666,26 @@\n Return the audio depth of the voice.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bD_\bE_\bP_\bT_\bH.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_v\bvo\boi\bic\bce\be_\b_p\bpl\bla\bay\byi\bin\bng\bg *\b**\b**\b**\b**\b*\n bool al_get_voice_playing(const ALLEGRO_VOICE *voice)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return true if the voice is currently playing.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bv_\bo_\bi_\bc_\be_\b__\bp_\bl_\ba_\by_\bi_\bn_\bg\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_v\bvo\boi\bic\bce\be_\b_p\bpl\bla\bay\byi\bin\bng\bg *\b**\b**\b**\b**\b*\n bool al_set_voice_playing(ALLEGRO_VOICE *voice, bool val)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Change whether a voice is playing or not. This can only work if the voice has a\n non-streaming object attached to it, e.g.\u00a0a sample instance. On success the\n voice\u2019s current sample position is reset.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bv_\bo_\bi_\bc_\be_\b__\bp_\bl_\ba_\by_\bi_\bn_\bg\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_v\bvo\boi\bic\bce\be_\b_p\bpo\bos\bsi\bit\bti\bio\bon\bn *\b**\b**\b**\b**\b*\n unsigned int al_get_voice_position(const ALLEGRO_VOICE *voice)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n When the voice has a non-streaming object attached to it, e.g.\u00a0a sample,\n returns the voice\u2019s current sample position. Otherwise, returns zero.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bv_\bo_\bi_\bc_\be_\b__\bp_\bo_\bs_\bi_\bt_\bi_\bo_\bn.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_v\bvo\boi\bic\bce\be_\b_p\bpo\bos\bsi\bit\bti\bio\bon\bn *\b**\b**\b**\b**\b*\n@@ -1468,14 +1710,18 @@\n it converts channel configurations, sample frequencies and audio depths of the\n attached sample instances and audio streams accordingly. You can control the\n quality of this conversion using ALLEGRO_MIXER_QUALITY.\n When going from mono to stereo (and above), the mixer reduces the volume of\n both channels by sqrt(2). When going from stereo (and above) to mono, the mixer\n reduces the volume of the left and right channels by sqrt(2) before adding them\n to the center channel (if present).\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_M\bMI\bIX\bXE\bER\bR_\b_Q\bQU\bUA\bAL\bLI\bIT\bTY\bY *\b**\b**\b**\b**\b*\n enum ALLEGRO_MIXER_QUALITY\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n * ALLEGRO_MIXER_QUALITY_POINT - point sampling\n * ALLEGRO_MIXER_QUALITY_LINEAR - linear interpolation\n * ALLEGRO_MIXER_QUALITY_CUBIC - cubic interpolation (since: 5.0.8, 5.1.4)\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_m\bmi\bix\bxe\ber\br *\b**\b**\b**\b**\b*\n@@ -1488,28 +1734,40 @@\n ALLEGRO_AUDIO_DEPTH_INT16 (not yet complete).\n To actually produce any output, the mixer will have to be attached to a voice\n using _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bm_\bi_\bx_\be_\br_\b__\bt_\bo_\b__\bv_\bo_\bi_\bc_\be.\n Reasonable default arguments are:\n al_create_mixer(44100, ALLEGRO_AUDIO_DEPTH_FLOAT32, ALLEGRO_CHANNEL_CONF_2)\n Returns true on success, false on error.\n See also: _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bm_\bi_\bx_\be_\br, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bD_\bE_\bP_\bT_\bH, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bH_\bA_\bN_\bN_\bE_\bL_\b__\bC_\bO_\bN_\bF\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_m\bmi\bix\bxe\ber\br *\b**\b**\b**\b**\b*\n void al_destroy_mixer(ALLEGRO_MIXER *mixer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Destroys the mixer.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bm_\bi_\bx_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_d\bde\bef\bfa\bau\bul\blt\bt_\b_m\bmi\bix\bxe\ber\br *\b**\b**\b**\b**\b*\n ALLEGRO_MIXER *al_get_default_mixer(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the default mixer, or NULL if one has not been set. Although different\n configurations of mixers and voices can be used, in most cases a single mixer\n attached to a voice is what you want. The default mixer is used by\n _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\bs_\ba_\bm_\bp_\bl_\be.\n See also: _\ba_\bl_\b__\br_\be_\bs_\be_\br_\bv_\be_\b__\bs_\ba_\bm_\bp_\bl_\be_\bs, _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\bs_\ba_\bm_\bp_\bl_\be, _\ba_\bl_\b__\bs_\be_\bt_\b__\bd_\be_\bf_\ba_\bu_\bl_\bt_\b__\bm_\bi_\bx_\be_\br,\n _\ba_\bl_\b__\br_\be_\bs_\bt_\bo_\br_\be_\b__\bd_\be_\bf_\ba_\bu_\bl_\bt_\b__\bm_\bi_\bx_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bp_\br_\bo_\bp_\bs_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\br_\be_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_d\bde\bef\bfa\bau\bul\blt\bt_\b_m\bmi\bix\bxe\ber\br *\b**\b**\b**\b**\b*\n bool al_set_default_mixer(ALLEGRO_MIXER *mixer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets the default mixer. All samples started with _\ba_\bl_\b__\bp_\bl_\ba_\by_\b__\bs_\ba_\bm_\bp_\bl_\be will be stopped\n and all sample instances returned by _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bd will be invalidated. If\n you are using your own mixer, this should be called before _\ba_\bl_\b__\br_\be_\bs_\be_\br_\bv_\be_\b__\bs_\ba_\bm_\bp_\bl_\be_\bs.\n Returns true on success, false on error.\n@@ -1545,30 +1803,41 @@\n Attaches the mixer passed as the first argument onto the mixer passed as the\n second argument. The first mixer (that is going to be attached) must not\n already be attached to anything. Both mixers must use the same frequency, audio\n depth and channel configuration.\n Returns true on success, false on error.\n It is invalid to attach a mixer to itself.\n See also: _\ba_\bl_\b__\bd_\be_\bt_\ba_\bc_\bh_\b__\bm_\bi_\bx_\be_\br.\n+Examples:\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_a\bat\btt\bta\bac\bch\bh_\b_s\bsa\bam\bmp\bpl\ble\be_\b_i\bin\bns\bst\bta\ban\bnc\bce\be_\b_t\bto\bo_\b_m\bmi\bix\bxe\ber\br *\b**\b**\b**\b**\b*\n bool al_attach_sample_instance_to_mixer(ALLEGRO_SAMPLE_INSTANCE *spl,\n ALLEGRO_MIXER *mixer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Attach a sample instance to a mixer. The instance must not already be attached\n to anything.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bd_\be_\bt_\ba_\bc_\bh_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_a\bat\btt\bta\bac\bch\bh_\b_a\bau\bud\bdi\bio\bo_\b_s\bst\btr\bre\bea\bam\bm_\b_t\bto\bo_\b_m\bmi\bix\bxe\ber\br *\b**\b**\b**\b**\b*\n bool al_attach_audio_stream_to_mixer(ALLEGRO_AUDIO_STREAM *stream,\n ALLEGRO_MIXER *mixer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Attach an audio stream to a mixer. The stream must not already be attached to\n anything.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bd_\be_\bt_\ba_\bc_\bh_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm.\n+Examples:\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmi\bix\bxe\ber\br_\b_f\bfr\bre\beq\bqu\bue\ben\bnc\bcy\by *\b**\b**\b**\b**\b*\n unsigned int al_get_mixer_frequency(const ALLEGRO_MIXER *mixer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the mixer frequency (in Hz).\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bi_\bx_\be_\br_\b__\bf_\br_\be_\bq_\bu_\be_\bn_\bc_\by\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_m\bmi\bix\bxe\ber\br_\b_f\bfr\bre\beq\bqu\bue\ben\bnc\bcy\by *\b**\b**\b**\b**\b*\n bool al_set_mixer_frequency(ALLEGRO_MIXER *mixer, unsigned int val)\n@@ -1578,32 +1847,41 @@\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bi_\bx_\be_\br_\b__\bf_\br_\be_\bq_\bu_\be_\bn_\bc_\by\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmi\bix\bxe\ber\br_\b_c\bch\bha\ban\bnn\bne\bel\bls\bs *\b**\b**\b**\b**\b*\n ALLEGRO_CHANNEL_CONF al_get_mixer_channels(const ALLEGRO_MIXER *mixer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the mixer channel configuration.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bH_\bA_\bN_\bN_\bE_\bL_\b__\bC_\bO_\bN_\bF.\n+Examples:\n+ * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmi\bix\bxe\ber\br_\b_d\bde\bep\bpt\bth\bh *\b**\b**\b**\b**\b*\n ALLEGRO_AUDIO_DEPTH al_get_mixer_depth(const ALLEGRO_MIXER *mixer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the mixer audio depth.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bD_\bE_\bP_\bT_\bH.\n+Examples:\n+ * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmi\bix\bxe\ber\br_\b_g\bga\bai\bin\bn *\b**\b**\b**\b**\b*\n float al_get_mixer_gain(const ALLEGRO_MIXER *mixer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the mixer gain (amplification factor). The default is 1.0.\n Since: 5.0.6, 5.1.0\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bi_\bx_\be_\br_\b__\bg_\ba_\bi_\bn.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_m\bmi\bix\bxe\ber\br_\b_g\bga\bai\bin\bn *\b**\b**\b**\b**\b*\n bool al_set_mixer_gain(ALLEGRO_MIXER *mixer, float new_gain)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the mixer gain (amplification factor).\n Returns true on success, false on failure.\n Since: 5.0.6, 5.1.0\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bi_\bx_\be_\br_\b__\bg_\ba_\bi_\bn\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bp_\br_\bo_\bp_\bs_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmi\bix\bxe\ber\br_\b_q\bqu\bua\bal\bli\bit\bty\by *\b**\b**\b**\b**\b*\n ALLEGRO_MIXER_QUALITY al_get_mixer_quality(const ALLEGRO_MIXER *mixer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the mixer quality.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bM_\bI_\bX_\bE_\bR_\b__\bQ_\bU_\bA_\bL_\bI_\bT_\bY, _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bi_\bx_\be_\br_\b__\bq_\bu_\ba_\bl_\bi_\bt_\by\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_m\bmi\bix\bxe\ber\br_\b_q\bqu\bua\bal\bli\bit\bty\by *\b**\b**\b**\b**\b*\n bool al_set_mixer_quality(ALLEGRO_MIXER *mixer, ALLEGRO_MIXER_QUALITY\n@@ -1614,20 +1892,24 @@\n Returns true on success, false on failure.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bM_\bI_\bX_\bE_\bR_\b__\bQ_\bU_\bA_\bL_\bI_\bT_\bY, _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bi_\bx_\be_\br_\b__\bq_\bu_\ba_\bl_\bi_\bt_\by\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmi\bix\bxe\ber\br_\b_p\bpl\bla\bay\byi\bin\bng\bg *\b**\b**\b**\b**\b*\n bool al_get_mixer_playing(const ALLEGRO_MIXER *mixer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return true if the mixer is playing.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bi_\bx_\be_\br_\b__\bp_\bl_\ba_\by_\bi_\bn_\bg.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_m\bmi\bix\bxe\ber\br_\b_p\bpl\bla\bay\byi\bin\bng\bg *\b**\b**\b**\b**\b*\n bool al_set_mixer_playing(ALLEGRO_MIXER *mixer, bool val)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Change whether the mixer is playing.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bi_\bx_\be_\br_\b__\bp_\bl_\ba_\by_\bi_\bn_\bg.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmi\bix\bxe\ber\br_\b_a\bat\btt\bta\bac\bch\bhe\bed\bd *\b**\b**\b**\b**\b*\n bool al_get_mixer_attached(const ALLEGRO_MIXER *mixer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return true if the mixer is attached to something.\n See also: _\ba_\bl_\b__\bm_\bi_\bx_\be_\br_\b__\bh_\ba_\bs_\b__\ba_\bt_\bt_\ba_\bc_\bh_\bm_\be_\bn_\bt_\bs, _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\ba_\bm_\bp_\bl_\be_\b__\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be_\b__\bt_\bo_\b__\bm_\bi_\bx_\be_\br,\n _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bt_\bo_\b__\bm_\bi_\bx_\be_\br, _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bm_\bi_\bx_\be_\br_\b__\bt_\bo_\b__\bm_\bi_\bx_\be_\br, _\ba_\bl_\b__\bd_\be_\bt_\ba_\bc_\bh_\b__\bm_\bi_\bx_\be_\br\n *\b**\b**\b**\b**\b* a\bal\bl_\b_m\bmi\bix\bxe\ber\br_\b_h\bha\bas\bs_\b_a\bat\btt\bta\bac\bch\bhm\bme\ben\bnt\bts\bs *\b**\b**\b**\b**\b*\n@@ -1638,23 +1920,29 @@\n _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bt_\bo_\b__\bm_\bi_\bx_\be_\br, _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bm_\bi_\bx_\be_\br_\b__\bt_\bo_\b__\bm_\bi_\bx_\be_\br, _\ba_\bl_\b__\bd_\be_\bt_\ba_\bc_\bh_\b__\bm_\bi_\bx_\be_\br\n Since: 5.2.9\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bet\bta\bac\bch\bh_\b_m\bmi\bix\bxe\ber\br *\b**\b**\b**\b**\b*\n bool al_detach_mixer(ALLEGRO_MIXER *mixer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Detach the mixer from whatever it is attached to, if anything.\n See also: _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bm_\bi_\bx_\be_\br_\b__\bt_\bo_\b__\bm_\bi_\bx_\be_\br.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_m\bmi\bix\bxe\ber\br_\b_p\bpo\bos\bst\btp\bpr\bro\boc\bce\bes\bss\bs_\b_c\bca\bal\bll\blb\bba\bac\bck\bk *\b**\b**\b**\b**\b*\n bool al_set_mixer_postprocess_callback(ALLEGRO_MIXER *mixer,\n void (*pp_callback)(void *buf, unsigned int samples, void *data),\n void *pp_callback_userdata)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets a post-processing filter function that\u2019s called after the attached streams\n have been mixed. The buffer\u2019s format will be whatever the mixer was created\n with. The sample count and user-data pointer is also passed.\n N\bNo\bot\bte\be:\b: The callback is called from a dedicated audio thread.\n+Examples:\n+ * _\be_\bx_\b__\br_\be_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bp_\bp_\b._\bc\n *\b**\b**\b**\b**\b**\b* M\bMi\bis\bsc\bce\bel\bla\ban\bne\beo\bou\bus\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_A\bAU\bUD\bDI\bIO\bO_\b_D\bDE\bEP\bPT\bTH\bH *\b**\b**\b**\b**\b*\n enum ALLEGRO_AUDIO_DEPTH\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sample depth and type as well as signedness. Mixers only use 32-bit signed\n float (-1..+1), or 16-bit signed integers. Signedness is determined by an\n \u201cunsigned\u201d bit-flag applied to the depth value.\n@@ -1663,37 +1951,47 @@\n * ALLEGRO_AUDIO_DEPTH_INT24\n * ALLEGRO_AUDIO_DEPTH_FLOAT32\n * ALLEGRO_AUDIO_DEPTH_UNSIGNED\n For convenience:\n * ALLEGRO_AUDIO_DEPTH_UINT8\n * ALLEGRO_AUDIO_DEPTH_UINT16\n * ALLEGRO_AUDIO_DEPTH_UINT24\n+Examples:\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_A\bAU\bUD\bDI\bIO\bO_\b_P\bPA\bAN\bN_\b_N\bNO\bON\bNE\bE *\b**\b**\b**\b**\b*\n #define ALLEGRO_AUDIO_PAN_NONE (-1000.0f)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n A special value for the pan property of sample instances and audio streams. Use\n this value to disable panning on sample instances and audio streams, and play\n them without attentuation implied by panning support.\n ALLEGRO_AUDIO_PAN_NONE is different from a pan value of 0.0 (centered) because,\n when panning is enabled, we try to maintain a constant sound power level as a\n sample is panned from left to right. A sound coming out of one speaker should\n sound as loud as it does when split over two speakers. As a consequence, a\n sample with pan value 0.0 will be 3 dB softer than the original level.\n (Please correct us if this is wrong.)\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bp_\br_\bo_\bp_\bs_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_C\bCH\bHA\bAN\bNN\bNE\bEL\bL_\b_C\bCO\bON\bNF\bF *\b**\b**\b**\b**\b*\n enum ALLEGRO_CHANNEL_CONF\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Speaker configuration (mono, stereo, 2.1, etc).\n * ALLEGRO_CHANNEL_CONF_1\n * ALLEGRO_CHANNEL_CONF_2\n * ALLEGRO_CHANNEL_CONF_3\n * ALLEGRO_CHANNEL_CONF_4\n * ALLEGRO_CHANNEL_CONF_5_1\n * ALLEGRO_CHANNEL_CONF_6_1\n * ALLEGRO_CHANNEL_CONF_7_1\n+Examples:\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b__\bm_\bu_\bl_\bt_\bi_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_P\bPL\bLA\bAY\bYM\bMO\bOD\bDE\bE *\b**\b**\b**\b**\b*\n enum ALLEGRO_PLAYMODE\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sample and stream playback mode.\n * ALLEGRO_PLAYMODE_ONCE - the sample/stream is played from start to finish\n an then it stops.\n * ALLEGRO_PLAYMODE_LOOP - the sample/stream is played from start to finish\n@@ -1702,14 +2000,18 @@\n * ALLEGRO_PLAYMODE_LOOP_ONCE - just like ALLEGRO_PLAYMODE_ONCE, but\n respects the loop end point.\n * ALLEGRO_PLAYMODE_BIDIR - the sample is played from start to finish (or\n between the two loop points). When it reaches the end, it reverses the\n playback direction and plays until it reaches the beginning when it\n reverses the direction back to normal. This is mode is rarely supported\n for streams.\n+Examples:\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\bk_\bc_\bm_\b__\bd_\bi_\br_\be_\bc_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_A\bAU\bUD\bDI\bIO\bO_\b_E\bEV\bVE\bEN\bNT\bT_\b_T\bTY\bYP\bPE\bE *\b**\b**\b**\b**\b*\n enum ALLEGRO_AUDIO_EVENT_TYPE\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Events sent by _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be or\n _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bu_\bd_\bi_\bo_\b__\br_\be_\bc_\bo_\br_\bd_\be_\br_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be.\n *\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_E\bEV\bVE\bEN\bNT\bT_\b_A\bAU\bUD\bDI\bIO\bO_\b_S\bST\bTR\bRE\bEA\bAM\bM_\b_F\bFR\bRA\bAG\bGM\bME\bEN\bNT\bT *\b**\b**\b**\b*\n Sent when a stream fragment is ready to be filled in. See\n@@ -1729,21 +2031,28 @@\n Returns the (compiled) version of the addon, in the same format as\n _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bl_\bl_\be_\bg_\br_\bo_\b__\bv_\be_\br_\bs_\bi_\bo_\bn.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bau\bud\bdi\bio\bo_\b_d\bde\bep\bpt\bth\bh_\b_s\bsi\biz\bze\be *\b**\b**\b**\b**\b*\n size_t al_get_audio_depth_size(ALLEGRO_AUDIO_DEPTH depth)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the size of a sample, in bytes, for the given format. The format is one\n of the values listed under _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bA_\bU_\bD_\bI_\bO_\b__\bD_\bE_\bP_\bT_\bH.\n+Examples:\n+ * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_c\bch\bha\ban\bnn\bne\bel\bl_\b_c\bco\bou\bun\bnt\bt *\b**\b**\b**\b**\b*\n size_t al_get_channel_count(ALLEGRO_CHANNEL_CONF conf)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the number of channels for the given channel configuration, which is one\n of the values listed under _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bH_\bA_\bN_\bN_\bE_\bL_\b__\bC_\bO_\bN_\bF.\n+Examples:\n+ * _\be_\bx_\b__\ba_\bc_\bo_\bd_\be_\bc_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_f\bfi\bil\bll\bl_\b_s\bsi\bil\ble\ben\bnc\bce\be *\b**\b**\b**\b**\b*\n void al_fill_silence(void *buf, unsigned int samples,\n ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Fill a buffer with silence, for the given format and channel configuration. The\n buffer must have enough space for the given number of samples, and be properly\n aligned.\n Since: 5.1.8\n+Examples:\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/color.html", "source2": "./usr/share/doc/allegro5-doc/refman/color.html", "unified_diff": "@@ -272,23 +272,33 @@\n href=\"https://github.com/liballeg/allegro5/blob/master/addons/color/color.c#L480\">Source\n Code

    \n

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

    \n

    See also: al_color_cmyk_to_rgb, al_color_rgb_to_cmyk

    \n+

    Examples:

    \n+
      \n+
    • ex_color.cpp
      • \n+
    \n

    al_color_cmyk_to_rgb

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

    Source\n Code

    \n

    Convert CMYK values to RGB values.

    \n

    See also: al_color_cmyk, al_color_rgb_to_cmyk

    \n+

    Examples:

    \n+
      \n+
    • ex_color.cpp
      • \n+
    \n

    al_color_hsl

    \n 
    ALLEGRO_COLOR al_color_hsl(float h, float s, float l)
    \n

    Source\n Code

    \n

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

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

    See also: al_color_hsl_to_rgb, al_color_hsv

    \n+

    Examples:

    \n+
      \n+
    • ex_color.cpp
      • \n+
    • ex_clip.c
      • \n+
    • ex_palette.c
      • \n+
    \n

    al_color_hsl_to_rgb

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

    Source\n Code

    \n

    Convert values in HSL color model to RGB color model.

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

    See also: al_color_rgb_to_hsl, al_color_hsl, al_color_hsv_to_rgb

    \n+

    Examples:

    \n+
      \n+
    • ex_color.cpp
      • \n+
    • ex_palette.c
      • \n+
    \n

    al_color_hsv

    \n 
    ALLEGRO_COLOR al_color_hsv(float h, float s, float v)
    \n

    Source\n Code

    \n

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

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

    See also: al_color_hsv_to_rgb, al_color_hsl

    \n+

    Examples:

    \n+
      \n+
    • ex_font_multiline.cpp
      • \n+
    • ex_color.cpp
      • \n+
    • ex_multisample.c
      • \n+
    \n

    al_color_hsv_to_rgb

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

    Source\n Code

    \n

    Convert values in HSV color model to RGB color model.

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

    See also: al_color_rgb_to_hsv, al_color_hsv, al_color_hsl_to_rgb

    \n+

    Examples:

    \n+
      \n+
    • ex_color.cpp
      • \n+
    \n

    al_color_html

    \n 
    ALLEGRO_COLOR al_color_html(char const *string)
    \n

    Source\n Code

    \n

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

    Example:

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

    Now html will contain \u201c#ff0000\u201d.

    \n

    See also: al_color_html, al_color_html_to_rgb

    \n+

    Examples:

    \n+
      \n+
    • ex_color.cpp
      • \n+
    \n

    al_color_name

    \n 
    ALLEGRO_COLOR al_color_name(char const *name)
    \n

    Source\n Code

    \n

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

    \n

    See al_color_name_to_rgb for the\n list of names.

    \n+

    Examples:

    \n+
      \n+
    • ex_drag_and_drop.c
      • \n+
    • ex_multisample_target.c
      • \n+
    • ex_clip.c
      • \n+
    \n

    al_color_name_to_rgb

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

    Source\n Code

    \n

    Parameters:

    \n
      \n@@ -478,48 +532,72 @@\n M = 1 - G\n Y = 1 - B\n K = 0\n

      This function will instead find the representation with the maximal\n value for K and minimal color components.

      \n

      See also: al_color_cmyk, al_color_cmyk_to_rgb

      \n+

      Examples:

      \n+
        \n+
      • ex_color.cpp
        • \n+
      \n

      al_color_rgb_to_hsl

      \n 
      void al_color_rgb_to_hsl(float red, float green, float blue,\n    float *hue, float *saturation, float *lightness)
      \n

      Source\n Code

      \n

      Given an RGB triplet with components in the range 0..1, return the\n hue in degrees from 0..360 and saturation and lightness in the range\n 0..1.

      \n

      See also: al_color_hsl_to_rgb, al_color_hsl

      \n+

      Examples:

      \n+
        \n+
      • ex_color.cpp
        • \n+
      • ex_palette.c
        • \n+
      \n

      al_color_rgb_to_hsv

      \n 
      void al_color_rgb_to_hsv(float red, float green, float blue,\n    float *hue, float *saturation, float *value)
      \n

      Source\n Code

      \n

      Given an RGB triplet with components in the range 0..1, return the\n hue in degrees from 0..360 and saturation and value in the range\n 0..1.

      \n

      See also: al_color_hsv_to_rgb, al_color_hsv

      \n+

      Examples:

      \n+
        \n+
      • ex_color.cpp
        • \n+
      • ex_color_gradient.c
        • \n+
      \n

      al_color_rgb_to_name

      \n 
      char const *al_color_rgb_to_name(float r, float g, float b)
      \n

      Source\n Code

      \n

      Given an RGB triplet with components in the range 0..1, find a color\n name describing it approximately.

      \n

      See also: al_color_name_to_rgb, al_color_name

      \n+

      Examples:

      \n+
        \n+
      • ex_color.cpp
        • \n+
      \n

      al_color_rgb_to_xyz

      \n 
      void al_color_rgb_to_xyz(float red, float green, float blue,\n    float *x, float *y, float *z)
      \n

      Source\n Code

      \n

      Convert RGB values to XYZ color space.

      \n@@ -598,14 +676,19 @@\n

      Source\n Code

      \n

      Convert RGB values to L*a*b* color space.

      \n

      Since: 5.2.3

      \n

      See also: al_color_lab, al_color_lab_to_rgb

      \n+

      Examples:

      \n+
        \n+
      • ex_color_gradient.c
        • \n+
      \n

      al_color_lab

      \n 
      ALLEGRO_COLOR al_color_lab(float l, float a, float b)
      \n

      Source\n Code

      \n

      Return an ALLEGRO_COLOR\n structure from CIE L*a*b* values. The L* component corresponds to\n@@ -624,34 +707,51 @@\n -100 to +100. In that case divide all components by 100 before passing\n them to this function.

      \n \n

      Since: 5.2.3

      \n

      See also: al_color_lab_to_rgb, al_color_rgb_to_lab

      \n+

      Examples:

      \n+
        \n+
      • ex_color2.c
        • \n+
      • ex_color_gradient.c
        • \n+
      \n

      al_color_lab_to_rgb

      \n 
      void al_color_lab_to_rgb(float l, float a, float b,\n     float *red, float *green, float *blue)
      \n

      Source\n Code

      \n

      Convert CIE L*a*b* color values to RGB color space.

      \n

      Since: 5.2.3

      \n

      See also: al_color_lab, al_color_rgb_to_lab

      \n+

      Examples:

      \n+
        \n+
      • ex_color2.c
        • \n+
      \n

      al_color_rgb_to_lch

      \n 
      void al_color_rgb_to_lch(float red, float green, float blue,\n    float *l, float *c, float *h)
      \n

      Source\n Code

      \n

      Convert RGB values to CIE LCH color space.

      \n

      Since: 5.2.3

      \n

      See also: al_color_lch, al_color_lch_to_rgb

      \n+

      Examples:

      \n+
        \n+
      • ex_color.cpp
        • \n+
      \n

      al_color_lch

      \n 
      ALLEGRO_COLOR al_color_lch(float l, float c, float h)
      \n

      Source\n Code

      \n

      Return an ALLEGRO_COLOR\n structure from CIE LCH values. LCH colors are very similar to HSL, with\n@@ -663,24 +763,34 @@\n this:

      \n 
      C = sqrt(a * a + b * b)\n H = atan2(b, a)
      \n

      Since: 5.2.3

      \n

      See also: al_color_lch_to_rgb, al_color_rgb_to_lch

      \n+

      Examples:

      \n+
        \n+
      • ex_color.cpp
        • \n+
      \n

      al_color_lch_to_rgb

      \n 
      void al_color_lch_to_rgb(float l, float c, float h,\n     float *red, float *green, float *blue)
      \n

      Source\n Code

      \n

      Convert CIE LCH color values to RGB color space.

      \n

      Since: 5.2.3

      \n

      See also: al_color_lch, al_color_rgb_to_lch

      \n+

      Examples:

      \n+
        \n+
      • ex_color.cpp
        • \n+
      \n

      al_color_distance_ciede2000

      \n 
      double al_color_distance_ciede2000(ALLEGRO_COLOR color1,\n       ALLEGRO_COLOR color2) {
      \n

      Source\n Code

      \n

      This function computes the CIEDE2000 color difference between two RGB\n@@ -699,42 +809,62 @@\n

      \n

      Note: This function uses al_color_lab internally which defines\n the L component to be in the range 0..1 (and not 0..100 as is sometimes\n seen).

      \n
      \n

      Since: 5.2.3

      \n+

      Examples:

      \n+
        \n+
      • ex_color2.c
        • \n+
      \n

      al_color_rgb_to_yuv

      \n 
      void al_color_rgb_to_yuv(float red, float green, float blue,\n    float *y, float *u, float *v)
      \n

      Source\n Code

      \n

      Convert RGB values to YUV color space.

      \n

      See also: al_color_yuv, al_color_yuv_to_rgb

      \n+

      Examples:

      \n+
        \n+
      • ex_color.cpp
        • \n+
      \n

      al_color_yuv

      \n 
      ALLEGRO_COLOR al_color_yuv(float y, float u, float v)
      \n

      Source\n Code

      \n

      Return an ALLEGRO_COLOR\n structure from YUV values.

      \n

      See also: al_color_yuv_to_rgb, al_color_rgb_to_yuv

      \n+

      Examples:

      \n+
        \n+
      • ex_color.cpp
        • \n+
      \n

      al_color_yuv_to_rgb

      \n 
      void al_color_yuv_to_rgb(float y, float u, float v,\n     float *red, float *green, float *blue)
      \n

      Source\n Code

      \n

      Convert YUV color values to RGB color space.

      \n

      See also: al_color_yuv, al_color_rgb_to_yuv

      \n+

      Examples:

      \n+
        \n+
      • ex_color.cpp
        • \n+
      \n

      al_get_allegro_color_version

      \n 
      uint32_t al_get_allegro_color_version(void)
      \n

      Source\n Code

      \n

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

      \n@@ -751,14 +881,19 @@\n

      Source\n Code

      \n

      Convert RGB values to the Oklab color space.

      \n

      Since: 5.2.8

      \n

      See also: al_color_oklab, al_color_oklab_to_rgb

      \n+

      Examples:

      \n+
        \n+
      • ex_color_gradient.c
        • \n+
      \n

      al_color_oklab

      \n 
      ALLEGRO_COLOR al_color_oklab(float l, float a, float b)
      \n

      Source\n Code

      \n

      Return an ALLEGRO_COLOR\n structure from Oklab values. The L component corresponds to luminance\n@@ -770,14 +905,19 @@\n 0..1 range. You can check for that case with al_is_color_valid.

      \n \n

      Since: 5.2.8

      \n

      See also: al_color_oklab_to_rgb, al_color_rgb_to_oklab

      \n+

      Examples:

      \n+
        \n+
      • ex_color_gradient.c
        • \n+
      \n

      al_color_oklab_to_rgb

      \n 
      void al_color_oklab_to_rgb(float ol, float oa, float ob,\n     float *red, float *green, float *blue)
      \n

      Source\n Code

      \n

      Convert Oklab color values to RGB.

      \n@@ -792,14 +932,19 @@\n Code

      \n

      Convert gamma corrected sRGB values (i.e.\u00a0normal RGB) to linear sRGB\n space.

      \n

      Since: 5.2.8

      \n

      See also: al_color_linear,\n al_color_linear_to_rgb

      \n+

      Examples:

      \n+
        \n+
      • ex_color_gradient.c
        • \n+
      \n

      al_color_linear

      \n 
      ALLEGRO_COLOR al_color_linear(float r, float g, float b)
      \n

      Source\n Code

      \n

      Return an ALLEGRO_COLOR\n structure from linear sRGB values. Allegro RGB values are assumed to be\n@@ -818,14 +963,19 @@\n 

      ALLEGRO_COLOR gray = al_color_linear(0.216, 0.216, 0.216);\n char html[8];\n al_color_rgb_to_html(gray.r, gray.g, gray.b, html); // "#808080"
      \n

      Since: 5.2.8

      \n

      See also: al_color_linear_to_rgb, al_color_rgb_to_linear

      \n+

      Examples:

      \n+
        \n+
      • ex_color_gradient.c
        • \n+
      \n

      al_color_linear_to_rgb

      \n 
      void al_color_linear_to_rgb(float r, float g, float b,\n     float *red, float *green, float *blue)
      \n

      Source\n Code

      \n

      Convert linear sRGB color values to gamma corrected (i.e.\u00a0normal) RGB\n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -103,60 +103,77 @@\n output of the monitor will be less than half).\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_c\bcm\bmy\byk\bk *\b**\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_color_cmyk(float c, float m, float y, float k)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR structure from CMYK values (cyan, magenta, yellow,\n black).\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bc_\bm_\by_\bk_\b__\bt_\bo_\b__\br_\bg_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\br_\bg_\bb_\b__\bt_\bo_\b__\bc_\bm_\by_\bk\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_c\bcm\bmy\byk\bk_\b_t\bto\bo_\b_r\brg\bgb\bb *\b**\b**\b**\b**\b**\b*\n void al_color_cmyk_to_rgb(float cyan, float magenta, float yellow,\n float key, float *red, float *green, float *blue)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert CMYK values to RGB values.\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bc_\bm_\by_\bk, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\br_\bg_\bb_\b__\bt_\bo_\b__\bc_\bm_\by_\bk\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_h\bhs\bsl\bl *\b**\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_color_hsl(float h, float s, float l)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR structure from HSL (hue, saturation, lightness) values.\n Parameters:\n * hue - Color hue angle in the range 0..360\n * saturation - Color saturation in the range 0..1\n * lightness - Color lightness in the range 0..1\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bs_\bl_\b__\bt_\bo_\b__\br_\bg_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bs_\bv\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bc_\bl_\bi_\bp_\b._\bc\n+ * _\be_\bx_\b__\bp_\ba_\bl_\be_\bt_\bt_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_h\bhs\bsl\bl_\b_t\bto\bo_\b_r\brg\bgb\bb *\b**\b**\b**\b**\b**\b*\n void al_color_hsl_to_rgb(float hue, float saturation, float lightness,\n float *red, float *green, float *blue)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert values in HSL color model to RGB color model.\n Parameters:\n * hue - Color hue angle in the range 0..360\n * saturation - Color saturation in the range 0..1\n * lightness - Color lightness in the range 0..1\n * red, green, blue - returned RGB values in the range 0..1\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\br_\bg_\bb_\b__\bt_\bo_\b__\bh_\bs_\bl, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bs_\bl, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bs_\bv_\b__\bt_\bo_\b__\br_\bg_\bb\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bp_\ba_\bl_\be_\bt_\bt_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_h\bhs\bsv\bv *\b**\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_color_hsv(float h, float s, float v)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR structure from HSV (hue, saturation, value) values.\n Parameters:\n * hue - Color hue angle in the range 0..360\n * saturation - Color saturation in the range 0..1\n * value - Color value in the range 0..1\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bs_\bv_\b__\bt_\bo_\b__\br_\bg_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bs_\bl\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bm_\bu_\bl_\bt_\bi_\bs_\ba_\bm_\bp_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_h\bhs\bsv\bv_\b_t\bto\bo_\b_r\brg\bgb\bb *\b**\b**\b**\b**\b**\b*\n void al_color_hsv_to_rgb(float hue, float saturation, float value,\n float *red, float *green, float *blue)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert values in HSV color model to RGB color model.\n Parameters:\n * hue - Color hue angle in the range 0..360\n * saturation - Color saturation in the range 0..1\n * value - Color value in the range 0..1\n * red, green, blue - returned RGB values in the range 0..1\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\br_\bg_\bb_\b__\bt_\bo_\b__\bh_\bs_\bv, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bs_\bv, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bs_\bl_\b__\bt_\bo_\b__\br_\bg_\bb\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_h\bht\btm\bml\bl *\b**\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_color_html(char const *string)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Interprets an HTML-style hex number (e.g.\u00a0#00faff) as a color. The accepted\n format is the same as _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bt_\bm_\bl_\b__\bt_\bo_\b__\br_\bg_\bb.\n Returns the interpreted color, or al_map_rgba(0, 0, 0, 0) if the string could\n not be parsed.\n@@ -185,20 +202,26 @@\n * string - A pointer to a buffer of at least 8 bytes, into which the result\n will be written (including the NUL terminator).\n Example:\n char html[8];\n al_color_rgb_to_html(1, 0, 0, html);\n Now html will contain \u201c#ff0000\u201d.\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bt_\bm_\bl, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bt_\bm_\bl_\b__\bt_\bo_\b__\br_\bg_\bb\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_n\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_color_name(char const *name)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR with the given name. If the color is not found then\n black is returned.\n See _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bn_\ba_\bm_\be_\b__\bt_\bo_\b__\br_\bg_\bb for the list of names.\n+Examples:\n+ * _\be_\bx_\b__\bd_\br_\ba_\bg_\b__\ba_\bn_\bd_\b__\bd_\br_\bo_\bp_\b._\bc\n+ * _\be_\bx_\b__\bm_\bu_\bl_\bt_\bi_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bc_\bl_\bi_\bp_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_n\bna\bam\bme\be_\b_t\bto\bo_\b_r\brg\bgb\bb *\b**\b**\b**\b**\b**\b*\n bool al_color_name_to_rgb(char const *name, float *r, float *g, float *b)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Parameters:\n * name - The (lowercase) name of the color.\n * r, g, b - If one of the recognized color names below is passed, the\n corresponding RGB values in the range 0..1 are written.\n@@ -243,34 +266,44 @@\n C = 1 - R\n M = 1 - G\n Y = 1 - B\n K = 0\n This function will instead find the representation with the maximal value for K\n and minimal color components.\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bc_\bm_\by_\bk, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bc_\bm_\by_\bk_\b__\bt_\bo_\b__\br_\bg_\bb\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_r\brg\bgb\bb_\b_t\bto\bo_\b_h\bhs\bsl\bl *\b**\b**\b**\b**\b**\b*\n void al_color_rgb_to_hsl(float red, float green, float blue,\n float *hue, float *saturation, float *lightness)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Given an RGB triplet with components in the range 0..1, return the hue in\n degrees from 0..360 and saturation and lightness in the range 0..1.\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bs_\bl_\b__\bt_\bo_\b__\br_\bg_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bs_\bl\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bp_\ba_\bl_\be_\bt_\bt_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_r\brg\bgb\bb_\b_t\bto\bo_\b_h\bhs\bsv\bv *\b**\b**\b**\b**\b**\b*\n void al_color_rgb_to_hsv(float red, float green, float blue,\n float *hue, float *saturation, float *value)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Given an RGB triplet with components in the range 0..1, return the hue in\n degrees from 0..360 and saturation and value in the range 0..1.\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bs_\bv_\b__\bt_\bo_\b__\br_\bg_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bh_\bs_\bv\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b__\bg_\br_\ba_\bd_\bi_\be_\bn_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_r\brg\bgb\bb_\b_t\bto\bo_\b_n\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n char const *al_color_rgb_to_name(float r, float g, float b)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Given an RGB triplet with components in the range 0..1, find a color name\n describing it approximately.\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bn_\ba_\bm_\be_\b__\bt_\bo_\b__\br_\bg_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bn_\ba_\bm_\be\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_r\brg\bgb\bb_\b_t\bto\bo_\b_x\bxy\byz\bz *\b**\b**\b**\b**\b**\b*\n void al_color_rgb_to_xyz(float red, float green, float blue,\n float *x, float *y, float *z)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert RGB values to XYZ color space.\n Since: 5.2.3\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bx_\by_\bz, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bx_\by_\bz_\b__\bt_\bo_\b__\br_\bg_\bb\n@@ -321,14 +354,16 @@\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_r\brg\bgb\bb_\b_t\bto\bo_\b_l\bla\bab\bb *\b**\b**\b**\b**\b**\b*\n void al_color_rgb_to_lab(float red, float green, float blue,\n float *l, float *a, float *b)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert RGB values to L*a*b* color space.\n Since: 5.2.3\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bl_\ba_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bl_\ba_\bb_\b__\bt_\bo_\b__\br_\bg_\bb\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b__\bg_\br_\ba_\bd_\bi_\be_\bn_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_l\bla\bab\bb *\b**\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_color_lab(float l, float a, float b)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR structure from CIE L*a*b* values. The L* component\n corresponds to luminance from 0..1. The a* and b* components are in the range -\n 1..+1.\n N\bNo\bot\bte\be:\b:\n@@ -337,48 +372,59 @@\n 0..1 range. You can check for that case with _\ba_\bl_\b__\bi_\bs_\b__\bc_\bo_\bl_\bo_\br_\b__\bv_\ba_\bl_\bi_\bd.\n N\bNo\bot\bte\be:\b:\n In some literature the range of L* is 0 to 100 and a* and b* are from\n -100 to +100. In that case divide all components by 100 before\n passing them to this function.\n Since: 5.2.3\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bl_\ba_\bb_\b__\bt_\bo_\b__\br_\bg_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\br_\bg_\bb_\b__\bt_\bo_\b__\bl_\ba_\bb\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b2_\b._\bc\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b__\bg_\br_\ba_\bd_\bi_\be_\bn_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_l\bla\bab\bb_\b_t\bto\bo_\b_r\brg\bgb\bb *\b**\b**\b**\b**\b**\b*\n void al_color_lab_to_rgb(float l, float a, float b,\n float *red, float *green, float *blue)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert CIE L*a*b* color values to RGB color space.\n Since: 5.2.3\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bl_\ba_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\br_\bg_\bb_\b__\bt_\bo_\b__\bl_\ba_\bb\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b2_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_r\brg\bgb\bb_\b_t\bto\bo_\b_l\blc\bch\bh *\b**\b**\b**\b**\b**\b*\n void al_color_rgb_to_lch(float red, float green, float blue,\n float *l, float *c, float *h)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert RGB values to CIE LCH color space.\n Since: 5.2.3\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bl_\bc_\bh, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bl_\bc_\bh_\b__\bt_\bo_\b__\br_\bg_\bb\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_l\blc\bch\bh *\b**\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_color_lch(float l, float c, float h)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR structure from CIE LCH values. LCH colors are very\n similar to HSL, with the same meaning of L and H and C corresponding to S.\n However LCH is more visually uniform. Furthermore, this function expects the\n angle for H in radians and not in degree.\n The CIE LCH color space is a cylindrical representation of the L*a*b* color\n space. The L component is the same and C and H are computed like this:\n C = sqrt(a * a + b * b)\n H = atan2(b, a)\n Since: 5.2.3\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bl_\bc_\bh_\b__\bt_\bo_\b__\br_\bg_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\br_\bg_\bb_\b__\bt_\bo_\b__\bl_\bc_\bh\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_l\blc\bch\bh_\b_t\bto\bo_\b_r\brg\bgb\bb *\b**\b**\b**\b**\b**\b*\n void al_color_lch_to_rgb(float l, float c, float h,\n float *red, float *green, float *blue)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert CIE LCH color values to RGB color space.\n Since: 5.2.3\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bl_\bc_\bh, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\br_\bg_\bb_\b__\bt_\bo_\b__\bl_\bc_\bh\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_d\bdi\bis\bst\bta\ban\bnc\bce\be_\b_c\bci\bie\bed\bde\be2\b20\b00\b00\b0 *\b**\b**\b**\b**\b**\b*\n double al_color_distance_ciede2000(ALLEGRO_COLOR color1,\n ALLEGRO_COLOR color2) {\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This function computes the CIEDE2000 color difference between two RGB colors.\n This is a visually uniform color difference, unlike for example the RGB\n distance.\n@@ -390,31 +436,39 @@\n The CIEDE2000 formula contains some additional transformations to fix that.\n The returned color distance is roughly in the range 0 (identical color) to 1\n (completely different color) - but values greater than one are possible.\n Note: This function uses _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bl_\ba_\bb internally which defines the L\n component to be in the range 0..1 (and not 0..100 as is sometimes\n seen).\n Since: 5.2.3\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b2_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_r\brg\bgb\bb_\b_t\bto\bo_\b_y\byu\buv\bv *\b**\b**\b**\b**\b**\b*\n void al_color_rgb_to_yuv(float red, float green, float blue,\n float *y, float *u, float *v)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert RGB values to YUV color space.\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\by_\bu_\bv, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\by_\bu_\bv_\b__\bt_\bo_\b__\br_\bg_\bb\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_y\byu\buv\bv *\b**\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_color_yuv(float y, float u, float v)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR structure from YUV values.\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\by_\bu_\bv_\b__\bt_\bo_\b__\br_\bg_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\br_\bg_\bb_\b__\bt_\bo_\b__\by_\bu_\bv\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_y\byu\buv\bv_\b_t\bto\bo_\b_r\brg\bgb\bb *\b**\b**\b**\b**\b**\b*\n void al_color_yuv_to_rgb(float y, float u, float v,\n float *red, float *green, float *blue)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert YUV color values to RGB color space.\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\by_\bu_\bv, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\br_\bg_\bb_\b__\bt_\bo_\b__\by_\bu_\bv\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bal\bll\ble\beg\bgr\bro\bo_\b_c\bco\bol\blo\bor\br_\b_v\bve\ber\brs\bsi\bio\bon\bn *\b**\b**\b**\b**\b**\b*\n uint32_t al_get_allegro_color_version(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the (compiled) version of the addon, in the same format as\n _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bl_\bl_\be_\bg_\br_\bo_\b__\bv_\be_\br_\bs_\bi_\bo_\bn.\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_c\bco\bol\blo\bor\br_\b_v\bva\bal\bli\bid\bd *\b**\b**\b**\b**\b**\b*\n Source Code\n@@ -426,40 +480,46 @@\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_r\brg\bgb\bb_\b_t\bto\bo_\b_o\bok\bkl\bla\bab\bb *\b**\b**\b**\b**\b**\b*\n void al_color_rgb_to_oklab(float red, float green, float blue,\n float *ol, float *oa, float *ob)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert RGB values to the Oklab color space.\n Since: 5.2.8\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bo_\bk_\bl_\ba_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bo_\bk_\bl_\ba_\bb_\b__\bt_\bo_\b__\br_\bg_\bb\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b__\bg_\br_\ba_\bd_\bi_\be_\bn_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_o\bok\bkl\bla\bab\bb *\b**\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_color_oklab(float l, float a, float b)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR structure from Oklab values. The L component\n corresponds to luminance from 0..1. The a and b components are in the range -\n 1..+1.\n N\bNo\bot\bte\be:\b:\n The Oklab color space can represent more colors than are visible in\n sRGB and therefore conversion may result in RGB values outside of the\n 0..1 range. You can check for that case with _\ba_\bl_\b__\bi_\bs_\b__\bc_\bo_\bl_\bo_\br_\b__\bv_\ba_\bl_\bi_\bd.\n Since: 5.2.8\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bo_\bk_\bl_\ba_\bb_\b__\bt_\bo_\b__\br_\bg_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\br_\bg_\bb_\b__\bt_\bo_\b__\bo_\bk_\bl_\ba_\bb\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b__\bg_\br_\ba_\bd_\bi_\be_\bn_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_o\bok\bkl\bla\bab\bb_\b_t\bto\bo_\b_r\brg\bgb\bb *\b**\b**\b**\b**\b**\b*\n void al_color_oklab_to_rgb(float ol, float oa, float ob,\n float *red, float *green, float *blue)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert Oklab color values to RGB.\n Since: 5.2.8\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bo_\bk_\bl_\ba_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\br_\bg_\bb_\b__\bt_\bo_\b__\bo_\bk_\bl_\ba_\bb\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_r\brg\bgb\bb_\b_t\bto\bo_\b_l\bli\bin\bne\bea\bar\br *\b**\b**\b**\b**\b**\b*\n void al_color_rgb_to_linear(float red, float green, float blue,\n float *r, float *g, float *b)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert gamma corrected sRGB values (i.e.\u00a0normal RGB) to linear sRGB space.\n Since: 5.2.8\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bl_\bi_\bn_\be_\ba_\br, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bl_\bi_\bn_\be_\ba_\br_\b__\bt_\bo_\b__\br_\bg_\bb\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b__\bg_\br_\ba_\bd_\bi_\be_\bn_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_l\bli\bin\bne\bea\bar\br *\b**\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_color_linear(float r, float g, float b)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR structure from linear sRGB values. Allegro RGB values\n are assumed to be sRGB. The sRGB standard is in wide use by various display\n devices. It accounts for a standard gamma correction applied to RGB colors\n before they get displayed.\n@@ -472,14 +532,16 @@\n For some applications it may be useful to specify a color in linear sRGB\n components, in which case you can use this function. For example:\n ALLEGRO_COLOR gray = al_color_linear(0.216, 0.216, 0.216);\n char html[8];\n al_color_rgb_to_html(gray.r, gray.g, gray.b, html); // \"#808080\"\n Since: 5.2.8\n See also: _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\bl_\bi_\bn_\be_\ba_\br_\b__\bt_\bo_\b__\br_\bg_\bb, _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\br_\bg_\bb_\b__\bt_\bo_\b__\bl_\bi_\bn_\be_\ba_\br\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b__\bg_\br_\ba_\bd_\bi_\be_\bn_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bol\blo\bor\br_\b_l\bli\bin\bne\bea\bar\br_\b_t\bto\bo_\b_r\brg\bgb\bb *\b**\b**\b**\b**\b**\b*\n void al_color_linear_to_rgb(float r, float g, float b,\n float *red, float *green, float *blue)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert linear sRGB color values to gamma corrected (i.e.\u00a0normal) RGB values.\n Since: 5.2.8\n See also: [al_color_linera], _\ba_\bl_\b__\bc_\bo_\bl_\bo_\br_\b__\br_\bg_\bb_\b__\bt_\bo_\b__\bl_\bi_\bn_\be_\ba_\br\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/config.html", "source2": "./usr/share/doc/allegro5-doc/refman/config.html", "unified_diff": "@@ -258,36 +258,55 @@\n al_destroy_config(cfg);\n

      ALLEGRO_CONFIG

      \n 
      typedef struct ALLEGRO_CONFIG ALLEGRO_CONFIG;
      \n

      Source\n Code

      \n

      An abstract configuration structure.

      \n+

      Examples:

      \n+
        \n+
      • ex_config.c
        • \n+
      • ex_vsync.c
        • \n+
      • ex_stream_seek.c
        • \n+
      \n

      ALLEGRO_CONFIG_SECTION

      \n 
      typedef struct ALLEGRO_CONFIG_SECTION ALLEGRO_CONFIG_SECTION;
      \n

      Source\n Code

      \n

      An opaque structure used for iterating across sections in a\n configuration structure.

      \n

      See also: al_get_first_config_section,\n al_get_next_config_section

      \n+

      Examples:

      \n+
        \n+
      • ex_config.c
        • \n+
      \n

      ALLEGRO_CONFIG_ENTRY

      \n 
      typedef struct ALLEGRO_CONFIG_ENTRY ALLEGRO_CONFIG_ENTRY;
      \n

      Source\n Code

      \n

      An opaque structure used for iterating across entries in a\n configuration section.

      \n

      See also: al_get_first_config_entry,\n al_get_next_config_entry

      \n+

      Examples:

      \n+
        \n+
      • ex_config.c
        • \n+
      \n

      al_create_config

      \n 
      ALLEGRO_CONFIG *al_create_config(void)
      \n

      Source\n Code

      \n

      Create an empty configuration structure.

      \n

      See also: al_create_config, al_load_config_file

      \n

      Examples:

      \n
        \n
      • ex_config.c
        • \n
      • ex_stream_seek.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_vsync.c#L122\">ex_vsync.c\n
      • ex_ttf.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_stream_seek.c#L273\">ex_stream_seek.c\n
      \n

      al_load_config_file

      \n 
      ALLEGRO_CONFIG *al_load_config_file(const char *filename)
      \n

      Source\n Code

      \n

      Read a configuration file from disk. Returns NULL on error. The\n@@ -333,17 +352,17 @@\n href=\"config.html#al_load_config_file_f\">al_load_config_file_f, al_save_config_file

      \n

      Examples:

      \n
        \n
      • ex_config.c
        • \n
      • ex_stream_seek.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_vsync.c#L102\">ex_vsync.c\n
      • ex_ttf.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_stream_seek.c#L254\">ex_stream_seek.c\n
      \n

      al_load_config_file_f

      \n 
      ALLEGRO_CONFIG *al_load_config_file_f(ALLEGRO_FILE *file)
      \n

      Source\n Code

      \n

      Read a configuration file from an already open file.

      \n@@ -429,17 +448,17 @@\n

      See also: al_set_config_value

      \n

      Examples:

      \n
        \n
      • ex_config.c
        • \n
      • ex_stream_seek.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_vsync.c#L18\">ex_vsync.c\n
      • ex_ttf.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_stream_seek.c#L256\">ex_stream_seek.c\n
      \n

      al_set_config_value

      \n 
      void al_set_config_value(ALLEGRO_CONFIG *config,\n    const char *section, const char *key, const char *value)
      \n

      Source\n Code

      \n@@ -454,17 +473,17 @@\n

      See also: al_get_config_value

      \n

      Examples:

      \n
        \n
      • ex_config.c
        • \n
      • ex_vsync.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_resize2.c#L35\">ex_resize2.c\n
      • ex_camera.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_vsync.c#L22\">ex_vsync.c\n
      \n

      al_remove_config_key

      \n 
      bool al_remove_config_key(ALLEGRO_CONFIG *config, char const *section,\n    char const *key)
      \n

      Source\n Code

      \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -103,26 +103,34 @@\n printf(\"%s\\n\", al_get_config_value(cfg, \"weapon 1\", \"damage\")); /* Prints: 503\n */\n al_destroy_config(cfg);\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_C\bCO\bON\bNF\bFI\bIG\bG *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_CONFIG ALLEGRO_CONFIG;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An abstract configuration structure.\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b._\bc\n+ * _\be_\bx_\b__\bv_\bs_\by_\bn_\bc_\b._\bc\n+ * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\be_\be_\bk_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_C\bCO\bON\bNF\bFI\bIG\bG_\b_S\bSE\bEC\bCT\bTI\bIO\bON\bN *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_CONFIG_SECTION ALLEGRO_CONFIG_SECTION;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An opaque structure used for iterating across sections in a configuration\n structure.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bf_\bi_\br_\bs_\bt_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b__\bs_\be_\bc_\bt_\bi_\bo_\bn, _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\be_\bx_\bt_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b__\bs_\be_\bc_\bt_\bi_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_C\bCO\bON\bNF\bFI\bIG\bG_\b_E\bEN\bNT\bTR\bRY\bY *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_CONFIG_ENTRY ALLEGRO_CONFIG_ENTRY;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An opaque structure used for iterating across entries in a configuration\n section.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bf_\bi_\br_\bs_\bt_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b__\be_\bn_\bt_\br_\by, _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\be_\bx_\bt_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b__\be_\bn_\bt_\br_\by\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_c\bco\bon\bnf\bfi\big\bg *\b**\b**\b**\b**\b**\b*\n ALLEGRO_CONFIG *al_create_config(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create an empty configuration structure.\n See also: _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b__\bf_\bi_\bl_\be, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bc_\bo_\bn_\bf_\bi_\bg\n Examples:\n * _\be_\bx_\b__\bv_\bs_\by_\bn_\bc_\b._\bc\n@@ -132,26 +140,26 @@\n void al_destroy_config(ALLEGRO_CONFIG *config)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Free the resources used by a configuration structure. Does nothing if passed\n NULL.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bc_\bo_\bn_\bf_\bi_\bg, _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b__\bf_\bi_\bl_\be\n Examples:\n * _\be_\bx_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b._\bc\n+ * _\be_\bx_\b__\bv_\bs_\by_\bn_\bc_\b._\bc\n * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\be_\be_\bk_\b._\bc\n- * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boa\bad\bd_\b_c\bco\bon\bnf\bfi\big\bg_\b_f\bfi\bil\ble\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_CONFIG *al_load_config_file(const char *filename)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Read a configuration file from disk. Returns NULL on error. The configuration\n structure should be destroyed with _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bc_\bo_\bn_\bf_\bi_\bg.\n See also: _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b__\bf_\bi_\bl_\be_\b__\bf, _\ba_\bl_\b__\bs_\ba_\bv_\be_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b__\bf_\bi_\bl_\be\n Examples:\n * _\be_\bx_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b._\bc\n+ * _\be_\bx_\b__\bv_\bs_\by_\bn_\bc_\b._\bc\n * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\be_\be_\bk_\b._\bc\n- * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boa\bad\bd_\b_c\bco\bon\bnf\bfi\big\bg_\b_f\bfi\bil\ble\be_\b_f\bf *\b**\b**\b**\b**\b**\b*\n ALLEGRO_CONFIG *al_load_config_file_f(ALLEGRO_FILE *file)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Read a configuration file from an already open file.\n Returns NULL on error. The configuration structure should be destroyed with\n _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bc_\bo_\bn_\bf_\bi_\bg. The file remains open afterwards.\n See also: _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b__\bf_\bi_\bl_\be\n@@ -201,32 +209,32 @@\n Gets a pointer to an internal character buffer that will only remain valid as\n long as the ALLEGRO_CONFIG structure is not destroyed. Copy the value if you\n need a copy. The section can be NULL or \u201c\u201d for the global section. Returns NULL\n if the section or key do not exist.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b__\bv_\ba_\bl_\bu_\be\n Examples:\n * _\be_\bx_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b._\bc\n+ * _\be_\bx_\b__\bv_\bs_\by_\bn_\bc_\b._\bc\n * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bs_\be_\be_\bk_\b._\bc\n- * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_c\bco\bon\bnf\bfi\big\bg_\b_v\bva\bal\blu\bue\be *\b**\b**\b**\b**\b**\b*\n void al_set_config_value(ALLEGRO_CONFIG *config,\n const char *section, const char *key, const char *value)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set a value in a section of a configuration. If the section doesn\u2019t yet exist,\n it will be created. If a value already existed for the given key, it will be\n overwritten. The section can be NULL or \u201c\u201d for the global section.\n For consistency with the on-disk format of config files, any leading and\n trailing whitespace will be stripped from the value. If you have significant\n whitespace you wish to preserve, you should add your own quote characters and\n remove them when reading the values back in.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b__\bv_\ba_\bl_\bu_\be\n Examples:\n * _\be_\bx_\b__\bc_\bo_\bn_\bf_\bi_\bg_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bs_\bi_\bz_\be_\b2_\b._\bc\n * _\be_\bx_\b__\bv_\bs_\by_\bn_\bc_\b._\bc\n- * _\be_\bx_\b__\bc_\ba_\bm_\be_\br_\ba_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bem\bmo\bov\bve\be_\b_c\bco\bon\bnf\bfi\big\bg_\b_k\bke\bey\by *\b**\b**\b**\b**\b**\b*\n bool al_remove_config_key(ALLEGRO_CONFIG *config, char const *section,\n char const *key)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Remove a key and its associated value in a section of a configuration.\n Returns true if the entry was removed, or false if the entry did not exist.\n Since: 5.1.5\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/direct3d.html", "source2": "./usr/share/doc/allegro5-doc/refman/direct3d.html", "unified_diff": "@@ -201,14 +201,19 @@\n 
      LPDIRECT3DDEVICE9 al_get_d3d_device(ALLEGRO_DISPLAY *display)
      \n

      Source\n Code

      \n

      Returns the Direct3D device of the display. The return value is\n undefined if the display was not created with the Direct3D flag.

      \n

      Returns: A pointer to the Direct3D device.

      \n+

      Examples:

      \n+
        \n+
      • ex_d3d.cpp
        • \n+
      \n

      al_get_d3d_system_texture

      \n 
      LPDIRECT3DTEXTURE9 al_get_d3d_system_texture(ALLEGRO_BITMAP *bitmap)
      \n

      Source\n Code

      \n

      Returns the system texture (stored with the D3DPOOL_SYSTEMMEM flags).\n This texture is used for the render-to-texture feature set.

      \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -57,14 +57,16 @@\n #include \n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_d\bd3\b3d\bd_\b_d\bde\bev\bvi\bic\bce\be *\b**\b**\b**\b**\b**\b*\n LPDIRECT3DDEVICE9 al_get_d3d_device(ALLEGRO_DISPLAY *display)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the Direct3D device of the display. The return value is undefined if\n the display was not created with the Direct3D flag.\n R\bRe\bet\btu\bur\brn\bns\bs:\b: A pointer to the Direct3D device.\n+Examples:\n+ * _\be_\bx_\b__\bd_\b3_\bd_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_d\bd3\b3d\bd_\b_s\bsy\bys\bst\bte\bem\bm_\b_t\bte\bex\bxt\btu\bur\bre\be *\b**\b**\b**\b**\b**\b*\n LPDIRECT3DTEXTURE9 al_get_d3d_system_texture(ALLEGRO_BITMAP *bitmap)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the system texture (stored with the D3DPOOL_SYSTEMMEM flags). This\n texture is used for the render-to-texture feature set.\n R\bRe\bet\btu\bur\brn\bns\bs:\b: A pointer to the Direct3D system texture.\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_d\bd3\b3d\bd_\b_v\bvi\bid\bde\beo\bo_\b_t\bte\bex\bxt\btu\bur\bre\be *\b**\b**\b**\b**\b**\b*\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/display.html", "source2": "./usr/share/doc/allegro5-doc/refman/display.html", "unified_diff": "@@ -345,14 +345,23 @@\n

      Display creation

      \n

      ALLEGRO_DISPLAY

      \n 
      typedef struct ALLEGRO_DISPLAY ALLEGRO_DISPLAY;
      \n

      Source\n Code

      \n

      An opaque type representing an open display or window.

      \n+

      Examples:

      \n+
        \n+
      • ex_monitorinfo.c
        • \n+
      • ex_d3d.cpp
        • \n+
      • ex_keyboard_focus.c
        • \n+
      \n

      al_create_display

      \n 
      ALLEGRO_DISPLAY *al_create_display(int w, int h)
      \n

      Source\n Code

      \n

      Create a display, or window, with the specified dimensions. The\n parameters of the display are determined by the last calls to\n@@ -375,19 +384,19 @@\n al_set_new_window_title\n al_set_window_position

      \n

      Examples:

      \n
        \n
      • ex_audio_props.cpp
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_d3d.cpp#L37\">ex_d3d.cpp\n
      • ex_keyboard_focus.c
        • \n
      • ex_d3d.cpp
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_mouse_focus.c#L48\">ex_mouse_focus.c\n
      \n

      al_destroy_display

      \n 
      void al_destroy_display(ALLEGRO_DISPLAY *display)
      \n

      Source\n Code

      \n

      Destroy a display.

      \n@@ -402,15 +411,15 @@\n

      Examples:

      \n
        \n
      • ex_d3d.cpp
        • \n
      • ex_mouse_focus.c
        • \n
      • ex_audio_simple.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_opengl.c#L173\">ex_opengl.c\n
      \n

      al_get_new_display_flags

      \n 
      int al_get_new_display_flags(void)
      \n

      Source\n Code

      \n

      Get the display flags to be used when creating new displays on the\n@@ -564,14 +573,23 @@\n \n

      0 can be used for default values.

      \n

      See also: al_set_new_display_option,\n al_get_display_option,\n al_set_display_option

      \n+

      Examples:

      \n+
        \n+
      • ex_d3d.cpp
        • \n+
      • ex_opengl.c
        • \n+
      • ex_opengl_pixel_shader.c
        • \n+
      \n

      al_get_new_display_option

      \n 
      int al_get_new_display_option(int option, int *importance)
      \n

      Source\n Code

      \n

      Retrieve an extra display setting which was previously set with al_set_new_display_option.

      \n@@ -773,17 +791,17 @@\n al_get_display_option

      \n

      Examples:

      \n
        \n
      • ex_d3d.cpp
        • \n
      • ex_color_gradient.c
        • \n-
      • ex_glext.c
        • \n+
      • ex_expose.c
        • \n
      \n

      al_reset_new_display_options

      \n 
      void al_reset_new_display_options(void)
      \n

      Source\n Code

      \n

      This undoes any previous call to Sets where the top left pixel of the client area of newly created\n windows (non-fullscreen) will be on screen, for displays created by the\n calling thread. Negative values are allowed on some multihead\n systems.

      \n

      To reset to the default behaviour, pass (INT_MAX, INT_MAX).

      \n

      See also: al_get_new_window_position

      \n+

      Examples:

      \n+
        \n+
      • ex_windows.c
        • \n+
      \n al_get_new_display_refresh_rate\n 
      int al_get_new_display_refresh_rate(void)
      \n

      Source\n Code

      \n

      Get the requested refresh rate to be used when creating new displays\n@@ -832,14 +855,19 @@\n list of modes with refresh rates can be found with al_get_num_display_modes\n and al_get_display_mode.

      \n

      The default setting is zero (don\u2019t care).

      \n

      See also: al_get_new_display_refresh_rate

      \n+

      Examples:

      \n+
        \n+
      • ex_vsync.c
        • \n+
      \n

      al_get_new_display_adapter

      \n 
      int al_get_new_display_adapter(void)
      \n

      Source\n Code

      \n

      Gets the video adapter index where new displays will be created by\n the calling thread, if previously set with al_get_monitor_info.

      \n

      To return to the default behaviour, pass\n ALLEGRO_DEFAULT_DISPLAY_ADAPTER.

      \n

      See also: al_get_num_video_adapters,\n al_get_monitor_info

      \n+

      Examples:

      \n+
        \n+
      • ex_monitorinfo.c
        • \n+
      • ex_winfull.c
        • \n+
      • ex_dualies.c
        • \n+
      \n

      Display operations

      \n

      al_get_display_event_source

      \n 
      ALLEGRO_EVENT_SOURCE *al_get_display_event_source(ALLEGRO_DISPLAY *display)
      \n

      Source\n Code

      \n

      Retrieve the associated event source. See the documentation on\n events for a list of the events displays will generate.

      \n

      Examples:

      \n
        \n
      • ex_joystick_hotplugging.c
        • \n-
      • ex_keyboard_events.c
        • \n
      • ex_audio_simple.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_opengl.c#L146\">ex_opengl.c\n+
      • ex_touch_input.c
        • \n
      \n

      al_get_backbuffer

      \n 
      ALLEGRO_BITMAP *al_get_backbuffer(ALLEGRO_DISPLAY *display)
      \n

      Source\n Code

      \n

      Return a special bitmap representing the back-buffer of the\n@@ -901,19 +938,19 @@\n the backbuffer into a temporary bitmap (via the al_draw_bitmap and al_draw_bitmap_region),\n and then use that temporary bitmap as the source bitmap.

      \n

      Examples:

      \n
        \n
      • ex_shader_target.c
        • \n-
      • ex_drawpixels.c
        • \n
      • ex_blend_test.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_multiwin.c#L102\">ex_multiwin.c\n+
      • ex_blend_target.c
        • \n
      \n

      al_flip_display

      \n 
      void al_flip_display(void)
      \n

      Source\n Code

      \n

      Copies or updates the front and back buffers so that what has been\n@@ -945,19 +982,19 @@\n

      See also: al_set_new_display_flags,\n al_set_new_display_option

      \n

      Examples:

      \n
        \n
      • ex_audio_props.cpp
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_d3d.cpp#L105\">ex_d3d.cpp\n
      • ex_keyboard_focus.c
        • \n
      • ex_d3d.cpp
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_mouse_focus.c#L20\">ex_mouse_focus.c\n
      \n

      al_update_display_region

      \n 
      void al_update_display_region(int x, int y, int width, int height)
      \n

      Source\n Code

      \n

      Does the same as Gets the width of the display. This is like SCREEN_W in Allegro\n 4.x.

      \n

      See also: al_get_display_height

      \n

      Examples:

      \n
        \n
      • ex_font_multiline.cpp
        • \n-
      • ex_font_justify.cpp
        • \n
      • nihgui.cpp
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_bitmap.c#L135\">ex_bitmap.c\n+
      • ex_ogre3d.cpp
        • \n
      \n

      al_get_display_height

      \n 
      int al_get_display_height(ALLEGRO_DISPLAY *display)
      \n

      Source\n Code

      \n

      Gets the height of the display. This is like SCREEN_H in Allegro\n 4.x.

      \n

      See also: al_get_display_width

      \n

      Examples:

      \n
        \n
      • ex_audio_chain.cpp
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_ogre3d.cpp#L108\">ex_ogre3d.cpp\n
      • nihgui.cpp
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_fs_resize.c#L102\">ex_fs_resize.c\n
      • ex_color_gradient.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_window_maximized.c#L101\">ex_window_maximized.c\n
      \n

      al_resize_display

      \n 
      bool al_resize_display(ALLEGRO_DISPLAY *display, int width, int height)
      \n

      Source\n Code

      \n

      Resize the display. Returns true on success, or false on error. This\n@@ -1039,17 +1076,17 @@\n

      See also: al_acknowledge_resize

      \n

      Examples:

      \n
        \n
      • ex_resize.c
        • \n
      • ex_mouse_events.c
        • \n-
      • ex_fs_resize.c
        • \n+
      • ex_fs_window.c
        • \n
      \n

      al_acknowledge_resize

      \n 
      bool al_acknowledge_resize(ALLEGRO_DISPLAY *display)
      \n

      Source\n Code

      \n

      When the user receives a \n

      See also: al_resize_display, ALLEGRO_EVENT

      \n

      Examples:

      \n
        \n
      • ex_display_events.c
        • \n-
      • ex_touch_input.c
        • \n
      • ex_color_gradient.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_multiwin.c#L73\">ex_multiwin.c\n+
      • ex_display_events.c
        • \n
      \n

      al_get_window_position

      \n 
      void al_get_window_position(ALLEGRO_DISPLAY *display, int *x, int *y)
      \n

      Source\n Code

      \n

      Gets the position of a non-fullscreen display.

      \n@@ -1247,17 +1284,17 @@\n href=\"display.html#al_set_new_display_flags\">al_set_new_display_flags,\n al_set_display_flag

      \n

      Examples:

      \n
        \n
      • ex_noframe.c
        • \n
      • ex_display_options.c
        • \n-
      • ex_fs_window.c
        • \n+
      • ex_resize2.c
        • \n
      \n

      al_set_display_flag

      \n 
      bool al_set_display_flag(ALLEGRO_DISPLAY *display, int flag, bool onoff)
      \n

      Source\n Code

      \n

      Enable or disable one of the display flags. The flags are the same as\n@@ -1278,17 +1315,17 @@\n href=\"display.html#al_set_new_display_flags\">al_set_new_display_flags,\n al_get_display_flags

      \n

      Examples:

      \n
        \n
      • ex_noframe.c
        • \n
      • ex_video.c
        • \n-
      • ex_fs_window.c
        • \n+
      • ex_resize2.c
        • \n
      \n

      al_get_display_option

      \n 
      int al_get_display_option(ALLEGRO_DISPLAY *display, int option)
      \n

      Source\n Code

      \n

      Return an extra display setting of the display.

      \n@@ -1297,15 +1334,15 @@\n

      Examples:

      \n
        \n
      • ex_glext.c
        • \n
      • ex_gldepth.c
        • \n
      • ex_display_options.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_multisample.c#L160\">ex_multisample.c\n
      \n

      al_set_display_option

      \n 
      void al_set_display_option(ALLEGRO_DISPLAY *display, int option, int value)
      \n

      Source\n Code

      \n

      Change an option that was previously set for a display. After\n@@ -1376,19 +1413,19 @@\n

      Set the title on a display.

      \n

      See also: al_set_display_icon, al_set_display_icons

      \n

      Examples:

      \n
        \n
      • ex_synth.cpp
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_icon.c#L49\">ex_icon.c\n
      • ex_window_title.c
        • \n
      • ex_icon.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_bitmap.c#L72\">ex_bitmap.c\n
      \n

      al_set_new_window_title

      \n 
      void al_set_new_window_title(const char *title)
      \n

      Source\n Code

      \n

      Set the title that will be used when a new display is created.\n@@ -1398,14 +1435,21 @@\n this.

      \n

      See also: al_set_window_title, al_get_new_window_title,\n al_create_display, ALLEGRO_NEW_WINDOW_TITLE_MAX_SIZE

      \n

      Since: 5.1.12

      \n+

      Examples:

      \n+
        \n+
      • ex_window_title.c
        • \n+
      • ex_windows.c
        • \n+
      \n ALLEGRO_NEW_WINDOW_TITLE_MAX_SIZE\n 
      #define ALLEGRO_NEW_WINDOW_TITLE_MAX_SIZE 255
      \n

      Source\n Code

      \n

      This is the maximum size of the title that can be set with \n

      See also: al_set_window_title, al_set_new_window_title,\n al_create_display

      \n

      Since: 5.1.12

      \n+

      Examples:

      \n+
        \n+
      • ex_window_title.c
        • \n+
      \n

      al_set_display_icon

      \n 
      void al_set_display_icon(ALLEGRO_DISPLAY *display, ALLEGRO_BITMAP *icon)
      \n

      Source\n Code

      \n

      Changes the icon associated with the display (window). Same as al_set_display_icons with\n one icon.

      \n

      See also: al_set_display_icons, al_set_window_title

      \n

      Examples:

      \n
        \n
      • ex_icon.c
        • \n-
      • ex_icon2.c
        • \n+
      • ex_icon.c
        • \n
      \n

      al_set_display_icons

      \n 
      void al_set_display_icons(ALLEGRO_DISPLAY *display,\n    int num_icons, ALLEGRO_BITMAP *icons[])
      \n

      Source\n Code

      \n@@ -1488,17 +1537,17 @@\n

      See also: ALLEGRO_EVENT_DISPLAY_HALT_DRAWING

      \n

      Examples:

      \n
        \n
      • ex_touch_input.c
        • \n
      • ex_vertex_buffer.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_resize2.c#L89\">ex_resize2.c\n
      • ex_depth_mask.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_android.c#L199\">ex_android.c\n
      \n al_acknowledge_drawing_resume\n 
      void al_acknowledge_drawing_resume(ALLEGRO_DISPLAY *display)
      \n

      Source\n Code

      \n@@ -1509,28 +1558,33 @@\n

      See also: ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING

      \n

      Examples:

      \n
        \n
      • ex_touch_input.c
        • \n
      • ex_camera.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_resize2.c#L93\">ex_resize2.c\n
      • ex_native_filechooser.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_android.c#L205\">ex_android.c\n
      \n

      Screensaver

      \n

      al_inhibit_screensaver

      \n 
      bool al_inhibit_screensaver(bool inhibit)
      \n

      Source\n Code

      \n

      This function allows the user to stop the system screensaver from\n starting up if true is passed, or resets the system back to the default\n state (the state at program start) if false is passed. It returns true\n if the state was set successfully, otherwise false.

      \n+

      Examples:

      \n+
        \n+
      • ex_disable_screensaver.c
        • \n+
      \n

      Clipboard

      \n

      With the clipboard API of Allegro, text can be copied from and to the\n clipboard. Currentlly, only UTF8 encoded text is supported. It currently\n works on Linux, Windows, OSX, Android and IOS.

      \n

      al_get_clipboard_text

      \n 
      char *al_get_clipboard_text(ALLEGRO_DISPLAY *display)
      \n

      any.source field tells you which\n event source generated that particular event. The\n any.timestamp field tells you when the event was generated.\n The time is referenced to the same starting point as al_get_time.

      \n

      Each event is of one of the following types, with the usable fields\n given.

      \n+

      Examples:

      \n+
        \n+
      • ex_inject_events.c
        • \n+
      • ex_enet_server.c
        • \n+
      • ex_timer_pause.c
        • \n+
      \n

      ALLEGRO_EVENT_JOYSTICK_AXIS

      \n

      A joystick axis value changed.

      \n
      \n
      joystick.id (ALLEGRO_JOYSTICK *)
      \n
      \n The joystick which generated the event. This is not the same as the\n event source joystick.source.\n@@ -1049,40 +1058,63 @@\n Please see the documentation for ALLEGRO_GET_EVENT_TYPE for\n the rules you should follow when assigning identifiers.

      \n

      See also: al_emit_user_event, ALLEGRO_GET_EVENT_TYPE, al_init_user_event_source

      \n+

      Examples:

      \n+
        \n+
      • ex_user_events.c
        • \n+
      \n

      ALLEGRO_EVENT_QUEUE

      \n 
      typedef struct ALLEGRO_EVENT_QUEUE ALLEGRO_EVENT_QUEUE;
      \n

      Source\n Code

      \n

      An event queue holds events that have been generated by event sources\n that are registered with the queue. Events are stored in the order they\n are generated. Access is in a strictly FIFO (first-in-first-out)\n order.

      \n

      See also: al_create_event_queue, al_destroy_event_queue

      \n+

      Examples:

      \n+
        \n+
      • ex_inject_events.c
        • \n+
      • ex_enet_server.c
        • \n+
      • ex_timer_pause.c
        • \n+
      \n

      ALLEGRO_EVENT_SOURCE

      \n 
      typedef struct ALLEGRO_EVENT_SOURCE ALLEGRO_EVENT_SOURCE;
      \n

      Source\n Code

      \n

      An event source is any object which can generate events. For example,\n an ALLEGRO_DISPLAY can generate events, and you can get the\n ALLEGRO_EVENT_SOURCE pointer from an ALLEGRO_DISPLAY with al_get_display_event_source.

      \n

      You may create your own \u201cuser\u201d event sources that emit custom\n events.

      \n

      See also: ALLEGRO_EVENT, al_init_user_event_source,\n al_emit_user_event

      \n+

      Examples:

      \n+
        \n+
      • ex_inject_events.c
        • \n+
      • ex_user_events.c
        • \n+
      • nihgui.cpp
        • \n+
      \n

      ALLEGRO_EVENT_TYPE

      \n 
      typedef unsigned int ALLEGRO_EVENT_TYPE;
      \n

      Source\n Code

      \n

      An integer used to distinguish between different types of events.

      \n

      See also: ALLEGRO_EVENT, 

      #define ALLEGRO_GET_EVENT_TYPE(a, b, c, d)   AL_ID(a, b, c, d)
      \n

      Source\n Code

      \n

      Make an event type identifier, which is a 32-bit integer. Usually,\n but not necessarily, this will be made from four 8-bit character codes,\n for example:

      \n-
      #defin  MY_EVENT_TYPE   ALLEGRO_GET_EVENT_TYPE('M','I','N','E')
      \n+
      Examples:\n+\n+* [ex_user_events.c](https://github.com/liballeg/allegro5/blob/master/examples/ex_user_events.c#L10)\n+* [ex_native_filechooser.c](https://github.com/liballeg/allegro5/blob/master/examples/ex_native_filechooser.c#L24)\n+\n+#defin  MY_EVENT_TYPE   ALLEGRO_GET_EVENT_TYPE('M','I','N','E')
      \n

      IDs less than 1024 are reserved for Allegro or its addons. Don\u2019t use\n anything lower than ALLEGRO_GET_EVENT_TYPE(0, 0, 4, 0).

      \n

      You should try to make your IDs unique so they don\u2019t clash with any\n 3rd party code you may be using. Be creative. Numbering from 1024 is not\n creative.

      \n

      If you need multiple identifiers, you could define them like\n this:

      \n@@ -1136,19 +1173,19 @@\n

      See also: al_register_event_source,\n al_destroy_event_queue,\n ALLEGRO_EVENT_QUEUE

      \n

      Examples:

      \n
        \n
      • ex_enet_server.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_inject_events.c#L33\">ex_inject_events.c\n
      • ex_saw.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_enet_server.c#L213\">ex_enet_server.c\n
      • ex_stream_file.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_timer_pause.c#L36\">ex_timer_pause.c\n
      \n

      al_destroy_event_queue

      \n 
      void al_destroy_event_queue(ALLEGRO_EVENT_QUEUE *queue)
      \n

      Source\n Code

      \n

      Destroy the event queue specified. All event sources currently\n@@ -1158,19 +1195,19 @@\n 5.2.9)

      \n

      See also: al_create_event_queue, ALLEGRO_EVENT_QUEUE

      \n

      Examples:

      \n
        \n
      • ex_saw.c
        • \n-
      • ex_stream_file.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_inject_events.c#L66\">ex_inject_events.c\n
      • ex_timer_pause.c
        • \n+
      • common.c
        • \n
      \n

      al_register_event_source

      \n 
      void al_register_event_source(ALLEGRO_EVENT_QUEUE *queue,\n    ALLEGRO_EVENT_SOURCE *source)
      \n

      Source\n Code

      \n@@ -1180,19 +1217,19 @@\n more than once does nothing.

      \n

      See also: al_unregister_event_source,\n ALLEGRO_EVENT_SOURCE

      \n

      Examples:

      \n
        \n
      • ex_enet_server.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_inject_events.c#L34\">ex_inject_events.c\n
      • ex_saw.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_enet_server.c#L215\">ex_enet_server.c\n
      • ex_stream_file.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_timer_pause.c#L39\">ex_timer_pause.c\n
      \n

      al_unregister_event_source

      \n 
      void al_unregister_event_source(ALLEGRO_EVENT_QUEUE *queue,\n    ALLEGRO_EVENT_SOURCE *source)
      \n

      Source\n Code

      \n@@ -1250,19 +1287,19 @@\n

      Return true if the event queue specified is currently empty.

      \n

      See also: al_get_next_event, al_peek_next_event

      \n

      Examples:

      \n
        \n
      • ex_audio_timer.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_inject_events.c#L49\">ex_inject_events.c\n
      • ex_enet_client.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_opengl.c#L151\">ex_opengl.c\n
      • ex_inject_events.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_touch_input.c#L70\">ex_touch_input.c\n
      \n

      al_get_next_event

      \n 
      bool al_get_next_event(ALLEGRO_EVENT_QUEUE *queue, ALLEGRO_EVENT *ret_event)
      \n

      Source\n Code

      \n

      Take the next event out of the event queue specified, and copy the\n@@ -1332,19 +1369,19 @@\n href=\"events.html#al_wait_for_event_timed\">al_wait_for_event_timed,\n al_wait_for_event_until,\n al_get_next_event

      \n

      Examples:

      \n
        \n
      • ex_enet_server.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_inject_events.c#L50\">ex_inject_events.c\n
      • ex_saw.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_enet_server.c#L224\">ex_enet_server.c\n
      • ex_stream_file.c
        • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_timer_pause.c#L58\">ex_timer_pause.c\n
      \n

      al_wait_for_event_timed

      \n 
      bool al_wait_for_event_timed(ALLEGRO_EVENT_QUEUE *queue,\n    ALLEGRO_EVENT *ret_event, float secs)
      \n

      Source\n Code

      \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -133,14 +133,18 @@\n any.timestamp (double)\n When the event was generated.\n By examining the type field you can then access type-specific fields. The\n any.source field tells you which event source generated that particular event.\n The any.timestamp field tells you when the event was generated. The time is\n referenced to the same starting point as _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\bi_\bm_\be.\n Each event is of one of the following types, with the usable fields given.\n+Examples:\n+ * _\be_\bx_\b__\bi_\bn_\bj_\be_\bc_\bt_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n+ * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bs_\be_\br_\bv_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b__\bp_\ba_\bu_\bs_\be_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_E\bEV\bVE\bEN\bNT\bT_\b_J\bJO\bOY\bYS\bST\bTI\bIC\bCK\bK_\b_A\bAX\bXI\bIS\bS *\b**\b**\b**\b**\b*\n A joystick axis value changed.\n joystick.id (ALLEGRO_JOYSTICK *)\n The joystick which generated the event. This is not the same as the event\n source joystick.source.\n joystick.stick (int)\n The stick number, counting from zero. Axes on a joystick are grouped into\n@@ -523,39 +527,56 @@\n my_event.user.data2 = &some_var;\n \n al_emit_user_event(&my_event_source, &my_event, NULL);\n Event type identifiers for user events are assigned by the user. Please see the\n documentation for _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bG_\bE_\bT_\b__\bE_\bV_\bE_\bN_\bT_\b__\bT_\bY_\bP_\bE for the rules you should follow when\n assigning identifiers.\n See also: _\ba_\bl_\b__\be_\bm_\bi_\bt_\b__\bu_\bs_\be_\br_\b__\be_\bv_\be_\bn_\bt, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bG_\bE_\bT_\b__\bE_\bV_\bE_\bN_\bT_\b__\bT_\bY_\bP_\bE, _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bu_\bs_\be_\br_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be\n+Examples:\n+ * _\be_\bx_\b__\bu_\bs_\be_\br_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_E\bEV\bVE\bEN\bNT\bT_\b_Q\bQU\bUE\bEU\bUE\bE *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_EVENT_QUEUE ALLEGRO_EVENT_QUEUE;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An event queue holds events that have been generated by event sources that are\n registered with the queue. Events are stored in the order they are generated.\n Access is in a strictly FIFO (first-in-first-out) order.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\be_\bv_\be_\bn_\bt_\b__\bq_\bu_\be_\bu_\be, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\be_\bv_\be_\bn_\bt_\b__\bq_\bu_\be_\bu_\be\n+Examples:\n+ * _\be_\bx_\b__\bi_\bn_\bj_\be_\bc_\bt_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n+ * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bs_\be_\br_\bv_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b__\bp_\ba_\bu_\bs_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_E\bEV\bVE\bEN\bNT\bT_\b_S\bSO\bOU\bUR\bRC\bCE\bE *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_EVENT_SOURCE ALLEGRO_EVENT_SOURCE;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An event source is any object which can generate events. For example, an\n ALLEGRO_DISPLAY can generate events, and you can get the ALLEGRO_EVENT_SOURCE\n pointer from an ALLEGRO_DISPLAY with _\ba_\bl_\b__\bg_\be_\bt_\b__\bd_\bi_\bs_\bp_\bl_\ba_\by_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be.\n You may create your own \u201cuser\u201d event sources that emit custom events.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT, _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bu_\bs_\be_\br_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be, _\ba_\bl_\b__\be_\bm_\bi_\bt_\b__\bu_\bs_\be_\br_\b__\be_\bv_\be_\bn_\bt\n+Examples:\n+ * _\be_\bx_\b__\bi_\bn_\bj_\be_\bc_\bt_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n+ * _\be_\bx_\b__\bu_\bs_\be_\br_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_E\bEV\bVE\bEN\bNT\bT_\b_T\bTY\bYP\bPE\bE *\b**\b**\b**\b**\b**\b*\n typedef unsigned int ALLEGRO_EVENT_TYPE;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An integer used to distinguish between different types of events.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bG_\bE_\bT_\b__\bE_\bV_\bE_\bN_\bT_\b__\bT_\bY_\bP_\bE, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bT_\bY_\bP_\bE_\b__\bI_\bS_\b__\bU_\bS_\bE_\bR\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_G\bGE\bET\bT_\b_E\bEV\bVE\bEN\bNT\bT_\b_T\bTY\bYP\bPE\bE *\b**\b**\b**\b**\b**\b*\n #define ALLEGRO_GET_EVENT_TYPE(a, b, c, d) AL_ID(a, b, c, d)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Make an event type identifier, which is a 32-bit integer. Usually, but not\n necessarily, this will be made from four 8-bit character codes, for example:\n+Examples:\n+\n+* [ex_user_events.c](https://github.com/liballeg/allegro5/blob/master/examples/\n+ex_user_events.c#L10)\n+* [ex_native_filechooser.c](https://github.com/liballeg/allegro5/blob/master/\n+examples/ex_native_filechooser.c#L24)\n+\n #defin MY_EVENT_TYPE ALLEGRO_GET_EVENT_TYPE('M','I','N','E')\n IDs less than 1024 are reserved for Allegro or its addons. Don\u2019t use anything\n lower than ALLEGRO_GET_EVENT_TYPE(0, 0, 4, 0).\n You should try to make your IDs unique so they don\u2019t clash with any 3rd party\n code you may be using. Be creative. Numbering from 1024 is not creative.\n If you need multiple identifiers, you could define them like this:\n #defin BASE_EVENT ALLEGRO_GET_EVENT_TYPE('M','I','N','E')\n@@ -578,41 +599,41 @@\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_e\bev\bve\ben\bnt\bt_\b_q\bqu\bue\beu\bue\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_EVENT_QUEUE *al_create_event_queue(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a new, empty event queue, returning a pointer to the newly created\n object if successful. Returns NULL on error.\n See also: _\ba_\bl_\b__\br_\be_\bg_\bi_\bs_\bt_\be_\br_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\be_\bv_\be_\bn_\bt_\b__\bq_\bu_\be_\bu_\be, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bQ_\bU_\bE_\bU_\bE\n Examples:\n+ * _\be_\bx_\b__\bi_\bn_\bj_\be_\bc_\bt_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bs_\be_\br_\bv_\be_\br_\b._\bc\n- * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n- * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b__\bp_\ba_\bu_\bs_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_e\bev\bve\ben\bnt\bt_\b_q\bqu\bue\beu\bue\be *\b**\b**\b**\b**\b**\b*\n void al_destroy_event_queue(ALLEGRO_EVENT_QUEUE *queue)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Destroy the event queue specified. All event sources currently registered with\n the queue will be automatically unregistered before the queue is destroyed.\n This function does nothing if queue is NULL. (since 5.2.9)\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\be_\bv_\be_\bn_\bt_\b__\bq_\bu_\be_\bu_\be, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bQ_\bU_\bE_\bU_\bE\n Examples:\n- * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n- * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\bi_\bn_\bj_\be_\bc_\bt_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b__\bp_\ba_\bu_\bs_\be_\b._\bc\n+ * _\bc_\bo_\bm_\bm_\bo_\bn_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\beg\bgi\bis\bst\bte\ber\br_\b_e\bev\bve\ben\bnt\bt_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b**\b*\n void al_register_event_source(ALLEGRO_EVENT_QUEUE *queue,\n ALLEGRO_EVENT_SOURCE *source)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Register the event source with the event queue specified. An event source may\n be registered with any number of event queues simultaneously, or none. Trying\n to register an event source with the same event queue more than once does\n nothing.\n See also: _\ba_\bl_\b__\bu_\bn_\br_\be_\bg_\bi_\bs_\bt_\be_\br_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bS_\bO_\bU_\bR_\bC_\bE\n Examples:\n+ * _\be_\bx_\b__\bi_\bn_\bj_\be_\bc_\bt_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bs_\be_\br_\bv_\be_\br_\b._\bc\n- * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n- * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b__\bp_\ba_\bu_\bs_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bnr\bre\beg\bgi\bis\bst\bte\ber\br_\b_e\bev\bve\ben\bnt\bt_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b**\b*\n void al_unregister_event_source(ALLEGRO_EVENT_QUEUE *queue,\n ALLEGRO_EVENT_SOURCE *source)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Unregister an event source with an event queue. If the event source is not\n actually registered with the event queue, nothing happens.\n If the queue had any events in it which originated from the event source, they\n@@ -646,17 +667,17 @@\n Since: 5.1.0\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_e\bev\bve\ben\bnt\bt_\b_q\bqu\bue\beu\bue\be_\b_e\bem\bmp\bpt\bty\by *\b**\b**\b**\b**\b**\b*\n bool al_is_event_queue_empty(ALLEGRO_EVENT_QUEUE *queue)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return true if the event queue specified is currently empty.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\be_\bx_\bt_\b__\be_\bv_\be_\bn_\bt, _\ba_\bl_\b__\bp_\be_\be_\bk_\b__\bn_\be_\bx_\bt_\b__\be_\bv_\be_\bn_\bt\n Examples:\n- * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bt_\bi_\bm_\be_\br_\b._\bc\n- * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bc_\bl_\bi_\be_\bn_\bt_\b._\bc\n * _\be_\bx_\b__\bi_\bn_\bj_\be_\bc_\bt_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n+ * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b._\bc\n+ * _\be_\bx_\b__\bt_\bo_\bu_\bc_\bh_\b__\bi_\bn_\bp_\bu_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_n\bne\bex\bxt\bt_\b_e\bev\bve\ben\bnt\bt *\b**\b**\b**\b**\b**\b*\n bool al_get_next_event(ALLEGRO_EVENT_QUEUE *queue, ALLEGRO_EVENT *ret_event)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Take the next event out of the event queue specified, and copy the contents\n into ret_event, returning true. The original event will be removed from the\n queue. If the event queue is empty, return false and the contents of ret_event\n are unspecified.\n@@ -691,17 +712,17 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Wait until the event queue specified is non-empty. If ret_event is not NULL,\n the first event in the queue will be copied into ret_event and removed from the\n queue. If ret_event is NULL the first event is left at the head of the queue.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT, _\ba_\bl_\b__\bw_\ba_\bi_\bt_\b__\bf_\bo_\br_\b__\be_\bv_\be_\bn_\bt_\b__\bt_\bi_\bm_\be_\bd, _\ba_\bl_\b__\bw_\ba_\bi_\bt_\b__\bf_\bo_\br_\b__\be_\bv_\be_\bn_\bt_\b__\bu_\bn_\bt_\bi_\bl,\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\be_\bx_\bt_\b__\be_\bv_\be_\bn_\bt\n Examples:\n+ * _\be_\bx_\b__\bi_\bn_\bj_\be_\bc_\bt_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bs_\be_\br_\bv_\be_\br_\b._\bc\n- * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n- * _\be_\bx_\b__\bs_\bt_\br_\be_\ba_\bm_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b__\bp_\ba_\bu_\bs_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_w\bwa\bai\bit\bt_\b_f\bfo\bor\br_\b_e\bev\bve\ben\bnt\bt_\b_t\bti\bim\bme\bed\bd *\b**\b**\b**\b**\b**\b*\n bool al_wait_for_event_timed(ALLEGRO_EVENT_QUEUE *queue,\n ALLEGRO_EVENT *ret_event, float secs)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Wait until the event queue specified is non-empty. If ret_event is not NULL,\n the first event in the queue will be copied into ret_event and removed from the\n queue. If ret_event is NULL the first event is left at the head of the queue.\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/file.html", "source2": "./usr/share/doc/allegro5-doc/refman/file.html", "unified_diff": "@@ -242,14 +242,23 @@\n

      ALLEGRO_FILE

      \n 
      typedef struct ALLEGRO_FILE ALLEGRO_FILE;
      \n

      Source\n Code

      \n

      An opaque object representing an open file. This could be a real file\n on disk or a virtual file.

      \n+

      Examples:

      \n+
        \n+
      • ex_file.c
        • \n+
      • ex_dir.c
        • \n+
      • ex_memfile.c
        • \n+
      \n

      ALLEGRO_FILE_INTERFACE

      \n 
      typedef struct ALLEGRO_FILE_INTERFACE
      \n

      Source\n Code

      \n

      A structure containing function pointers to handle a type of \u201cfile\u201d,\n real or virtual. See the full discussion in al_fopen will also return NULL.

      \n

      The fi_fclose function must clean up and free the userdata, but\n Allegro will free the ALLEGRO_FILE\n handle.

      \n

      If fi_fungetc is NULL, then Allegro\u2019s default implementation of a 16\n char long buffer will be used.

      \n+

      Examples:

      \n+
        \n+
      • ex_curl.c
        • \n+
      \n

      ALLEGRO_SEEK

      \n 
      typedef enum ALLEGRO_SEEK
      \n

      Source\n Code

      \n
        \n
      • ALLEGRO_SEEK_SET - seek relative to beginning of file
        • \n
      • ALLEGRO_SEEK_CUR - seek relative to current file position
        • \n
      • ALLEGRO_SEEK_END - seek relative to end of file
        • \n
      \n

      See also: al_fseek

      \n+

      Examples:

      \n+
        \n+
      • ex_file.c
        • \n+
      • ex_memfile.c
        • \n+
      • ex_file_slice.c
        • \n+
      \n

      al_fopen

      \n 
      ALLEGRO_FILE *al_fopen(const char *path, const char *mode)
      \n

      Source\n Code

      \n

      Creates and opens a file (real or virtual) given the path and mode.\n The current file interface is used to open the file.

      \n@@ -318,19 +341,19 @@\n

      Returns a file handle on success, or NULL on error.

      \n

      See also: al_set_new_file_interface,\n al_fclose.

      \n

      Examples:

      \n
        \n
      • ex_synth.cpp
        • \n-
      • ex_file.c
        • \n
      • ex_file_slice.c
        • \n+
      • ex_bitmap_file.c
        • \n
      \n

      al_fopen_interface

      \n 
      ALLEGRO_FILE *al_fopen_interface(const ALLEGRO_FILE_INTERFACE *drv,\n    const char *path, const char *mode)
      \n

      Source\n Code

      \n@@ -389,19 +412,19 @@\n Code

      \n

      Close the given file, writing any buffered output data (if any).

      \n

      Returns true on success, false on failure. errno is set to indicate\n the error.

      \n

      Examples:

      \n
        \n
      • ex_synth.cpp
        • \n-
      • ex_file.c
        • \n
      • ex_memfile.c
        • \n+
      • ex_file_slice.c
        • \n
      \n

      al_fread

      \n 
      size_t al_fread(ALLEGRO_FILE *f, void *ptr, size_t size)
      \n

      Source\n Code

      \n

      Read \u2018size\u2019 bytes into the buffer pointed to by \u2018ptr\u2019, from the given\n@@ -441,19 +464,19 @@\n href=\"file.html#al_fwrite16be\">al_fwrite16be, al_fwrite16le, al_fwrite32be, al_fwrite32le

      \n

      Examples:

      \n
        \n
      • ex_synth.cpp
        • \n-
      • ex_memfile.c
        • \n
      • ex_file_slice.c
        • \n+
      • ex_synth.cpp
        • \n
      \n

      al_fflush

      \n 
      bool al_fflush(ALLEGRO_FILE *f)
      \n

      Source\n Code

      \n

      Flush any pending writes to the given file.

      \n@@ -890,14 +913,19 @@\n href=\"file.html#allegro_file_interface\">ALLEGRO_FILE_INTERFACE table\n for the calling thread. This will change the handler for later calls to\n al_fopen.

      \n

      See also: al_set_standard_file_interface,\n al_store_state, al_restore_state.

      \n+

      Examples:

      \n+
        \n+
      • ex_curl.c
        • \n+
      \n al_set_standard_file_interface\n 
      void al_set_standard_file_interface(void)
      \n

      Source\n Code

      \n

      Set the \n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_F\bFI\bIL\bLE\bE *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_FILE ALLEGRO_FILE;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An opaque object representing an open file. This could be a real file on disk\n or a virtual file.\n+Examples:\n+ * _\be_\bx_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\bd_\bi_\br_\b._\bc\n+ * _\be_\bx_\b__\bm_\be_\bm_\bf_\bi_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_F\bFI\bIL\bLE\bE_\b_I\bIN\bNT\bTE\bER\bRF\bFA\bAC\bCE\bE *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_FILE_INTERFACE\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n A structure containing function pointers to handle a type of \u201cfile\u201d, real or\n virtual. See the full discussion in _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bf_\bi_\bl_\be_\b__\bi_\bn_\bt_\be_\br_\bf_\ba_\bc_\be.\n The fields are:\n void* (*fi_fopen)(const char *path, const char *mode);\n@@ -116,21 +120,27 @@\n with the file. The other functions can access that data by calling\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bf_\bi_\bl_\be_\b__\bu_\bs_\be_\br_\bd_\ba_\bt_\ba on the file handle. If fi_open returns NULL then _\ba_\bl_\b__\bf_\bo_\bp_\be_\bn\n will also return NULL.\n The fi_fclose function must clean up and free the userdata, but Allegro will\n free the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bF_\bI_\bL_\bE handle.\n If fi_fungetc is NULL, then Allegro\u2019s default implementation of a 16 char long\n buffer will be used.\n+Examples:\n+ * _\be_\bx_\b__\bc_\bu_\br_\bl_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_S\bSE\bEE\bEK\bK *\b**\b**\b**\b**\b**\b*\n typedef enum ALLEGRO_SEEK\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n * ALLEGRO_SEEK_SET - seek relative to beginning of file\n * ALLEGRO_SEEK_CUR - seek relative to current file position\n * ALLEGRO_SEEK_END - seek relative to end of file\n See also: _\ba_\bl_\b__\bf_\bs_\be_\be_\bk\n+Examples:\n+ * _\be_\bx_\b__\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\bm_\be_\bm_\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\bf_\bi_\bl_\be_\b__\bs_\bl_\bi_\bc_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_f\bfo\bop\bpe\ben\bn *\b**\b**\b**\b**\b**\b*\n ALLEGRO_FILE *al_fopen(const char *path, const char *mode)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Creates and opens a file (real or virtual) given the path and mode. The current\n file interface is used to open the file.\n Parameters:\n * path - path to the file to open\n@@ -144,17 +154,17 @@\n defined to be equal to LF either.)\n Newline translations can be useful for text files but is disastrous for binary\n files. To avoid this behaviour you need to open file streams in binary mode by\n using a mode argument containing a \u201cb\u201d, e.g.\u00a0\u201crb\u201d, \u201cwb\u201d.\n Returns a file handle on success, or NULL on error.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bf_\bi_\bl_\be_\b__\bi_\bn_\bt_\be_\br_\bf_\ba_\bc_\be, _\ba_\bl_\b__\bf_\bc_\bl_\bo_\bs_\be.\n Examples:\n- * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n * _\be_\bx_\b__\bf_\bi_\bl_\be_\b._\bc\n * _\be_\bx_\b__\bf_\bi_\bl_\be_\b__\bs_\bl_\bi_\bc_\be_\b._\bc\n+ * _\be_\bx_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bi_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_f\bfo\bop\bpe\ben\bn_\b_i\bin\bnt\bte\ber\brf\bfa\bac\bce\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_FILE *al_fopen_interface(const ALLEGRO_FILE_INTERFACE *drv,\n const char *path, const char *mode)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Opens a file using the specified interface, instead of the interface set with\n _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bf_\bi_\bl_\be_\b__\bi_\bn_\bt_\be_\br_\bf_\ba_\bc_\be.\n See also: _\ba_\bl_\b__\bf_\bo_\bp_\be_\bn\n@@ -194,17 +204,17 @@\n * _\be_\bx_\b__\bf_\bi_\bl_\be_\b__\bs_\bl_\bi_\bc_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_f\bfc\bcl\blo\bos\bse\be *\b**\b**\b**\b**\b**\b*\n bool al_fclose(ALLEGRO_FILE *f)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Close the given file, writing any buffered output data (if any).\n Returns true on success, false on failure. errno is set to indicate the error.\n Examples:\n- * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n * _\be_\bx_\b__\bf_\bi_\bl_\be_\b._\bc\n * _\be_\bx_\b__\bm_\be_\bm_\bf_\bi_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\bf_\bi_\bl_\be_\b__\bs_\bl_\bi_\bc_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_f\bfr\bre\bea\bad\bd *\b**\b**\b**\b**\b**\b*\n size_t al_fread(ALLEGRO_FILE *f, void *ptr, size_t size)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Read \u2018size\u2019 bytes into the buffer pointed to by \u2018ptr\u2019, from the given file.\n Returns the number of bytes actually read. If an error occurs, or the end-of-\n file is reached, the return value is a short byte count (or zero).\n al_fread() does not distinguish between EOF and other errors. Use _\ba_\bl_\b__\bf_\be_\bo_\bf and\n@@ -219,17 +229,17 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Write \u2018size\u2019 bytes from the buffer pointed to by \u2018ptr\u2019 into the given file.\n Returns the number of bytes actually written. If an error occurs, the return\n value is a short byte count (or zero).\n See also: _\ba_\bl_\b__\bf_\bp_\bu_\bt_\bc, _\ba_\bl_\b__\bf_\bp_\bu_\bt_\bs, _\ba_\bl_\b__\bf_\bw_\br_\bi_\bt_\be_\b1_\b6_\bb_\be, _\ba_\bl_\b__\bf_\bw_\br_\bi_\bt_\be_\b1_\b6_\bl_\be, _\ba_\bl_\b__\bf_\bw_\br_\bi_\bt_\be_\b3_\b2_\bb_\be,\n _\ba_\bl_\b__\bf_\bw_\br_\bi_\bt_\be_\b3_\b2_\bl_\be\n Examples:\n- * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n * _\be_\bx_\b__\bm_\be_\bm_\bf_\bi_\bl_\be_\b._\bc\n * _\be_\bx_\b__\bf_\bi_\bl_\be_\b__\bs_\bl_\bi_\bc_\be_\b._\bc\n+ * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_f\bff\bfl\blu\bus\bsh\bh *\b**\b**\b**\b**\b**\b*\n bool al_fflush(ALLEGRO_FILE *f)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Flush any pending writes to the given file.\n Returns true on success, false otherwise. errno is set to indicate the error.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\be_\br_\br_\bn_\bo\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_f\bft\bte\bel\bll\bl *\b**\b**\b**\b**\b**\b*\n@@ -502,14 +512,16 @@\n will handle the following _\ba_\bl_\b__\bf_\bo_\bp_\be_\bn calls for the current thread.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_n\bne\bew\bw_\b_f\bfi\bil\ble\be_\b_i\bin\bnt\bte\ber\brf\bfa\bac\bce\be *\b**\b**\b**\b**\b*\n void al_set_new_file_interface(const ALLEGRO_FILE_INTERFACE *file_interface)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bF_\bI_\bL_\bE_\b__\bI_\bN_\bT_\bE_\bR_\bF_\bA_\bC_\bE table for the calling thread. This will change\n the handler for later calls to _\ba_\bl_\b__\bf_\bo_\bp_\be_\bn.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd_\b__\bf_\bi_\bl_\be_\b__\bi_\bn_\bt_\be_\br_\bf_\ba_\bc_\be, _\ba_\bl_\b__\bs_\bt_\bo_\br_\be_\b__\bs_\bt_\ba_\bt_\be, _\ba_\bl_\b__\br_\be_\bs_\bt_\bo_\br_\be_\b__\bs_\bt_\ba_\bt_\be.\n+Examples:\n+ * _\be_\bx_\b__\bc_\bu_\br_\bl_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bst\bta\ban\bnd\bda\bar\brd\bd_\b_f\bfi\bil\ble\be_\b_i\bin\bnt\bte\ber\brf\bfa\bac\bce\be *\b**\b**\b**\b**\b*\n void al_set_standard_file_interface(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bF_\bI_\bL_\bE_\b__\bI_\bN_\bT_\bE_\bR_\bF_\bA_\bC_\bE table to the default, for the calling thread.\n This will change the handler for later calls to _\ba_\bl_\b__\bf_\bo_\bp_\be_\bn.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bf_\bi_\bl_\be_\b__\bi_\bn_\bt_\be_\br_\bf_\ba_\bc_\be\n Examples:\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/font.html", "source2": "./usr/share/doc/allegro5-doc/refman/font.html", "unified_diff": "@@ -294,14 +294,23 @@\n

      A handle identifying any kind of font. Usually you will create it\n with al_load_font which supports\n loading all kinds of TrueType fonts supported by the FreeType library.\n If you instead pass the filename of a bitmap file, it will be loaded\n with al_load_bitmap and a\n font in Allegro\u2019s bitmap font format will be created from it with al_grab_font_from_bitmap.

      \n+

      Examples:

      \n+
        \n+
      • ex_disable_screensaver.c
        • \n+
      • ex_font_justify.cpp
        • \n+
      • ex_timedwait.c
        • \n+
      \n

      ALLEGRO_GLYPH

      \n 
      typedef struct ALLEGRO_GLYPH ALLEGRO_GLYPH;
      \n

      Source\n Code

      \n

      A structure containing the properties of a character in a font.

      \n 
      typedef struct ALLEGRO_GLYPH {\n@@ -328,14 +337,19 @@\n to the next character in a string and includes kerning.
      \n 
      Since: 5.2.1
      \n 
      \n 
      Unstable\n API: This API is new and subject to refinement.
      \n 
      \n 
      See also: al_get_glyph
      \n+
      Examples:
      \n+
        \n+
      • ex_ttf.c
        • \n+
      \n 
      al_init_font_addon
      \n 
      bool al_init_font_addon(void)
      \n 
      Source\n Code
      \n 
      Initialise the font addon.
      \n 
      Note that if you intend to load bitmap fonts, you will need to\n@@ -347,14 +361,23 @@\n function has no return value. You may wish to avoid checking the return\n value if your code needs to be compatible with Allegro 5.0. Currently,\n the function will never return false.
      \n 
      See also: al_init_image_addon, al_init_ttf_addon, al_shutdown_font_addon
      \n+
      Examples:
      \n+
        \n+
      • ex_disable_screensaver.c
        • \n+
      • ex_font_justify.cpp
        • \n+
      • ex_timedwait.c
        • \n+
      \n 
      al_is_font_addon_initialized
      \n 
      bool al_is_font_addon_initialized(void)
      \n 
      Source\n Code
      \n 
      Returns true if the font addon is initialized, otherwise returns\n false.
      \n@@ -385,22 +408,40 @@\n href=\"graphics.html#al_set_new_bitmap_flags\">bitmap flags at the\n time the font is loaded.
      \n 
      See also: al_destroy_font, al_init_font_addon, al_register_font_loader, al_load_bitmap_font_flags,\n al_load_ttf_font
      \n+
      Examples:
      \n+
        \n+
      • ex_font_justify.cpp
        • \n+
      • ex_membmp.c
        • \n+
      • ex_window_title.c
        • \n+
      \n 
      al_destroy_font
      \n 
      void al_destroy_font(ALLEGRO_FONT *f)
      \n 
      Source\n Code
      \n 
      Frees the memory being used by a font structure. Does nothing if\n passed NULL.
      \n 
      See also: al_load_font
      \n+
      Examples:
      \n+
        \n+
      • ex_disable_screensaver.c
        • \n+
      • ex_font_justify.cpp
        • \n+
      • ex_cpu.c
        • \n+
      \n 
      al_register_font_loader
      \n 
      bool al_register_font_loader(char const *extension,\n    ALLEGRO_FONT *(*load_font)(char const *filename, int size, int flags))
      \n 
      Source\n Code
      \n 
      Informs Allegro of a new font file type, telling it how to load files\n@@ -434,53 +475,86 @@\n                |        |\n                descent  |\n                |        |\n -------------------------
      \n

      See also: al_get_text_width, al_get_text_dimensions

      \n+

      Examples:

      \n+
        \n+
      • ex_font_justify.cpp
        • \n+
      • ex_membmp.c
        • \n+
      • ex_mouse_warp.c
        • \n+
      \n

      al_get_font_ascent

      \n 
      int al_get_font_ascent(const ALLEGRO_FONT *f)
      \n

      Source\n Code

      \n

      Returns the ascent of the specified font.

      \n

      See also: al_get_font_descent, al_get_font_line_height

      \n+

      Examples:

      \n+
        \n+
      • ex_ttf.c
        • \n+
      \n

      al_get_font_descent

      \n 
      int al_get_font_descent(const ALLEGRO_FONT *f)
      \n

      Source\n Code

      \n

      Returns the descent of the specified font.

      \n

      See also: al_get_font_ascent, al_get_font_line_height

      \n+

      Examples:

      \n+
        \n+
      • ex_ttf.c
        • \n+
      \n

      al_get_text_width

      \n 
      int al_get_text_width(const ALLEGRO_FONT *f, const char *str)
      \n

      Source\n Code

      \n

      Calculates the length of a string in a particular font, in\n pixels.

      \n

      See also: al_get_ustr_width, al_get_font_line_height, al_get_text_dimensions

      \n+

      Examples:

      \n+
        \n+
      • ex_display_options.c
        • \n+
      • ex_record_name.c
        • \n+
      • ex_color_gradient.c
        • \n+
      \n

      al_get_ustr_width

      \n 
      int al_get_ustr_width(const ALLEGRO_FONT *f, ALLEGRO_USTR const *ustr)
      \n

      Source\n Code

      \n

      Like al_get_text_width but\n expects an ALLEGRO_USTR.

      \n

      See also: al_get_text_width, al_get_ustr_dimensions

      \n+

      Examples:

      \n+
        \n+
      • nihgui.cpp
        • \n+
      \n

      al_draw_text

      \n 
      void al_draw_text(const ALLEGRO_FONT *font,\n    ALLEGRO_COLOR color, float x, float y, int flags,\n    char const *text)
      \n

      Source\n Code

      \n@@ -506,27 +580,45 @@\n but you can use al_draw_multiline_text for\n multi line text output.

      \n

      See also: al_draw_ustr, al_draw_textf, al_draw_justified_text, al_draw_multiline_text.

      \n+

      Examples:

      \n+
        \n+
      • ex_disable_screensaver.c
        • \n+
      • ex_timedwait.c
        • \n+
      • ex_display_events.c
        • \n+
      \n

      al_draw_ustr

      \n 
      void al_draw_ustr(const ALLEGRO_FONT *font,\n    ALLEGRO_COLOR color, float x, float y, int flags,\n    const ALLEGRO_USTR *ustr)
      \n

      Source\n Code

      \n

      Like al_draw_text, except the\n text is passed as an ALLEGRO_USTR instead of a NUL-terminated char\n array.

      \n

      See also: al_draw_text, al_draw_justified_ustr, al_draw_multiline_ustr

      \n+

      Examples:

      \n+
        \n+
      • ex_font_multiline.cpp
        • \n+
      • nihgui.cpp
        • \n+
      • ex_blend.c
        • \n+
      \n

      al_draw_justified_text

      \n 
      void al_draw_justified_text(const ALLEGRO_FONT *font,\n    ALLEGRO_COLOR color, float x1, float x2,\n    float y, float diff, int flags, const char *text)
      \n

      Source\n Code

      \n@@ -541,14 +633,19 @@\n
        \n
      • ALLEGRO_ALIGN_INTEGER - Draw text aligned to integer pixel\n positions. Since: 5.0.8, 5.1.5
        • \n
      \n

      See also: al_draw_justified_textf, al_draw_justified_ustr

      \n+

      Examples:

      \n+
        \n+
      • ex_font_justify.cpp
        • \n+
      \n

      al_draw_justified_ustr

      \n 
      void al_draw_justified_ustr(const ALLEGRO_FONT *font,\n    ALLEGRO_COLOR color, float x1, float x2,\n    float y, float diff, int flags, const ALLEGRO_USTR *ustr)
      \n

      Source\n Code

      \n@@ -567,14 +664,23 @@\n href=\"https://github.com/liballeg/allegro5/blob/master/addons/font/text.c#L213\">Source\n Code

      \n

      Formatted text output, using a printf() style format string. All\n parameters have the same meaning as with al_draw_text otherwise.

      \n

      See also: al_draw_text, al_draw_ustr

      \n+

      Examples:

      \n+
        \n+
      • ex_disable_screensaver.c
        • \n+
      • ex_timedwait.c
        • \n+
      • ex_display_events.c
        • \n+
      \n

      al_draw_justified_textf

      \n 
      void al_draw_justified_textf(const ALLEGRO_FONT *f,\n    ALLEGRO_COLOR color, float x1, float x2, float y,\n    float diff, int flags, const char *format, ...)
      \n

      Source\n Code

      \n@@ -604,14 +710,21 @@\n
    \n

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

    \n

    See also: al_get_text_width, al_get_font_line_height, al_get_ustr_dimensions

    \n+

    Examples:

    \n+
      \n+
    • ex_ttf.c
      • \n+
    • ex_logo.c
      • \n+
    \n

    al_get_ustr_dimensions

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

    Source\n Code

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

    \n

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

    \n

    Since: 5.1.4

    \n

    See also: al_grab_font_from_bitmap

    \n+

    Examples:

    \n+
      \n+
    • ex_ttf.c
      • \n+
    \n

    al_set_fallback_font

    \n 
    void al_set_fallback_font(ALLEGRO_FONT *font, ALLEGRO_FONT *fallback)
    \n

    Source\n Code

    \n

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

    \n

    Since: 5.1.12

    \n

    See also: al_get_fallback_font, al_draw_glyph, al_draw_text

    \n+

    Examples:

    \n+
      \n+
    • ex_ttf.c
      • \n+
    \n

    al_get_fallback_font

    \n 
    ALLEGRO_FONT *al_get_fallback_font(ALLEGRO_FONT *font)
    \n

    Source\n Code

    \n

    Retrieves the fallback font for this font or NULL.

    \n

    Since: 5.1.12

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

    \n

    Since: 5.1.12

    \n

    See also: al_get_glyph_width, al_get_glyph_dimensions, al_get_glyph_advance.

    \n+

    Examples:

    \n+
      \n+
    • ex_font.c
      • \n+
    • ex_ttf.c
      • \n+
    \n

    al_get_glyph_width

    \n 
    int al_get_glyph_width(const ALLEGRO_FONT *f, int codepoint)
    \n

    Source\n Code

    \n

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

    Since: 5.1.12

    \n

    See also: al_draw_glyph, al_get_glyph_width, al_get_glyph_advance.

    \n+

    Examples:

    \n+
      \n+
    • ex_ttf.c
      • \n+
    \n

    al_get_glyph_advance

    \n 
    int al_get_glyph_advance(const ALLEGRO_FONT *f, int codepoint1, int codepoint2)
    \n

    Source\n Code

    \n

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

    Since: 5.1.12

    \n

    See also: al_draw_glyph, al_get_glyph_width, al_get_glyph_dimensions.

    \n+

    Examples:

    \n+
      \n+
    • ex_font.c
      • \n+
    • ex_ttf.c
      • \n+
    \n

    Multiline text drawing

    \n

    al_draw_multiline_text

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

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

    \n

    Since: 5.1.9

    \n

    See also: al_do_multiline_text, al_draw_multiline_ustr, al_draw_multiline_textf

    \n+

    Examples:

    \n+
      \n+
    • ex_font_multiline.cpp
      • \n+
    • ex_resize2.c
      • \n+
    \n

    al_draw_multiline_ustr

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

    Source\n Code

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

    \n

    Since: 5.1.9

    \n

    See also: al_draw_multiline_text, al_draw_multiline_ustr, al_do_multiline_text

    \n+

    Examples:

    \n+
      \n+
    • ex_resize2.c
      • \n+
    \n

    al_do_multiline_text

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

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

    \n

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

    \n

    Since: 5.1.9

    \n

    See also: al_draw_multiline_text

    \n+

    Examples:

    \n+
      \n+
    • ex_font_multiline.cpp
      • \n+
    \n

    al_do_multiline_ustr

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

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

    \n

    See also: al_load_bitmap,\n al_grab_font_from_bitmap

    \n+

    Examples:

    \n+
      \n+
    • ex_font.c
      • \n+
    • ex_ttf.c
      • \n+
    \n

    al_load_bitmap_font

    \n 
    ALLEGRO_FONT *al_load_bitmap_font(const char *fname)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_load_bitmap_font_flags,\n al_load_font, al_load_bitmap_flags

    \n+

    Examples:

    \n+
      \n+
    • ex_bitmap_flip.c
      • \n+
    • ex_mouse_cursor.c
      • \n+
    • ex_record_name.c
      • \n+
    \n

    al_load_bitmap_font_flags

    \n 
    ALLEGRO_FONT *al_load_bitmap_font_flags(const char *fname, int flags)
    \n

    Source\n Code

    \n

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

    Returns NULL on an error.

    \n

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

    \n

    Since: 5.0.8, 5.1.3

    \n

    See also: al_load_bitmap_font, al_destroy_font

    \n+

    Examples:

    \n+
      \n+
    • ex_disable_screensaver.c
      • \n+
    • ex_timedwait.c
      • \n+
    • ex_display_events.c
      • \n+
    \n

    TTF fonts

    \n

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

    \n 
     #include <allegro5/allegro_ttf.h>
    \n

    al_init_ttf_addon

    \n 
    bool al_init_ttf_addon(void)
    \n

    \n

    Call this after al_init_font_addon to make al_load_font recognize \u201c.ttf\u201d and\n other formats supported by al_load_ttf_font.

    \n

    Returns true on success, false on failure.

    \n+

    Examples:

    \n+
      \n+
    • ex_font_justify.cpp
      • \n+
    • ex_font_multiline.cpp
      • \n+
    • ex_color.cpp
      • \n+
    \n

    al_is_ttf_addon_initialized

    \n 
    bool al_is_ttf_addon_initialized(void)
    \n

    Source\n Code

    \n

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

    \n@@ -1165,14 +1358,23 @@\n

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

    • \n \n

    See also: al_init_ttf_addon, al_load_ttf_font_f

    \n+

    Examples:

    \n+
      \n+
    • ex_bitmap_flip.c
      • \n+
    • ex_synth.cpp
      • \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_load_ttf_font_f

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

    Source\n Code

    \n

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

    \n

    Since: 5.2.1

    \n
    \n

    Unstable\n API: This API is new and subject to refinement.

    \n
    \n

    See also: ALLEGRO_GLYPH

    \n+

    Examples:

    \n+
      \n+
    • ex_font.c
      • \n+
    • ex_ttf.c
      • \n+
    \n

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

    \n \n \n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -103,14 +103,18 @@\n typedef struct ALLEGRO_FONT ALLEGRO_FONT;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n A handle identifying any kind of font. Usually you will create it with\n _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bf_\bo_\bn_\bt which supports loading all kinds of TrueType fonts supported by\n the FreeType library. If you instead pass the filename of a bitmap file, it\n will be loaded with _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp and a font in Allegro\u2019s bitmap font format\n will be created from it with _\ba_\bl_\b__\bg_\br_\ba_\bb_\b__\bf_\bo_\bn_\bt_\b__\bf_\br_\bo_\bm_\b__\bb_\bi_\bt_\bm_\ba_\bp.\n+Examples:\n+ * _\be_\bx_\b__\bd_\bi_\bs_\ba_\bb_\bl_\be_\b__\bs_\bc_\br_\be_\be_\bn_\bs_\ba_\bv_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bj_\bu_\bs_\bt_\bi_\bf_\by_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\bd_\bw_\ba_\bi_\bt_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_G\bGL\bLY\bYP\bPH\bH *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_GLYPH ALLEGRO_GLYPH;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n A structure containing the properties of a character in a font.\n typedef struct ALLEGRO_GLYPH {\n ALLEGRO_BITMAP *bitmap; // the bitmap the character is on\n int x; // the x position of the glyph on bitmap\n@@ -131,27 +135,33 @@\n Glyphs are tightly packed onto the bitmap, so you need to add offset_x and\n offset_y to your draw position for the text to look right.\n advance is the number of pixels to add to your x position to advance to the\n next character in a string and includes kerning.\n Since: 5.2.1\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: This API is new and subject to refinement.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bg_\bl_\by_\bp_\bh\n+Examples:\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bni\bit\bt_\b_f\bfo\bon\bnt\bt_\b_a\bad\bdd\bdo\bon\bn *\b**\b**\b**\b**\b*\n bool al_init_font_addon(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Initialise the font addon.\n Note that if you intend to load bitmap fonts, you will need to initialise\n allegro_image separately (unless you are using another library to load images).\n Similarly, if you wish to load truetype-fonts, do not forget to also call\n _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bt_\bt_\bf_\b__\ba_\bd_\bd_\bo_\bn.\n Returns true on success, false on failure. On the 5.0 branch, this function has\n no return value. You may wish to avoid checking the return value if your code\n needs to be compatible with Allegro 5.0. Currently, the function will never\n return false.\n See also: _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bi_\bm_\ba_\bg_\be_\b__\ba_\bd_\bd_\bo_\bn, _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bt_\bt_\bf_\b__\ba_\bd_\bd_\bo_\bn, _\ba_\bl_\b__\bs_\bh_\bu_\bt_\bd_\bo_\bw_\bn_\b__\bf_\bo_\bn_\bt_\b__\ba_\bd_\bd_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\bd_\bi_\bs_\ba_\bb_\bl_\be_\b__\bs_\bc_\br_\be_\be_\bn_\bs_\ba_\bv_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bj_\bu_\bs_\bt_\bi_\bf_\by_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\bd_\bw_\ba_\bi_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_f\bfo\bon\bnt\bt_\b_a\bad\bdd\bdo\bon\bn_\b_i\bin\bni\bit\bti\bia\bal\bli\biz\bze\bed\bd *\b**\b**\b**\b**\b*\n bool al_is_font_addon_initialized(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if the font addon is initialized, otherwise returns false.\n Since: 5.2.6\n See also: _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bf_\bo_\bn_\bt_\b__\ba_\bd_\bd_\bo_\bn, _\ba_\bl_\b__\bs_\bh_\bu_\bt_\bd_\bo_\bw_\bn_\b__\bf_\bo_\bn_\bt_\b__\ba_\bd_\bd_\bo_\bn\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bsh\bhu\but\btd\bdo\bow\bwn\bn_\b_f\bfo\bon\bnt\bt_\b_a\bad\bdd\bdo\bon\bn *\b**\b**\b**\b**\b*\n@@ -166,19 +176,27 @@\n Loads a font from disk. This will use _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bo_\bn_\bt_\b__\bf_\bl_\ba_\bg_\bs if you pass the\n name of a known bitmap format, or else _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bt_\bt_\bf_\b__\bf_\bo_\bn_\bt.\n The flags parameter is passed through to either of those functions. Bitmap and\n TTF fonts are also affected by the current _\bb_\bi_\bt_\bm_\ba_\bp_\b _\bf_\bl_\ba_\bg_\bs at the time the font is\n loaded.\n See also: _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bf_\bo_\bn_\bt, _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bf_\bo_\bn_\bt_\b__\ba_\bd_\bd_\bo_\bn, _\ba_\bl_\b__\br_\be_\bg_\bi_\bs_\bt_\be_\br_\b__\bf_\bo_\bn_\bt_\b__\bl_\bo_\ba_\bd_\be_\br,\n _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bo_\bn_\bt_\b__\bf_\bl_\ba_\bg_\bs, _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bt_\bt_\bf_\b__\bf_\bo_\bn_\bt\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bj_\bu_\bs_\bt_\bi_\bf_\by_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bm_\be_\bm_\bb_\bm_\bp_\b._\bc\n+ * _\be_\bx_\b__\bw_\bi_\bn_\bd_\bo_\bw_\b__\bt_\bi_\bt_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_f\bfo\bon\bnt\bt *\b**\b**\b**\b**\b*\n void al_destroy_font(ALLEGRO_FONT *f)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Frees the memory being used by a font structure. Does nothing if passed NULL.\n See also: _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bf_\bo_\bn_\bt\n+Examples:\n+ * _\be_\bx_\b__\bd_\bi_\bs_\ba_\bb_\bl_\be_\b__\bs_\bc_\br_\be_\be_\bn_\bs_\ba_\bv_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bj_\bu_\bs_\bt_\bi_\bf_\by_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bc_\bp_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\beg\bgi\bis\bst\bte\ber\br_\b_f\bfo\bon\bnt\bt_\b_l\blo\boa\bad\bde\ber\br *\b**\b**\b**\b**\b*\n bool al_register_font_loader(char const *extension,\n ALLEGRO_FONT *(*load_font)(char const *filename, int size, int flags))\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Informs Allegro of a new font file type, telling it how to load files of this\n format.\n The extension should include the leading dot (\u2018.\u2019) character. It will be\n@@ -204,34 +222,48 @@\n / \\ | height\n ---------------- |\n | |\n descent |\n | |\n -------------------------\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\be_\bx_\bt_\b__\bw_\bi_\bd_\bt_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\be_\bx_\bt_\b__\bd_\bi_\bm_\be_\bn_\bs_\bi_\bo_\bn_\bs\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bj_\bu_\bs_\bt_\bi_\bf_\by_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bm_\be_\bm_\bb_\bm_\bp_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bw_\ba_\br_\bp_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_f\bfo\bon\bnt\bt_\b_a\bas\bsc\bce\ben\bnt\bt *\b**\b**\b**\b**\b*\n int al_get_font_ascent(const ALLEGRO_FONT *f)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the ascent of the specified font.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bf_\bo_\bn_\bt_\b__\bd_\be_\bs_\bc_\be_\bn_\bt, _\ba_\bl_\b__\bg_\be_\bt_\b__\bf_\bo_\bn_\bt_\b__\bl_\bi_\bn_\be_\b__\bh_\be_\bi_\bg_\bh_\bt\n+Examples:\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_f\bfo\bon\bnt\bt_\b_d\bde\bes\bsc\bce\ben\bnt\bt *\b**\b**\b**\b**\b*\n int al_get_font_descent(const ALLEGRO_FONT *f)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the descent of the specified font.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bf_\bo_\bn_\bt_\b__\ba_\bs_\bc_\be_\bn_\bt, _\ba_\bl_\b__\bg_\be_\bt_\b__\bf_\bo_\bn_\bt_\b__\bl_\bi_\bn_\be_\b__\bh_\be_\bi_\bg_\bh_\bt\n+Examples:\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_t\bte\bex\bxt\bt_\b_w\bwi\bid\bdt\bth\bh *\b**\b**\b**\b**\b*\n int al_get_text_width(const ALLEGRO_FONT *f, const char *str)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Calculates the length of a string in a particular font, in pixels.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bu_\bs_\bt_\br_\b__\bw_\bi_\bd_\bt_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\bf_\bo_\bn_\bt_\b__\bl_\bi_\bn_\be_\b__\bh_\be_\bi_\bg_\bh_\bt, _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\be_\bx_\bt_\b__\bd_\bi_\bm_\be_\bn_\bs_\bi_\bo_\bn_\bs\n+Examples:\n+ * _\be_\bx_\b__\bd_\bi_\bs_\bp_\bl_\ba_\by_\b__\bo_\bp_\bt_\bi_\bo_\bn_\bs_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bn_\ba_\bm_\be_\b._\bc\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b__\bg_\br_\ba_\bd_\bi_\be_\bn_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_u\bus\bst\btr\br_\b_w\bwi\bid\bdt\bth\bh *\b**\b**\b**\b**\b*\n int al_get_ustr_width(const ALLEGRO_FONT *f, ALLEGRO_USTR const *ustr)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\be_\bx_\bt_\b__\bw_\bi_\bd_\bt_\bh but expects an ALLEGRO_USTR.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\be_\bx_\bt_\b__\bw_\bi_\bd_\bt_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\bu_\bs_\bt_\br_\b__\bd_\bi_\bm_\be_\bn_\bs_\bi_\bo_\bn_\bs\n+Examples:\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_t\bte\bex\bxt\bt *\b**\b**\b**\b**\b*\n void al_draw_text(const ALLEGRO_FONT *font,\n ALLEGRO_COLOR color, float x, float y, int flags,\n char const *text)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Writes the NUL-terminated string text onto the target bitmap at position x, y,\n using the specified font.\n@@ -242,35 +274,45 @@\n It can also be combined with this flag:\n * ALLEGRO_ALIGN_INTEGER - Always draw text aligned to an integer pixel\n position. This was formerly the default behaviour. Since: 5.0.8, 5.1.4\n This function does not support newline characters (\\n), but you can use\n _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b__\bt_\be_\bx_\bt for multi line text output.\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bu_\bs_\bt_\br, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bt_\be_\bx_\bt_\bf, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bj_\bu_\bs_\bt_\bi_\bf_\bi_\be_\bd_\b__\bt_\be_\bx_\bt,\n _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b__\bt_\be_\bx_\bt.\n+Examples:\n+ * _\be_\bx_\b__\bd_\bi_\bs_\ba_\bb_\bl_\be_\b__\bs_\bc_\br_\be_\be_\bn_\bs_\ba_\bv_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\bd_\bw_\ba_\bi_\bt_\b._\bc\n+ * _\be_\bx_\b__\bd_\bi_\bs_\bp_\bl_\ba_\by_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_u\bus\bst\btr\br *\b**\b**\b**\b**\b*\n void al_draw_ustr(const ALLEGRO_FONT *font,\n ALLEGRO_COLOR color, float x, float y, int flags,\n const ALLEGRO_USTR *ustr)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bt_\be_\bx_\bt, except the text is passed as an ALLEGRO_USTR instead of a\n NUL-terminated char array.\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bt_\be_\bx_\bt, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bj_\bu_\bs_\bt_\bi_\bf_\bi_\be_\bd_\b__\bu_\bs_\bt_\br, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b__\bu_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b._\bc_\bp_\bp\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_j\bju\bus\bst\bti\bif\bfi\bie\bed\bd_\b_t\bte\bex\bxt\bt *\b**\b**\b**\b**\b*\n void al_draw_justified_text(const ALLEGRO_FONT *font,\n ALLEGRO_COLOR color, float x1, float x2,\n float y, float diff, int flags, const char *text)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bt_\be_\bx_\bt, but justifies the string to the region x1-x2.\n The diff parameter is the maximum amount of horizontal space to allow between\n words. If justisfying the text would exceed diff pixels, or the string contains\n less than two words, then the string will be drawn left aligned.\n The flags parameter can be 0 or one of the following flags:\n * ALLEGRO_ALIGN_INTEGER - Draw text aligned to integer pixel positions.\n Since: 5.0.8, 5.1.5\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bj_\bu_\bs_\bt_\bi_\bf_\bi_\be_\bd_\b__\bt_\be_\bx_\bt_\bf, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bj_\bu_\bs_\bt_\bi_\bf_\bi_\be_\bd_\b__\bu_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bj_\bu_\bs_\bt_\bi_\bf_\by_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_j\bju\bus\bst\bti\bif\bfi\bie\bed\bd_\b_u\bus\bst\btr\br *\b**\b**\b**\b**\b*\n void al_draw_justified_ustr(const ALLEGRO_FONT *font,\n ALLEGRO_COLOR color, float x1, float x2,\n float y, float diff, int flags, const ALLEGRO_USTR *ustr)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bj_\bu_\bs_\bt_\bi_\bf_\bi_\be_\bd_\b__\bt_\be_\bx_\bt, except the text is passed as an ALLEGRO_USTR\n instead of a NUL-terminated char array.\n@@ -279,14 +321,18 @@\n void al_draw_textf(const ALLEGRO_FONT *font, ALLEGRO_COLOR color,\n float x, float y, int flags,\n const char *format, ...)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Formatted text output, using a printf() style format string. All parameters\n have the same meaning as with _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bt_\be_\bx_\bt otherwise.\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bt_\be_\bx_\bt, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bu_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bd_\bi_\bs_\ba_\bb_\bl_\be_\b__\bs_\bc_\br_\be_\be_\bn_\bs_\ba_\bv_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\bd_\bw_\ba_\bi_\bt_\b._\bc\n+ * _\be_\bx_\b__\bd_\bi_\bs_\bp_\bl_\ba_\by_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_j\bju\bus\bst\bti\bif\bfi\bie\bed\bd_\b_t\bte\bex\bxt\btf\bf *\b**\b**\b**\b**\b*\n void al_draw_justified_textf(const ALLEGRO_FONT *f,\n ALLEGRO_COLOR color, float x1, float x2, float y,\n float diff, int flags, const char *format, ...)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Formatted text output, using a printf() style format string. All parameters\n have the same meaning as with _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bj_\bu_\bs_\bt_\bi_\bf_\bi_\be_\bd_\b__\bt_\be_\bx_\bt otherwise.\n@@ -301,14 +347,17 @@\n information.\n Returned variables (all in pixels):\n * x, y - Offset to upper left corner of bounding box.\n * w, h - Dimensions of bounding box.\n Note that glyphs may go to the left and upwards of the X, in which case x and y\n will have negative values.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\be_\bx_\bt_\b__\bw_\bi_\bd_\bt_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\bf_\bo_\bn_\bt_\b__\bl_\bi_\bn_\be_\b__\bh_\be_\bi_\bg_\bh_\bt, _\ba_\bl_\b__\bg_\be_\bt_\b__\bu_\bs_\bt_\br_\b__\bd_\bi_\bm_\be_\bn_\bs_\bi_\bo_\bn_\bs\n+Examples:\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\bg_\bo_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_u\bus\bst\btr\br_\b_d\bdi\bim\bme\ben\bns\bsi\bio\bon\bns\bs *\b**\b**\b**\b**\b*\n void al_get_ustr_dimensions(const ALLEGRO_FONT *f,\n ALLEGRO_USTR const *ustr,\n int *bbx, int *bby, int *bbw, int *bbh)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\be_\bx_\bt_\b__\bd_\bi_\bm_\be_\bn_\bs_\bi_\bo_\bn_\bs, except the text is passed as an ALLEGRO_USTR\n instead of a NUL-terminated char array.\n@@ -327,22 +376,26 @@\n ranges should be an array with room for ranges_count * 2 elements. The even\n integers are the first unicode point in a range, the odd integers the last\n unicode point in a range.\n Returns the number of ranges contained in the font (even if it is bigger than\n ranges_count).\n Since: 5.1.4\n See also: _\ba_\bl_\b__\bg_\br_\ba_\bb_\b__\bf_\bo_\bn_\bt_\b__\bf_\br_\bo_\bm_\b__\bb_\bi_\bt_\bm_\ba_\bp\n+Examples:\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_f\bfa\bal\bll\blb\bba\bac\bck\bk_\b_f\bfo\bon\bnt\bt *\b**\b**\b**\b**\b*\n void al_set_fallback_font(ALLEGRO_FONT *font, ALLEGRO_FONT *fallback)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets a font which is used instead if a character is not present. Can be\n chained, but make sure there is no loop as that would crash the application!\n Pass NULL to remove a fallback font again.\n Since: 5.1.12\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bf_\ba_\bl_\bl_\bb_\ba_\bc_\bk_\b__\bf_\bo_\bn_\bt, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bg_\bl_\by_\bp_\bh, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bt_\be_\bx_\bt\n+Examples:\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_f\bfa\bal\bll\blb\bba\bac\bck\bk_\b_f\bfo\bon\bnt\bt *\b**\b**\b**\b**\b*\n ALLEGRO_FONT *al_get_fallback_font(ALLEGRO_FONT *font)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Retrieves the fallback font for this font or NULL.\n Since: 5.1.12\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bf_\ba_\bl_\bl_\bb_\ba_\bc_\bk_\b__\bf_\bo_\bn_\bt\n *\b**\b**\b**\b**\b**\b* P\bPe\ber\br g\bgl\bly\byp\bph\bh t\bte\bex\bxt\bt h\bha\ban\bnd\bdl\bli\bin\bng\bg *\b**\b**\b**\b**\b**\b*\n@@ -369,14 +422,17 @@\n to determine the size and position of each glyph.\n If you have to draw many glyphs at the same time, use _\ba_\bl_\b__\bh_\bo_\bl_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bd_\br_\ba_\bw_\bi_\bn_\bg\n with true as the parameter, before drawing the glyphs, and then call\n _\ba_\bl_\b__\bh_\bo_\bl_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bd_\br_\ba_\bw_\bi_\bn_\bg again with false as a parameter when done drawing the\n glyphs to further enhance performance.\n Since: 5.1.12\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bg_\bl_\by_\bp_\bh_\b__\bw_\bi_\bd_\bt_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\bg_\bl_\by_\bp_\bh_\b__\bd_\bi_\bm_\be_\bn_\bs_\bi_\bo_\bn_\bs, _\ba_\bl_\b__\bg_\be_\bt_\b__\bg_\bl_\by_\bp_\bh_\b__\ba_\bd_\bv_\ba_\bn_\bc_\be.\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b._\bc\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_g\bgl\bly\byp\bph\bh_\b_w\bwi\bid\bdt\bth\bh *\b**\b**\b**\b**\b*\n int al_get_glyph_width(const ALLEGRO_FONT *f, int codepoint)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This function returns the width in pixels of the glyph that corresponds with\n codepoint in the font font. Returns zero if the font does not have such a\n glyph.\n Since: 5.1.12\n@@ -423,14 +479,16 @@\n +---+--------+ | | ***** |\n | | *|\n | | * *|\n v | **** |\n +---+-------+\n Since: 5.1.12\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bg_\bl_\by_\bp_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\bg_\bl_\by_\bp_\bh_\b__\bw_\bi_\bd_\bt_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\bg_\bl_\by_\bp_\bh_\b__\ba_\bd_\bv_\ba_\bn_\bc_\be.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_g\bgl\bly\byp\bph\bh_\b_a\bad\bdv\bva\ban\bnc\bce\be *\b**\b**\b**\b**\b*\n int al_get_glyph_advance(const ALLEGRO_FONT *f, int codepoint1, int codepoint2)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This function returns by how much the x position should be advanced for left to\n right text drawing when the glyph that corresponds to codepoint1 has been\n drawn, and the glyph that corresponds to codepoint2 will be the next to be\n drawn. This takes into consideration the horizontal advance width of the glyph\n@@ -482,14 +540,17 @@\n / \\ |\n /____\\ |\n / \\ |\n / \\ \\_\n ---------------\n Since: 5.1.12\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bg_\bl_\by_\bp_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\bg_\bl_\by_\bp_\bh_\b__\bw_\bi_\bd_\bt_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\bg_\bl_\by_\bp_\bh_\b__\bd_\bi_\bm_\be_\bn_\bs_\bi_\bo_\bn_\bs.\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b._\bc\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b**\b* M\bMu\bul\blt\bti\bil\bli\bin\bne\be t\bte\bex\bxt\bt d\bdr\bra\baw\bwi\bin\bng\bg *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_m\bmu\bul\blt\bti\bil\bli\bin\bne\be_\b_t\bte\bex\bxt\bt *\b**\b**\b**\b**\b*\n void al_draw_multiline_text(const ALLEGRO_FONT *font,\n ALLEGRO_COLOR color, float x, float y, float max_width, float line_height,\n int flags, const char *text)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bt_\be_\bx_\bt, but this function supports drawing multiple lines of text.\n@@ -516,14 +577,17 @@\n The flags ALLEGRO_ALIGN_LEFT, ALLEGRO_ALIGN_CENTRE, ALLEGRO_ALIGN_RIGHT and\n ALLEGRO_ALIGN_INTEGER will be honoured by this function.\n If you want to calculate the size of what this function will draw without\n actually drawing it, or if you need a complex and/or custom layout, you can use\n _\ba_\bl_\b__\bd_\bo_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b__\bt_\be_\bx_\bt.\n Since: 5.1.9\n See also: _\ba_\bl_\b__\bd_\bo_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b__\bt_\be_\bx_\bt, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b__\bu_\bs_\bt_\br, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b__\bt_\be_\bx_\bt_\bf\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\br_\be_\bs_\bi_\bz_\be_\b2_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_m\bmu\bul\blt\bti\bil\bli\bin\bne\be_\b_u\bus\bst\btr\br *\b**\b**\b**\b**\b*\n void al_draw_multiline_ustr(const ALLEGRO_FONT *font,\n ALLEGRO_COLOR color, float x, float y, float max_width, float line_height,\n int flags, const ALLEGRO_USTR *ustr)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b__\bt_\be_\bx_\bt, except the text is passed as an ALLEGRO_USTR\n instead of a NUL-terminated char array.\n@@ -534,14 +598,16 @@\n ALLEGRO_COLOR color, float x, float y, float max_width, float line_height,\n int flags, const char *format, ...)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Formatted text output, using a printf() style format string. All parameters\n have the same meaning as with _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b__\bt_\be_\bx_\bt otherwise.\n Since: 5.1.9\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b__\bt_\be_\bx_\bt, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b__\bu_\bs_\bt_\br, _\ba_\bl_\b__\bd_\bo_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b__\bt_\be_\bx_\bt\n+Examples:\n+ * _\be_\bx_\b__\br_\be_\bs_\bi_\bz_\be_\b2_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdo\bo_\b_m\bmu\bul\blt\bti\bil\bli\bin\bne\be_\b_t\bte\bex\bxt\bt *\b**\b**\b**\b**\b*\n void al_do_multiline_text(const ALLEGRO_FONT *font,\n float max_width, const char *text,\n bool (*cb)(int line_num, const char *line, int size, void *extra),\n void *extra)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This function processes the text and splits it into lines as\n@@ -561,14 +627,16 @@\n buffer and NUL-terminate it yourself. You will also have to make your own copy\n if you need the contents of line after cb has returned, as line is n\bno\bot\bt\n guaranteed to be valid after that.\n If the callback cb returns false, al_do_multiline_text will stop immediately,\n otherwise it will continue on to the next line.\n Since: 5.1.9\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b__\bt_\be_\bx_\bt\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdo\bo_\b_m\bmu\bul\blt\bti\bil\bli\bin\bne\be_\b_u\bus\bst\btr\br *\b**\b**\b**\b**\b*\n void al_do_multiline_ustr(const ALLEGRO_FONT *font, float max_width,\n const ALLEGRO_USTR *ustr,\n bool (*cb)(int line_num, const ALLEGRO_USTR * line, void *extra),\n void *extra)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bd_\bo_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b__\bt_\be_\bx_\bt, but using ALLEGRO_USTR instead of a NUL-terminated\n@@ -621,23 +689,30 @@\n The first example will grab glyphs for the 95 standard printable ASCII\n characters, beginning with the space character (32) and ending with the tilde\n character (126). The second example will map the first 96 glyphs found in the\n bitmap to ASCII range, the next 95 glyphs to Latin 1, the next 128 glyphs to\n Extended-A, and the last glyph to the Euro character. (This is just the\n characters found in the Allegro 4 font.)\n See also: _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bg_\br_\ba_\bb_\b__\bf_\bo_\bn_\bt_\b__\bf_\br_\bo_\bm_\b__\bb_\bi_\bt_\bm_\ba_\bp\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b._\bc\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boa\bad\bd_\b_b\bbi\bit\btm\bma\bap\bp_\b_f\bfo\bon\bnt\bt *\b**\b**\b**\b**\b*\n ALLEGRO_FONT *al_load_bitmap_font(const char *fname)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Load a bitmap font from a file. This is done by first calling\n _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs and then _\ba_\bl_\b__\bg_\br_\ba_\bb_\b__\bf_\bo_\bn_\bt_\b__\bf_\br_\bo_\bm_\b__\bb_\bi_\bt_\bm_\ba_\bp.\n If you wanted to load an old A4 font, for example, it would be better to load\n the bitmap yourself in order to call _\ba_\bl_\b__\bc_\bo_\bn_\bv_\be_\br_\bt_\b__\bm_\ba_\bs_\bk_\b__\bt_\bo_\b__\ba_\bl_\bp_\bh_\ba on it before\n passing it to _\ba_\bl_\b__\bg_\br_\ba_\bb_\b__\bf_\bo_\bn_\bt_\b__\bf_\br_\bo_\bm_\b__\bb_\bi_\bt_\bm_\ba_\bp.\n See also: _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bo_\bn_\bt_\b__\bf_\bl_\ba_\bg_\bs, _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bf_\bo_\bn_\bt, _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs\n+Examples:\n+ * _\be_\bx_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\bi_\bp_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bn_\ba_\bm_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boa\bad\bd_\b_b\bbi\bit\btm\bma\bap\bp_\b_f\bfo\bon\bnt\bt_\b_f\bfl\bla\bag\bgs\bs *\b**\b**\b**\b**\b*\n ALLEGRO_FONT *al_load_bitmap_font_flags(const char *fname, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bo_\bn_\bt but additionally takes a flags parameter which is a\n bitfield containing a combination of the following:\n ALLEGRO_NO_PREMULTIPLIED_ALPHA\n The same meaning as for _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs.\n@@ -655,24 +730,32 @@\n 0x0100 to 0x017F (Extended A)\n 0x20AC to 0x20AC (euro currency symbol)\n Returns NULL on an error.\n The font memory must be freed the same way as for any other font, using\n _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bf_\bo_\bn_\bt.\n Since: 5.0.8, 5.1.3\n See also: _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bo_\bn_\bt, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bf_\bo_\bn_\bt\n+Examples:\n+ * _\be_\bx_\b__\bd_\bi_\bs_\ba_\bb_\bl_\be_\b__\bs_\bc_\br_\be_\be_\bn_\bs_\ba_\bv_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\bd_\bw_\ba_\bi_\bt_\b._\bc\n+ * _\be_\bx_\b__\bd_\bi_\bs_\bp_\bl_\ba_\by_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* T\bTT\bTF\bF f\bfo\bon\bnt\bts\bs *\b**\b**\b**\b**\b**\b*\n These functions are declared in the following header file. Link with\n allegro_ttf.\n #include \n *\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bni\bit\bt_\b_t\btt\btf\bf_\b_a\bad\bdd\bdo\bon\bn *\b**\b**\b**\b**\b*\n bool al_init_ttf_addon(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Call this after _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bf_\bo_\bn_\bt_\b__\ba_\bd_\bd_\bo_\bn to make _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bf_\bo_\bn_\bt recognize \u201c.ttf\u201d and\n other formats supported by _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bt_\bt_\bf_\b__\bf_\bo_\bn_\bt.\n Returns true on success, false on failure.\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bj_\bu_\bs_\bt_\bi_\bf_\by_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_t\btt\btf\bf_\b_a\bad\bdd\bdo\bon\bn_\b_i\bin\bni\bit\bti\bia\bal\bli\biz\bze\bed\bd *\b**\b**\b**\b**\b*\n bool al_is_ttf_addon_initialized(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if the TTF addon is initialized, otherwise returns false.\n Since: 5.2.6\n See also: _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bt_\bt_\bf_\b__\ba_\bd_\bd_\bo_\bn, _\ba_\bl_\b__\bs_\bh_\bu_\bt_\bd_\bo_\bw_\bn_\b__\bt_\bt_\bf_\b__\ba_\bd_\bd_\bo_\bn\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bsh\bhu\but\btd\bdo\bow\bwn\bn_\b_t\btt\btf\bf_\b_a\bad\bdd\bdo\bon\bn *\b**\b**\b**\b**\b*\n@@ -695,14 +778,18 @@\n * ALLEGRO_TTF_NO_KERNING - Do not use any kerning even if the font file\n supports it.\n * ALLEGRO_TTF_MONOCHROME - Load as a monochrome font (which means no anti-\n aliasing of the font is done).\n * ALLEGRO_TTF_NO_AUTOHINT - Disable the Auto Hinter which is enabled by\n default in newer versions of FreeType. Since: 5.0.6, 5.1.2\n See also: _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bt_\bt_\bf_\b__\ba_\bd_\bd_\bo_\bn, _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bt_\bt_\bf_\b__\bf_\bo_\bn_\bt_\b__\bf\n+Examples:\n+ * _\be_\bx_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\bi_\bp_\b._\bc\n+ * _\be_\bx_\b__\bs_\by_\bn_\bt_\bh_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boa\bad\bd_\b_t\btt\btf\bf_\b_f\bfo\bon\bnt\bt_\b_f\bf *\b**\b**\b**\b**\b*\n ALLEGRO_FONT *al_load_ttf_font_f(ALLEGRO_FILE *file,\n char const *filename, int size, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bt_\bt_\bf_\b__\bf_\bo_\bn_\bt, but the font is read from the file handle. The filename\n is only used to find possible additional files next to a font file.\n N\bNo\bot\bte\be:\b: The file handle is owned by the returned ALLEGRO_FONT object\n@@ -747,8 +834,11 @@\n yourself. prev_codepoint is the codepoint in the string before the one you want\n to draw and is used for kerning. codepoint is the character you want to get\n info about. You should clear the \u2018glyph\u2019 structure to 0 with memset before\n passing it to this function for future compatibility.\n Since: 5.2.1\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: This API is new and subject to refinement.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bG_\bL_\bY_\bP_\bH\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b._\bc\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/fshook.html", "source2": "./usr/share/doc/allegro5-doc/refman/fshook.html", "unified_diff": "@@ -250,14 +250,21 @@\n

    Source\n Code

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_dir.c
      • \n+
    • ex_physfs.c
      • \n+
    \n

    ALLEGRO_FILE_MODE

    \n 
    typedef enum ALLEGRO_FILE_MODE
    \n

    Source\n Code

    \n

    Filesystem modes/types

    \n
      \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -79,14 +79,17 @@\n filesystem like your harddrive, or a virtual filesystem like a .zip archive (or\n whatever else you or an addon makes it do).\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_F\bFS\bS_\b_E\bEN\bNT\bTR\bRY\bY *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_FS_ENTRY ALLEGRO_FS_ENTRY;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Opaque filesystem entry object. Represents a file or a directory (check with\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bf_\bs_\b__\be_\bn_\bt_\br_\by_\b__\bm_\bo_\bd_\be). There are no user accessible member variables.\n+Examples:\n+ * _\be_\bx_\b__\bd_\bi_\br_\b._\bc\n+ * _\be_\bx_\b__\bp_\bh_\by_\bs_\bf_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_F\bFI\bIL\bLE\bE_\b_M\bMO\bOD\bDE\bE *\b**\b**\b**\b**\b**\b*\n typedef enum ALLEGRO_FILE_MODE\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Filesystem modes/types\n * ALLEGRO_FILEMODE_READ - Readable\n * ALLEGRO_FILEMODE_WRITE - Writable\n * ALLEGRO_FILEMODE_EXECUTE - Executable\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/fullscreen_mode.html", "source2": "./usr/share/doc/allegro5-doc/refman/fullscreen_mode.html", "unified_diff": "@@ -197,14 +197,21 @@\n int refresh_rate; // The refresh rate of the mode\n } ALLEGRO_DISPLAY_MODE;\n

      The refresh_rate may be zero if unknown.

      \n

      For an explanation of what format means, see ALLEGRO_PIXEL_FORMAT.

      \n

      See also: al_get_display_mode

      \n+

      Examples:

      \n+
        \n+
      • ex_monitorinfo.c
        • \n+
      • ex_display_options.c
        • \n+
      \n

      al_get_display_mode

      \n 
      ALLEGRO_DISPLAY_MODE *al_get_display_mode(int index, ALLEGRO_DISPLAY_MODE *mode)
      \n

      Source\n Code

      \n

      Retrieves a fullscreen mode. Display parameters should not be changed\n between a call of Source\n Code

      \n

      An ALLEGRO_COLOR structure describes a color in a device independent\n way. Use al_map_rgb et al.\u00a0and al_unmap_rgb et al.\u00a0to translate\n from and to various color representations.

      \n+

      Examples:

      \n+
        \n+
      • ex_keyboard_focus.c
        • \n+
      • ex_nodisplay.c
        • \n+
      • ex_mouse_focus.c
        • \n+
      \n

      al_map_rgb

      \n 
      ALLEGRO_COLOR al_map_rgb(\n    unsigned char r, unsigned char g, unsigned char b)
      \n

      Source\n Code

      \n

      Convert r, g, b (ranging from 0-255) into an ALLEGRO_COLOR, using 255 for\n alpha.

      \n

      This function can be called before Allegro is initialized.

      \n

      See also: al_map_rgba, al_map_rgba_f, al_map_rgb_f

      \n+

      Examples:

      \n+
        \n+
      • ex_enet_server.c
        • \n+
      • ex_keyboard_focus.c
        • \n+
      • ex_nodisplay.c
        • \n+
      \n

      al_map_rgb_f

      \n 
      ALLEGRO_COLOR al_map_rgb_f(float r, float g, float b)
      \n

      Source\n Code

      \n

      Convert r, g, b, (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR, using 1.0f for\n alpha.

      \n

      This function can be called before Allegro is initialized.

      \n

      See also: al_map_rgba, al_map_rgb, al_map_rgba_f

      \n+

      Examples:

      \n+
        \n+
      • ex_enet_server.c
        • \n+
      • ex_keyboard_events.c
        • \n+
      • ex_drawpixels.c
        • \n+
      \n

      al_map_rgba

      \n 
      ALLEGRO_COLOR al_map_rgba(\n    unsigned char r, unsigned char g, unsigned char b, unsigned char a)
      \n

      Source\n Code

      \n

      Convert r, g, b, a (ranging from 0-255) into an ALLEGRO_COLOR.

      \n

      This function can be called before Allegro is initialized.

      \n

      See also: al_map_rgb, al_premul_rgba, al_map_rgb_f

      \n+

      Examples:

      \n+
        \n+
      • ex_nodisplay.c
        • \n+
      • ex_drawpixels.c
        • \n+
      • ex_timedwait.c
        • \n+
      \n

      al_premul_rgba

      \n 
      ALLEGRO_COLOR al_premul_rgba(\n    unsigned char r, unsigned char g, unsigned char b, unsigned char a)
      \n

      Source\n Code

      \n

      This is a shortcut for

      \n

      Convert r, g, b, a (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR.

      \n

      This function can be called before Allegro is initialized.

      \n

      See also: al_map_rgba, al_premul_rgba_f, al_map_rgb_f

      \n+

      Examples:

      \n+
        \n+
      • ex_timedwait.c
        • \n+
      • ex_resize.c
        • \n+
      • ex_rotate.c
        • \n+
      \n

      al_premul_rgba_f

      \n 
      ALLEGRO_COLOR al_premul_rgba_f(float r, float g, float b, float a)
      \n

      Source\n Code

      \n

      This is a shortcut for al_map_rgba_f(r * a, g * a, b *\n@@ -562,52 +607,82 @@\n Code

      \n

      Retrieves components of an ALLEGRO_COLOR, ignoring alpha. Components\n will range from 0-255.

      \n

      This function can be called before Allegro is initialized.

      \n

      See also: al_unmap_rgba, al_unmap_rgba_f, al_unmap_rgb_f

      \n+

      Examples:

      \n+
        \n+
      • ex_blend_test.c
        • \n+
      • ex_haiku.c
        • \n+
      • ex_color_gradient.c
        • \n+
      \n

      al_unmap_rgb_f

      \n 
      void al_unmap_rgb_f(ALLEGRO_COLOR color, float *r, float *g, float *b)
      \n

      Source\n Code

      \n

      Retrieves components of an ALLEGRO_COLOR, ignoring alpha.\n Components will range from 0.0f-1.0f.

      \n

      This function can be called before Allegro is initialized.

      \n

      See also: al_unmap_rgba, al_unmap_rgb, al_unmap_rgba_f

      \n+

      Examples:

      \n+
        \n+
      • ex_haiku.c
        • \n+
      • ex_color_gradient.c
        • \n+
      \n

      al_unmap_rgba

      \n 
      void al_unmap_rgba(ALLEGRO_COLOR color,\n    unsigned char *r, unsigned char *g, unsigned char *b, unsigned char *a)
      \n

      Source\n Code

      \n

      Retrieves components of an ALLEGRO_COLOR. Components will\n range from 0-255.

      \n

      This function can be called before Allegro is initialized.

      \n

      See also: al_unmap_rgb, al_unmap_rgba_f, al_unmap_rgb_f

      \n+

      Examples:

      \n+
        \n+
      • ex_blend_test.c
        • \n+
      • ex_logo.c
        • \n+
      \n

      al_unmap_rgba_f

      \n 
      void al_unmap_rgba_f(ALLEGRO_COLOR color,\n    float *r, float *g, float *b, float *a)
      \n

      Source\n Code

      \n

      Retrieves components of an ALLEGRO_COLOR. Components will\n range from 0.0f-1.0f.

      \n

      This function can be called before Allegro is initialized.

      \n

      See also: al_unmap_rgba, al_unmap_rgb, al_unmap_rgb_f

      \n+

      Examples:

      \n+
        \n+
      • ex_blend_test.c
        • \n+
      • ex_logo.c
        • \n+
      \n

      Locking and pixel formats

      \n

      ALLEGRO_LOCKED_REGION

      \n 
      typedef struct ALLEGRO_LOCKED_REGION ALLEGRO_LOCKED_REGION;
      \n

      Source\n Code

      \n

      Users who wish to manually edit or read from a bitmap are required to\n@@ -637,14 +712,23 @@\n this is just the size of a single pixel, but for blocked pixel formats\n this value is different.

      \n
    \n

    See also: al_lock_bitmap,\n al_lock_bitmap_region,\n al_unlock_bitmap, ALLEGRO_PIXEL_FORMAT

    \n+

    Examples:

    \n+
      \n+
    • ex_lockbitmap.c
      • \n+
    • ex_premulalpha.c
      • \n+
    • ex_multisample.c
      • \n+
    \n

    ALLEGRO_PIXEL_FORMAT

    \n 
    typedef enum ALLEGRO_PIXEL_FORMAT
    \n

    Source\n Code

    \n

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

    See also: al_set_new_bitmap_format,\n al_get_bitmap_format

    \n+

    Examples:

    \n+
      \n+
    • ex_convert.c
      • \n+
    • ex_drawpixels.c
      • \n+
    • ex_lockbitmap.c
      • \n+
    \n

    al_get_pixel_size

    \n 
    int al_get_pixel_size(int format)
    \n

    Source\n Code

    \n

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

    \n@@ -799,26 +892,36 @@\n

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

    \n

    Since: 5.1.9.

    \n

    See also: ALLEGRO_PIXEL_FORMAT, al_get_pixel_block_size,\n al_get_pixel_block_height

    \n+

    Examples:

    \n+
      \n+
    • ex_compressed.c
      • \n+
    \n

    al_get_pixel_block_height

    \n 
    int al_get_pixel_block_height(int format)
    \n

    Source\n Code

    \n

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

    \n

    Since: 5.1.9.

    \n

    See also: ALLEGRO_PIXEL_FORMAT, al_get_pixel_block_size,\n al_get_pixel_block_width

    \n+

    Examples:

    \n+
      \n+
    • ex_compressed.c
      • \n+
    \n

    al_lock_bitmap

    \n 
    ALLEGRO_LOCKED_REGION *al_lock_bitmap(ALLEGRO_BITMAP *bitmap,\n    int format, int flags)
    \n

    Source\n Code

    \n

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

    Examples:

    \n
      \n
    • ex_drawpixels.c
      • \n
    • ex_membmp.c
      • \n
    • ex_blend.c
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_lockbitmap.c#L32\">ex_lockbitmap.c\n
    \n

    al_lock_bitmap_region

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

    Source\n Code

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

    \n

    Examples:

    \n
      \n
    • ex_lockbitmap.c
      • \n
    • ex_threads2.c
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_compressed.c#L114\">ex_compressed.c\n
    • ex_blit.c
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_threads2.c#L120\">ex_threads2.c\n
    \n

    al_unlock_bitmap

    \n 
    void al_unlock_bitmap(ALLEGRO_BITMAP *bitmap)
    \n

    Source\n Code

    \n

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

    \n

    Examples:

    \n
      \n
    • ex_drawpixels.c
      • \n
    • ex_blend.c
      • \n-
    • ex_lockbitmap.c
      • \n+
    • ex_premulalpha.c
      • \n
    \n

    al_lock_bitmap_blocked

    \n 
    ALLEGRO_LOCKED_REGION *al_lock_bitmap_blocked(ALLEGRO_BITMAP *bitmap,\n    int flags)
    \n

    Source\n Code

    \n@@ -985,14 +1088,23 @@\n

    Bitmap creation

    \n

    ALLEGRO_BITMAP

    \n 
    typedef struct ALLEGRO_BITMAP ALLEGRO_BITMAP;
    \n

    Source\n Code

    \n

    Abstract type representing a bitmap (2D image).

    \n+

    Examples:

    \n+
      \n+
    • ex_convert.c
      • \n+
    • ex_nodisplay.c
      • \n+
    • ex_opengl_pixel_shader.c
      • \n+
    \n

    al_create_bitmap

    \n 
    ALLEGRO_BITMAP *al_create_bitmap(int w, int h)
    \n

    Source\n Code

    \n

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

    \n

    Examples:

    \n
      \n
    • ex_opengl_pixel_shader.c
      • \n-
    • ex_nodisplay.c
      • \n
    • ex_lines.c
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_opengl_pixel_shader.c#L66\">ex_opengl_pixel_shader.c\n+
    • ex_icon2.c
      • \n
    \n

    al_create_sub_bitmap

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

    Source\n Code

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

    \n

    See also: al_create_bitmap

    \n

    Examples:

    \n
      \n
    • ex_shader_target.c
      • \n-
    • ex_blend_target.c
      • \n
    • ex_multisample_target.c
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_subbitmap.c#L145\">ex_subbitmap.c\n+
    • ex_shader_target.c
      • \n
    \n

    al_clone_bitmap

    \n 
    ALLEGRO_BITMAP *al_clone_bitmap(ALLEGRO_BITMAP *bitmap)
    \n

    Source\n Code

    \n

    Create a new bitmap with al_set_new_bitmap_format,\n al_set_new_bitmap_flags,\n al_convert_bitmap

    \n

    Examples:

    \n
      \n
    • ex_premulalpha.c
      • \n-
    • ex_blend2.cpp
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_subbitmap.c#L266\">ex_subbitmap.c\n
    • ex_font.c
      • \n+
    • ex_premulalpha.c
      • \n
    \n

    al_convert_bitmap

    \n 
    void al_convert_bitmap(ALLEGRO_BITMAP *bitmap)
    \n

    Source\n Code

    \n

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

    int al_get_new_bitmap_flags(void)
    \n

    Source\n Code

    \n

    Returns the flags used for newly created bitmaps.

    \n

    See also: al_set_new_bitmap_flags

    \n+

    Examples:

    \n+
      \n+
    • ex_prim.c
      • \n+
    \n

    al_get_new_bitmap_format

    \n 
    int al_get_new_bitmap_format(void)
    \n

    Source\n Code

    \n

    Returns the format used for newly created bitmaps.

    \n

    See also: \n \n \n

    See also: al_get_new_bitmap_flags,\n al_get_bitmap_flags

    \n+

    Examples:

    \n+
      \n+
    • ex_convert.c
      • \n+
    • ex_blend_bench.c
      • \n+
    • ex_icon2.c
      • \n+
    \n

    al_add_new_bitmap_flag

    \n 
    void al_add_new_bitmap_flag(int flag)
    \n

    Source\n Code

    \n

    A convenience function which does the same as

    \n 
    al_set_new_bitmap_flags(al_get_new_bitmap_flags() | flag);
    \n

    See also: al_set_new_bitmap_flags,\n al_get_new_bitmap_flags,\n al_get_bitmap_flags

    \n+

    Examples:

    \n+
      \n+
    • ex_blend2.cpp
      • \n+
    \n

    al_set_new_bitmap_format

    \n 
    void al_set_new_bitmap_format(int format)
    \n

    Source\n Code

    \n

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

    \n

    See also: ALLEGRO_PIXEL_FORMAT, al_get_new_bitmap_format,\n al_get_bitmap_format

    \n+

    Examples:

    \n+
      \n+
    • ex_convert.c
      • \n+
    • ex_pixelformat.cpp
      • \n+
    • ex_blend_test.c
      • \n+
    \n

    al_set_new_bitmap_depth

    \n 
    void al_set_new_bitmap_depth(int depth)\n SETTER(new_bitmap_depth, depth)
    \n

    Source\n Code

    \n

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

    \n

    Since: 5.2.1

    \n
    \n

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

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_depth_target.c
      • \n+
    \n

    al_get_new_bitmap_depth

    \n 
    int al_get_new_bitmap_depth(void)\n GETTER(new_bitmap_depth, 0)
    \n

    Source\n Code

    \n

    Returns the value currently set with \n

    Since: 5.2.1

    \n
    \n

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

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_multisample_target.c
      • \n+
    • ex_depth_target.c
      • \n+
    \n

    al_get_new_bitmap_samples

    \n 
    int al_get_new_bitmap_samples(void)\n GETTER(new_bitmap_samples, 0)
    \n

    Source\n Code

    \n

    Returns the value currently set with Since: 5.2.8

    \n
    \n

    Unstable\n API: This is an experimental feature.

    \n
    \n

    See also: ALLEGRO_BITMAP_WRAP

    \n+

    Examples:

    \n+
      \n+
    • ex_prim_wrap.c
      • \n+
    • ex_prim.c
      • \n+
    \n

    al_get_new_bitmap_wrap

    \n

    Source Code

    \n

    Returns the value currently set with al_set_new_bitmap_wrap\n on the current thread.

    \n

    Since: 5.2.8

    \n
    \n@@ -1463,14 +1622,21 @@\n

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

    • \n

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

    • \n

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

    • \n \n+

    Examples:

    \n+
      \n+
    • ex_prim_wrap.c
      • \n+
    • ex_prim.c
      • \n+
    \n

    Bitmap properties

    \n

    al_get_bitmap_flags

    \n 
    int al_get_bitmap_flags(ALLEGRO_BITMAP *bitmap)
    \n

    Source\n Code

    \n

    Return the flags used to create the bitmap.

    \n@@ -1504,34 +1670,34 @@\n

    Source\n Code

    \n

    Returns the height of a bitmap in pixels.

    \n

    Examples:

    \n
      \n
    • ex_color.cpp
      • \n-
    • ex_joystick_events.c
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_multiwin.c#L104\">ex_multiwin.c\n
    • ex_resize.c
      • \n+
    • ex_membmp.c
      • \n
    \n

    al_get_bitmap_width

    \n 
    int al_get_bitmap_width(ALLEGRO_BITMAP *bitmap)
    \n

    Source\n Code

    \n

    Returns the width of a bitmap in pixels.

    \n

    Examples:

    \n
      \n
    • ex_color.cpp
      • \n-
    • ex_font_justify.cpp
      • \n
    • ex_joystick_events.c
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_multiwin.c#L103\">ex_multiwin.c\n+
    • ex_resize.c
      • \n
    \n

    al_get_bitmap_depth

    \n 
    int al_get_bitmap_depth(ALLEGRO_BITMAP *bitmap)
    \n

    Source\n Code

    \n

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

    \n

    Examples:

    \n
      \n
    • ex_blend_test.c
      • \n
    • ex_vertex_buffer.c
      • \n-
    • ex_compressed.c
      • \n+
    • ex_vertex_buffer.c
      • \n
    \n

    al_is_bitmap_locked

    \n 
    bool al_is_bitmap_locked(ALLEGRO_BITMAP *bitmap)
    \n

    Source\n Code

    \n

    Returns whether or not a bitmap is already locked.

    \n@@ -1683,17 +1849,17 @@\n

    See also: al_create_sub_bitmap, al_get_parent_bitmap

    \n

    Since: 5.1.12

    \n

    Examples:

    \n
      \n
    • ex_multisample_target.c
      • \n-
    • ex_reparent.c
      • \n+
    • ex_multisample_target.c
      • \n
    \n

    al_get_bitmap_blender

    \n 
    void al_get_bitmap_blender(int *op, int *src, int *dst)
    \n

    Source\n Code

    \n

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

    See also: ALLEGRO_COLOR, al_set_clipping_rectangle,\n al_clear_depth_buffer

    \n

    Examples:

    \n
      \n
    • ex_audio_props.cpp
      • \n-
    • ex_keyboard_focus.c
      • \n
    • ex_font_multiline.cpp
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_nodisplay.c#L41\">ex_nodisplay.c\n+
    • ex_mouse_focus.c
      • \n
    \n

    al_clear_depth_buffer

    \n 
    void al_clear_depth_buffer(float z)
    \n

    Source\n Code

    \n

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

    \n

    Examples:

    \n
      \n
    • ex_depth_target.c
      • \n-
    • ex_depth_mask.c
      • \n
    • ex_camera.c
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_depth_target.c#L34\">ex_depth_target.c\n+
    • ex_projection2.c
      • \n
    \n

    al_draw_bitmap

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

    Source\n Code

    \n

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

    \n

    Examples:

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

    al_draw_tinted_bitmap

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

    Source\n Code

    \n@@ -1941,15 +2107,15 @@\n

    See also: al_draw_bitmap

    \n

    Examples:

    \n
      \n
    • ex_nodisplay.c
      • \n
    • ex_shader_target.c
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_expose.c#L79\">ex_expose.c\n
    • ex_bitmap_flip.c
      • \n
    \n

    al_draw_bitmap_region

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

    al_draw_rotated_bitmap,\n al_draw_scaled_rotated_bitmap

    \n

    Examples:

    \n
      \n
    • ex_blend.c
      • \n-
    • ex_font.c
      • \n
    • ex_clip.c
      • \n+
    • ex_blit.c
      • \n
    \n

    al_draw_tinted_bitmap_region

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

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

    \n

    See also: al_draw_tinted_bitmap

    \n

    Examples:

    \n
      \n
    • ex_ttf.c
      • \n-
    • ex_transform.c
      • \n+
    • ex_ttf.c
      • \n
    \n

    al_draw_pixel

    \n 
    void al_draw_pixel(float x, float y, ALLEGRO_COLOR color)
    \n

    Source\n Code

    \n

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

    \n

    Examples:

    \n
      \n
    • ex_drawpixels.c
      • \n
    • ex_resample_test.c
      • \n-
    • ex_blend_test.c
      • \n+
    • ex_resample_test.c
      • \n
    \n

    al_draw_rotated_bitmap

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

    Source\n Code

    \n@@ -2076,17 +2242,17 @@\n al_draw_scaled_rotated_bitmap

    \n

    Examples:

    \n
      \n
    • ex_blend2.cpp
      • \n
    • ex_multisample_target.c
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_multisample.c#L103\">ex_multisample.c\n
    • ex_palette.c
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_multisample_target.c#L111\">ex_multisample_target.c\n
    \n al_draw_tinted_rotated_bitmap\n 
    void al_draw_tinted_rotated_bitmap(ALLEGRO_BITMAP *bitmap,\n    ALLEGRO_COLOR tint,\n    float cx, float cy, float dx, float dy, float angle, int flags)
    \n

    al_draw_rotated_bitmap

    \n

    Examples:

    \n
      \n
    • ex_blend_bench.c
      • \n
    • ex_premulalpha.c
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_bitmap.c#L151\">ex_bitmap.c\n
    • ex_shader_multitex.c
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_bitmap_file.c#L160\">ex_bitmap_file.c\n
    \n al_draw_tinted_scaled_rotated_bitmap\n 
    void al_draw_tinted_scaled_rotated_bitmap(ALLEGRO_BITMAP *bitmap,\n    ALLEGRO_COLOR tint,\n    float cx, float cy, float dx, float dy, float xscale, float yscale,\n    float angle, int flags)
    \n@@ -2227,15 +2393,15 @@\n

    Examples:

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

    al_draw_tinted_scaled_bitmap

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

    ALLEGRO_BITMAP *al_get_target_bitmap(void)
    \n

    Source\n Code

    \n

    Return the target bitmap of the calling thread.

    \n

    See also: al_set_target_bitmap

    \n+

    Examples:

    \n+
      \n+
    • ex_font_justify.cpp
      • \n+
    • ex_resize.c
      • \n+
    • ex_membmp.c
      • \n+
    \n

    al_put_pixel

    \n 
    void al_put_pixel(int x, int y, ALLEGRO_COLOR color)
    \n

    Source\n Code

    \n

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

    \n

    Examples:

    \n
      \n
    • ex_drawpixels.c
      • \n
    • ex_icon.c
      • \n-
    • ex_icon2.c
      • \n+
    • ex_icon.c
      • \n
    \n

    al_put_blended_pixel

    \n 
    void al_put_blended_pixel(int x, int y, ALLEGRO_COLOR color)
    \n

    Source\n Code

    \n

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

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

    An OpenGL command will be used to directly draw the line into the\n bitmap\u2019s associated texture.

    \n

    See also: al_get_target_bitmap, al_set_target_backbuffer

    \n+

    Examples:

    \n+
      \n+
    • ex_nodisplay.c
      • \n+
    • ex_opengl_pixel_shader.c
      • \n+
    • ex_blend_bench.c
      • \n+
    \n

    al_set_target_backbuffer

    \n 
    void al_set_target_backbuffer(ALLEGRO_DISPLAY *display)
    \n

    Source\n Code

    \n

    Same as\n al_set_target_bitmap(al_get_backbuffer(display));

    \n

    See also: al_set_target_bitmap, al_get_backbuffer

    \n+

    Examples:

    \n+
      \n+
    • ex_keyboard_focus.c
      • \n+
    • ex_mouse_focus.c
      • \n+
    • ex_opengl_pixel_shader.c
      • \n+
    \n

    al_get_current_display

    \n 
    ALLEGRO_DISPLAY *al_get_current_display(void)
    \n

    Source\n Code

    \n

    Return the display that is \u201ccurrent\u201d for the calling thread, or NULL\n if there is none.

    \n

    See also: al_set_target_bitmap

    \n+

    Examples:

    \n+
      \n+
    • common.c
      • \n+
    • ex_vsync.c
      • \n+
    • ex_color2.c
      • \n+
    \n

    Blending modes

    \n

    al_get_blender

    \n 
    void al_get_blender(int *op, int *src, int *dst)
    \n

    Source\n Code

    \n

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

    See also: al_set_separate_blender,\n al_set_blend_color, al_get_blender

    \n+

    Examples:

    \n+
      \n+
    • ex_blend_bench.c
      • \n+
    • ex_rotate.c
      • \n+
    • ex_membmp.c
      • \n+
    \n

    al_set_separate_blender

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

    Source\n Code

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

    \n

    See also: al_set_blender,\n al_get_blender, al_get_separate_blender

    \n+

    Examples:

    \n+
      \n+
    • ex_blend_test.c
      • \n+
    • ex_blend2.cpp
      • \n+
    • ex_logo.c
      • \n+
    \n

    al_set_blend_color

    \n
    void al_set_blend_color(ALLEGRO_COLOR color)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_set_blender,\n al_get_blend_color

    \n

    Since: 5.1.12

    \n+

    Examples:

    \n+
      \n+
    • ex_blend2.cpp
      • \n+
    \n

    Clipping

    \n

    al_get_clipping_rectangle

    \n
    void al_get_clipping_rectangle(int *x, int *y, int *w, int *h)
    \n

    Source\n Code

    \n@@ -2581,19 +2806,19 @@\n

    See also: al_get_clipping_rectangle,\n al_reset_clipping_rectangle

    \n

    Examples:

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

    al_reset_clipping_rectangle

    \n
    void al_reset_clipping_rectangle(void)
    \n

    Source\n Code

    \n@@ -2614,17 +2839,17 @@\n

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

    \n

    See also: ALLEGRO_COLOR

    \n

    Examples:

    \n
      \n
    • ex_projection.c
      • \n-
    • ex_android.c
      • \n+
    • ex_projection.c
      • \n
    \n

    Deferred drawing

    \n

    al_hold_bitmap_drawing

    \n
    void al_hold_bitmap_drawing(bool hold)
    \n

    Source\n@@ -2650,17 +2875,17 @@\n

    See also: al_is_bitmap_drawing_held

    \n

    Examples:

    \n
      \n
    • ex_depth_mask.c
      • \n
    • ex_ttf.c
      • \n-
    • ex_draw_bitmap.c
      • \n+
    • ex_ttf.c
      • \n
    \n

    al_is_bitmap_drawing_held

    \n
    bool al_is_bitmap_drawing_held(void)
    \n

    Source\n Code

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

    \n

    Examples:

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

    al_load_bitmap_flags

    \n
    ALLEGRO_BITMAP *al_load_bitmap_flags(const char *filename, int flags)
    \n

    Source\n Code

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

    \n

    Examples:

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

    al_load_bitmap_flags_f

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

    Source\n@@ -3071,15 +3296,19 @@\n

    Since: 5.1.12

    \n

    See also: al_init_image_addon, al_identify_bitmap, al_register_bitmap_identifier

    \n

    Render State

    \n

    ALLEGRO_RENDER_STATE

    \n-

    Source Code

    \n+
    typedef enum ALLEGRO_RENDER_STATE {
    \n+

    Source\n+Code

    \n

    Possible render states which can be set with al_set_render_state:

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

    Since: 5.1.2

    \n

    See also: al_set_render_state, ALLEGRO_RENDER_FUNCTION,\n ALLEGRO_WRITE_MASK_FLAGS

    \n

    ALLEGRO_RENDER_FUNCTION

    \n-

    Source Code

    \n+
    typedef enum ALLEGRO_RENDER_FUNCTION {
    \n+

    Source\n+Code

    \n

    Possible functions are:

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

    Since: 5.1.2

    \n

    See also: al_set_render_state

    \n

    ALLEGRO_WRITE_MASK_FLAGS

    \n-

    Source Code

    \n+
    typedef enum ALLEGRO_WRITE_MASK_FLAGS {
    \n+

    Source\n+Code

    \n

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

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

    Since: 5.1.2

    \n

    See also: al_set_render_state

    \n

    al_get_render_state

    \n-
    int al_get_render_state(ALLEGRO_RENDER_STATE state)
    \n+
    int al_get_render_state(ALLEGRO_RENDER_STATE state)
    \n

    Source\n Code

    \n

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

    \n

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

    \n@@ -3174,16 +3411,16 @@\n

    See also: al_set_render_state, ALLEGRO_RENDER_STATE, ALLEGRO_RENDER_FUNCTION,\n ALLEGRO_WRITE_MASK_FLAGS

    \n

    al_set_render_state

    \n-
    void al_set_render_state(ALLEGRO_RENDER_STATE state, int value)
    \n+
    void al_set_render_state(ALLEGRO_RENDER_STATE state, int value)
    \n

    Source\n Code

    \n

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

    \n

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

    \n

    Examples:

    \n
      \n
    • ex_depth_target.c
      • \n-
    • ex_depth_mask.c
      • \n
    • ex_camera.c
      • \n+href=\"https://github.com/liballeg/allegro5/blob/master/examples/ex_depth_target.c#L44\">ex_depth_target.c\n+
    • ex_draw_bitmap.c
      • \n
    \n

    al_backup_dirty_bitmap

    \n-
    void al_backup_dirty_bitmap(ALLEGRO_BITMAP *bitmap)
    \n+
    void al_backup_dirty_bitmap(ALLEGRO_BITMAP *bitmap)
    \n

    Source\n Code

    \n

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

    Unstable\n API: This API is new and subject to refinement.

    \n
    \n

    See also: al_backup_dirty_bitmaps,\n al_create_bitmap

    \n

    al_backup_dirty_bitmaps

    \n-
    void al_backup_dirty_bitmaps(ALLEGRO_DISPLAY *display)
    \n+
    void al_backup_dirty_bitmaps(ALLEGRO_DISPLAY *display)
    \n

    Source\n Code

    \n

    Backs up all of a display\u2019s bitmaps to system memory.

    \n

    Since: 5.2.1

    \n
    \n

    Unstable\n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -175,36 +175,52 @@\n *\b**\b**\b**\b**\b**\b* C\bCo\bol\blo\bor\brs\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_C\bCO\bOL\bLO\bOR\bR *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_COLOR ALLEGRO_COLOR;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An ALLEGRO_COLOR structure describes a color in a device independent way. Use\n _\ba_\bl_\b__\bm_\ba_\bp_\b__\br_\bg_\bb et al.\u00a0and _\ba_\bl_\b__\bu_\bn_\bm_\ba_\bp_\b__\br_\bg_\bb et al.\u00a0to translate from and to various\n color representations.\n+Examples:\n+ * _\be_\bx_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n+ * _\be_\bx_\b__\bn_\bo_\bd_\bi_\bs_\bp_\bl_\ba_\by_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_m\bma\bap\bp_\b_r\brg\bgb\bb *\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_map_rgb(\n unsigned char r, unsigned char g, unsigned char b)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert r, g, b (ranging from 0-255) into an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR, using 255 for\n alpha.\n This function can be called before Allegro is initialized.\n See also: _\ba_\bl_\b__\bm_\ba_\bp_\b__\br_\bg_\bb_\ba, _\ba_\bl_\b__\bm_\ba_\bp_\b__\br_\bg_\bb_\ba_\b__\bf, _\ba_\bl_\b__\bm_\ba_\bp_\b__\br_\bg_\bb_\b__\bf\n+Examples:\n+ * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bs_\be_\br_\bv_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n+ * _\be_\bx_\b__\bn_\bo_\bd_\bi_\bs_\bp_\bl_\ba_\by_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_m\bma\bap\bp_\b_r\brg\bgb\bb_\b_f\bf *\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_map_rgb_f(float r, float g, float b)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert r, g, b, (ranging from 0.0f-1.0f) into an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR, using 1.0f for\n alpha.\n This function can be called before Allegro is initialized.\n See also: _\ba_\bl_\b__\bm_\ba_\bp_\b__\br_\bg_\bb_\ba, _\ba_\bl_\b__\bm_\ba_\bp_\b__\br_\bg_\bb, _\ba_\bl_\b__\bm_\ba_\bp_\b__\br_\bg_\bb_\ba_\b__\bf\n+Examples:\n+ * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bs_\be_\br_\bv_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n+ * _\be_\bx_\b__\bd_\br_\ba_\bw_\bp_\bi_\bx_\be_\bl_\bs_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_m\bma\bap\bp_\b_r\brg\bgb\bba\ba *\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_map_rgba(\n unsigned char r, unsigned char g, unsigned char b, unsigned char a)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert r, g, b, a (ranging from 0-255) into an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR.\n This function can be called before Allegro is initialized.\n See also: _\ba_\bl_\b__\bm_\ba_\bp_\b__\br_\bg_\bb, _\ba_\bl_\b__\bp_\br_\be_\bm_\bu_\bl_\b__\br_\bg_\bb_\ba, _\ba_\bl_\b__\bm_\ba_\bp_\b__\br_\bg_\bb_\b__\bf\n+Examples:\n+ * _\be_\bx_\b__\bn_\bo_\bd_\bi_\bs_\bp_\bl_\ba_\by_\b._\bc\n+ * _\be_\bx_\b__\bd_\br_\ba_\bw_\bp_\bi_\bx_\be_\bl_\bs_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\bd_\bw_\ba_\bi_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_p\bpr\bre\bem\bmu\bul\bl_\b_r\brg\bgb\bba\ba *\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_premul_rgba(\n unsigned char r, unsigned char g, unsigned char b, unsigned char a)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This is a shortcut for _\ba_\bl_\b__\bm_\ba_\bp_\b__\br_\bg_\bb_\ba(r * a / 255, g * a / 255, b * a / 255, a).\n By default Allegro uses pre-multiplied alpha for transparent blending of\n bitmaps and primitives (see _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs for a discussion of that\n@@ -223,14 +239,18 @@\n See also: _\ba_\bl_\b__\bm_\ba_\bp_\b__\br_\bg_\bb_\ba, _\ba_\bl_\b__\bp_\br_\be_\bm_\bu_\bl_\b__\br_\bg_\bb_\ba_\b__\bf\n *\b**\b**\b**\b**\b* a\bal\bl_\b_m\bma\bap\bp_\b_r\brg\bgb\bba\ba_\b_f\bf *\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_map_rgba_f(float r, float g, float b, float a)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert r, g, b, a (ranging from 0.0f-1.0f) into an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR.\n This function can be called before Allegro is initialized.\n See also: _\ba_\bl_\b__\bm_\ba_\bp_\b__\br_\bg_\bb_\ba, _\ba_\bl_\b__\bp_\br_\be_\bm_\bu_\bl_\b__\br_\bg_\bb_\ba_\b__\bf, _\ba_\bl_\b__\bm_\ba_\bp_\b__\br_\bg_\bb_\b__\bf\n+Examples:\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\bd_\bw_\ba_\bi_\bt_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bs_\bi_\bz_\be_\b._\bc\n+ * _\be_\bx_\b__\br_\bo_\bt_\ba_\bt_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_p\bpr\bre\bem\bmu\bul\bl_\b_r\brg\bgb\bba\ba_\b_f\bf *\b**\b**\b**\b**\b*\n ALLEGRO_COLOR al_premul_rgba_f(float r, float g, float b, float a)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This is a shortcut for _\ba_\bl_\b__\bm_\ba_\bp_\b__\br_\bg_\bb_\ba_\b__\bf(r * a, g * a, b * a, a).\n By default Allegro uses pre-multiplied alpha for transparent blending of\n bitmaps and primitives (see _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs for a discussion of that\n feature). This means that if you want to tint a bitmap or primitive to be\n@@ -250,35 +270,48 @@\n void al_unmap_rgb(ALLEGRO_COLOR color,\n unsigned char *r, unsigned char *g, unsigned char *b)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Retrieves components of an ALLEGRO_COLOR, ignoring alpha. Components will range\n from 0-255.\n This function can be called before Allegro is initialized.\n See also: _\ba_\bl_\b__\bu_\bn_\bm_\ba_\bp_\b__\br_\bg_\bb_\ba, _\ba_\bl_\b__\bu_\bn_\bm_\ba_\bp_\b__\br_\bg_\bb_\ba_\b__\bf, _\ba_\bl_\b__\bu_\bn_\bm_\ba_\bp_\b__\br_\bg_\bb_\b__\bf\n+Examples:\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\bh_\ba_\bi_\bk_\bu_\b._\bc\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b__\bg_\br_\ba_\bd_\bi_\be_\bn_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bnm\bma\bap\bp_\b_r\brg\bgb\bb_\b_f\bf *\b**\b**\b**\b**\b*\n void al_unmap_rgb_f(ALLEGRO_COLOR color, float *r, float *g, float *b)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Retrieves components of an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR, ignoring alpha. Components will range\n from 0.0f-1.0f.\n This function can be called before Allegro is initialized.\n See also: _\ba_\bl_\b__\bu_\bn_\bm_\ba_\bp_\b__\br_\bg_\bb_\ba, _\ba_\bl_\b__\bu_\bn_\bm_\ba_\bp_\b__\br_\bg_\bb, _\ba_\bl_\b__\bu_\bn_\bm_\ba_\bp_\b__\br_\bg_\bb_\ba_\b__\bf\n+Examples:\n+ * _\be_\bx_\b__\bh_\ba_\bi_\bk_\bu_\b._\bc\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b__\bg_\br_\ba_\bd_\bi_\be_\bn_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bnm\bma\bap\bp_\b_r\brg\bgb\bba\ba *\b**\b**\b**\b**\b*\n void al_unmap_rgba(ALLEGRO_COLOR color,\n unsigned char *r, unsigned char *g, unsigned char *b, unsigned char *a)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Retrieves components of an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR. Components will range from 0-255.\n This function can be called before Allegro is initialized.\n See also: _\ba_\bl_\b__\bu_\bn_\bm_\ba_\bp_\b__\br_\bg_\bb, _\ba_\bl_\b__\bu_\bn_\bm_\ba_\bp_\b__\br_\bg_\bb_\ba_\b__\bf, _\ba_\bl_\b__\bu_\bn_\bm_\ba_\bp_\b__\br_\bg_\bb_\b__\bf\n+Examples:\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\bg_\bo_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bnm\bma\bap\bp_\b_r\brg\bgb\bba\ba_\b_f\bf *\b**\b**\b**\b**\b*\n void al_unmap_rgba_f(ALLEGRO_COLOR color,\n float *r, float *g, float *b, float *a)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Retrieves components of an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR. Components will range from 0.0f-1.0f.\n This function can be called before Allegro is initialized.\n See also: _\ba_\bl_\b__\bu_\bn_\bm_\ba_\bp_\b__\br_\bg_\bb_\ba, _\ba_\bl_\b__\bu_\bn_\bm_\ba_\bp_\b__\br_\bg_\bb, _\ba_\bl_\b__\bu_\bn_\bm_\ba_\bp_\b__\br_\bg_\bb_\b__\bf\n+Examples:\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\bg_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* L\bLo\boc\bck\bki\bin\bng\bg a\ban\bnd\bd p\bpi\bix\bxe\bel\bl f\bfo\bor\brm\bma\bat\bts\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_L\bLO\bOC\bCK\bKE\bED\bD_\b_R\bRE\bEG\bGI\bIO\bON\bN *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_LOCKED_REGION ALLEGRO_LOCKED_REGION;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Users who wish to manually edit or read from a bitmap are required to lock it\n first. The ALLEGRO_LOCKED_REGION structure represents the locked region of the\n bitmap. This call will work with any bitmap, including memory bitmaps.\n@@ -300,14 +333,18 @@\n * p\bpi\bix\bxe\bel\bl_\b_s\bsi\biz\bze\be is the number of bytes used to represent a single block of\n pixels for the pixel format of this locked region. For most formats (and\n historically, this used to be true for all formats), this is just the\n size of a single pixel, but for blocked pixel formats this value is\n different.\n See also: _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\br_\be_\bg_\bi_\bo_\bn, _\ba_\bl_\b__\bu_\bn_\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp,\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bI_\bX_\bE_\bL_\b__\bF_\bO_\bR_\bM_\bA_\bT\n+Examples:\n+ * _\be_\bx_\b__\bl_\bo_\bc_\bk_\bb_\bi_\bt_\bm_\ba_\bp_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\be_\bm_\bu_\bl_\ba_\bl_\bp_\bh_\ba_\b._\bc\n+ * _\be_\bx_\b__\bm_\bu_\bl_\bt_\bi_\bs_\ba_\bm_\bp_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_P\bPI\bIX\bXE\bEL\bL_\b_F\bFO\bOR\bRM\bMA\bAT\bT *\b**\b**\b**\b**\b*\n typedef enum ALLEGRO_PIXEL_FORMAT\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Pixel formats. Each pixel format specifies the exact size and bit layout of a\n pixel in memory. Components are specified from high bits to low bits, so for\n example a fully opaque red pixel in ARGB_8888 format is 0xFFFF0000.\n N\bNo\bot\bte\be:\b:\n@@ -403,14 +440,18 @@\n resulting in 4x compression ratio. This format supports sharp alpha\n transitions. Since 5.1.9.\n * ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT5 - Compressed using the DXT5\n compression algorithm. Each 4x4 pixel block is encoded in 128 bytes,\n resulting in 4x compression ratio. This format supports smooth alpha\n transitions. Since 5.1.9.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bo_\br_\bm_\ba_\bt, _\ba_\bl_\b__\bg_\be_\bt_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bo_\br_\bm_\ba_\bt\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bn_\bv_\be_\br_\bt_\b._\bc\n+ * _\be_\bx_\b__\bd_\br_\ba_\bw_\bp_\bi_\bx_\be_\bl_\bs_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\bc_\bk_\bb_\bi_\bt_\bm_\ba_\bp_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_p\bpi\bix\bxe\bel\bl_\b_s\bsi\biz\bze\be *\b**\b**\b**\b**\b*\n int al_get_pixel_size(int format)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the number of bytes that a pixel of the given format occupies. For\n blocked pixel formats (e.g.\u00a0compressed formats), this returns 0.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bI_\bX_\bE_\bL_\b__\bF_\bO_\bR_\bM_\bA_\bT, _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\bi_\bx_\be_\bl_\b__\bf_\bo_\br_\bm_\ba_\bt_\b__\bb_\bi_\bt_\bs\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_p\bpi\bix\bxe\bel\bl_\b_f\bfo\bor\brm\bma\bat\bt_\b_b\bbi\bit\bts\bs *\b**\b**\b**\b**\b*\n@@ -429,21 +470,25 @@\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_p\bpi\bix\bxe\bel\bl_\b_b\bbl\blo\boc\bck\bk_\b_w\bwi\bid\bdt\bth\bh *\b**\b**\b**\b**\b*\n int al_get_pixel_block_width(int format)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the width of the the pixel block for this format.\n Since: 5.1.9.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bI_\bX_\bE_\bL_\b__\bF_\bO_\bR_\bM_\bA_\bT, _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\bi_\bx_\be_\bl_\b__\bb_\bl_\bo_\bc_\bk_\b__\bs_\bi_\bz_\be,\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\bi_\bx_\be_\bl_\b__\bb_\bl_\bo_\bc_\bk_\b__\bh_\be_\bi_\bg_\bh_\bt\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bm_\bp_\br_\be_\bs_\bs_\be_\bd_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_p\bpi\bix\bxe\bel\bl_\b_b\bbl\blo\boc\bck\bk_\b_h\bhe\bei\big\bgh\bht\bt *\b**\b**\b**\b**\b*\n int al_get_pixel_block_height(int format)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the height of the the pixel block for this format.\n Since: 5.1.9.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bI_\bX_\bE_\bL_\b__\bF_\bO_\bR_\bM_\bA_\bT, _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\bi_\bx_\be_\bl_\b__\bb_\bl_\bo_\bc_\bk_\b__\bs_\bi_\bz_\be,\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\bi_\bx_\be_\bl_\b__\bb_\bl_\bo_\bc_\bk_\b__\bw_\bi_\bd_\bt_\bh\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bm_\bp_\br_\be_\bs_\bs_\be_\bd_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boc\bck\bk_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n ALLEGRO_LOCKED_REGION *al_lock_bitmap(ALLEGRO_BITMAP *bitmap,\n int format, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Lock an entire bitmap for reading or writing. If the bitmap is a display bitmap\n it will be updated from system memory after the bitmap is unlocked (unless\n locked read only). Returns NULL if the bitmap cannot be locked, e.g.\u00a0the bitmap\n@@ -475,15 +520,15 @@\n operations on it (with the sole exception of _\ba_\bl_\b__\bp_\bu_\bt_\b__\bp_\bi_\bx_\be_\bl and\n _\ba_\bl_\b__\bp_\bu_\bt_\b__\bb_\bl_\be_\bn_\bd_\be_\bd_\b__\bp_\bi_\bx_\be_\bl).\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bL_\bO_\bC_\bK_\bE_\bD_\b__\bR_\bE_\bG_\bI_\bO_\bN, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bI_\bX_\bE_\bL_\b__\bF_\bO_\bR_\bM_\bA_\bT, _\ba_\bl_\b__\bu_\bn_\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp,\n _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\br_\be_\bg_\bi_\bo_\bn, _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bb_\bl_\bo_\bc_\bk_\be_\bd, _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\br_\be_\bg_\bi_\bo_\bn_\b__\bb_\bl_\bo_\bc_\bk_\be_\bd\n Examples:\n * _\be_\bx_\b__\bd_\br_\ba_\bw_\bp_\bi_\bx_\be_\bl_\bs_\b._\bc\n * _\be_\bx_\b__\bm_\be_\bm_\bb_\bm_\bp_\b._\bc\n- * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\bc_\bk_\bb_\bi_\bt_\bm_\ba_\bp_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boc\bck\bk_\b_b\bbi\bit\btm\bma\bap\bp_\b_r\bre\beg\bgi\bio\bon\bn *\b**\b**\b**\b**\b*\n ALLEGRO_LOCKED_REGION *al_lock_bitmap_region(ALLEGRO_BITMAP *bitmap,\n int x, int y, int width, int height, int format, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp, but only locks a specific area of the bitmap. If the\n bitmap is a video bitmap, only that area of the texture will be updated when it\n is unlocked. Locking only the region you indend to modify will be faster than\n@@ -494,28 +539,28 @@\n region be aligned to the block width for optimal performance. If it\n is not, then the function will have to lock the region with the\n ALLEGRO_LOCK_READWRITE instead in order to pad this region with valid\n data.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bL_\bO_\bC_\bK_\bE_\bD_\b__\bR_\bE_\bG_\bI_\bO_\bN, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bI_\bX_\bE_\bL_\b__\bF_\bO_\bR_\bM_\bA_\bT, _\ba_\bl_\b__\bu_\bn_\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp\n Examples:\n * _\be_\bx_\b__\bl_\bo_\bc_\bk_\bb_\bi_\bt_\bm_\ba_\bp_\b._\bc\n+ * _\be_\bx_\b__\bc_\bo_\bm_\bp_\br_\be_\bs_\bs_\be_\bd_\b._\bc\n * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n- * _\be_\bx_\b__\bb_\bl_\bi_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bnl\blo\boc\bck\bk_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n void al_unlock_bitmap(ALLEGRO_BITMAP *bitmap)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Unlock a previously locked bitmap or bitmap region. If the bitmap is a video\n bitmap, the texture will be updated to match the system memory copy (unless it\n was locked read only).\n See also: _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\br_\be_\bg_\bi_\bo_\bn, _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bb_\bl_\bo_\bc_\bk_\be_\bd,\n _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\br_\be_\bg_\bi_\bo_\bn_\b__\bb_\bl_\bo_\bc_\bk_\be_\bd\n Examples:\n * _\be_\bx_\b__\bd_\br_\ba_\bw_\bp_\bi_\bx_\be_\bl_\bs_\b._\bc\n- * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b._\bc\n * _\be_\bx_\b__\bl_\bo_\bc_\bk_\bb_\bi_\bt_\bm_\ba_\bp_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\be_\bm_\bu_\bl_\ba_\bl_\bp_\bh_\ba_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boc\bck\bk_\b_b\bbi\bit\btm\bma\bap\bp_\b_b\bbl\blo\boc\bck\bke\bed\bd *\b**\b**\b**\b**\b*\n ALLEGRO_LOCKED_REGION *al_lock_bitmap_blocked(ALLEGRO_BITMAP *bitmap,\n int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp, but allows locking bitmaps with a blocked pixel format\n (i.e.\u00a0a format for which _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\bi_\bx_\be_\bl_\b__\bb_\bl_\bo_\bc_\bk_\b__\bw_\bi_\bd_\bt_\bh or _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\bi_\bx_\be_\bl_\b__\bb_\bl_\bo_\bc_\bk_\b__\bh_\be_\bi_\bg_\bh_\bt\n do not return 1) in that format. To that end, this function also does not allow\n@@ -538,14 +583,18 @@\n Examples:\n * _\be_\bx_\b__\bc_\bo_\bm_\bp_\br_\be_\bs_\bs_\be_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* B\bBi\bit\btm\bma\bap\bp c\bcr\bre\bea\bat\bti\bio\bon\bn *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_B\bBI\bIT\bTM\bMA\bAP\bP *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_BITMAP ALLEGRO_BITMAP;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Abstract type representing a bitmap (2D image).\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bn_\bv_\be_\br_\bt_\b._\bc\n+ * _\be_\bx_\b__\bn_\bo_\bd_\bi_\bs_\bp_\bl_\ba_\by_\b._\bc\n+ * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\bp_\bi_\bx_\be_\bl_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n ALLEGRO_BITMAP *al_create_bitmap(int w, int h)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Creates a new bitmap using the bitmap format and flags for the current thread.\n Blitting between bitmaps of differing formats, or blitting between memory\n bitmaps and display bitmaps may be slow.\n Unless you set the ALLEGRO_MEMORY_BITMAP flag, the bitmap is created for the\n@@ -586,17 +635,17 @@\n N\bNo\bot\bte\be: The contents of a newly created bitmap are undefined - you need to clear\n the bitmap or make sure all pixels get overwritten before drawing it.\n When you are done with using the bitmap you must call _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bb_\bi_\bt_\bm_\ba_\bp on it\n to free any resources allocated for it.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bo_\br_\bm_\ba_\bt, _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs, _\ba_\bl_\b__\bc_\bl_\bo_\bn_\be_\b__\bb_\bi_\bt_\bm_\ba_\bp,\n _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bs_\bu_\bb_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bc_\bo_\bn_\bv_\be_\br_\bt_\b__\bm_\be_\bm_\bo_\br_\by_\b__\bb_\bi_\bt_\bm_\ba_\bp_\bs, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bb_\bi_\bt_\bm_\ba_\bp\n Examples:\n- * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\bp_\bi_\bx_\be_\bl_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n * _\be_\bx_\b__\bn_\bo_\bd_\bi_\bs_\bp_\bl_\ba_\by_\b._\bc\n- * _\be_\bx_\b__\bl_\bi_\bn_\be_\bs_\b._\bc\n+ * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\bp_\bi_\bx_\be_\bl_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bi_\bc_\bo_\bn_\b2_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_s\bsu\bub\bb_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n ALLEGRO_BITMAP *al_create_sub_bitmap(ALLEGRO_BITMAP *parent,\n int x, int y, int w, int h)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Creates a sub-bitmap of the parent, at the specified coordinates and of the\n specified size. A sub-bitmap is a bitmap that shares drawing memory with a pre-\n existing (parent) bitmap, but possibly with a different size and clipping\n@@ -610,31 +659,31 @@\n it to free any resources allocated for it.\n Note that destroying parents of sub-bitmaps will not destroy the sub-bitmaps;\n instead the sub-bitmaps become invalid and should no longer be used for drawing\n - they still must be destroyed with _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bb_\bi_\bt_\bm_\ba_\bp however. It does not\n matter whether you destroy a sub-bitmap before or after its parent otherwise.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bb_\bi_\bt_\bm_\ba_\bp\n Examples:\n- * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n- * _\be_\bx_\b__\bm_\bu_\bl_\bt_\bi_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bs_\bu_\bb_\bb_\bi_\bt_\bm_\ba_\bp_\b._\bc\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcl\blo\bon\bne\be_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n ALLEGRO_BITMAP *al_clone_bitmap(ALLEGRO_BITMAP *bitmap)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a new bitmap with _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bb_\bi_\bt_\bm_\ba_\bp, and copy the pixel data from the old\n bitmap across. The newly created bitmap will be created with the current new\n bitmap flags, and not the ones that were used to create the original bitmap. If\n the new bitmap is a memory bitmap, its projection bitmap is reset to be\n orthographic.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bo_\br_\bm_\ba_\bt, _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs,\n _\ba_\bl_\b__\bc_\bo_\bn_\bv_\be_\br_\bt_\b__\bb_\bi_\bt_\bm_\ba_\bp\n Examples:\n- * _\be_\bx_\b__\bp_\br_\be_\bm_\bu_\bl_\ba_\bl_\bp_\bh_\ba_\b._\bc\n- * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b2_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bu_\bb_\bb_\bi_\bt_\bm_\ba_\bp_\b._\bc\n * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\be_\bm_\bu_\bl_\ba_\bl_\bp_\bh_\ba_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bon\bnv\bve\ber\brt\bt_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n void al_convert_bitmap(ALLEGRO_BITMAP *bitmap)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Converts the bitmap to the current bitmap flags and format. The bitmap will be\n as if it was created anew with _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bb_\bi_\bt_\bm_\ba_\bp but retain its contents. All of\n this bitmap\u2019s sub-bitmaps are also converted. If the new bitmap type is memory,\n then the bitmap\u2019s projection bitmap is reset to be orthographic.\n@@ -675,14 +724,16 @@\n * _\be_\bx_\b__\bn_\bo_\bd_\bi_\bs_\bp_\bl_\ba_\by_\b._\bc\n * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bb_\be_\bn_\bc_\bh_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_n\bne\bew\bw_\b_b\bbi\bit\btm\bma\bap\bp_\b_f\bfl\bla\bag\bgs\bs *\b**\b**\b**\b**\b*\n int al_get_new_bitmap_flags(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the flags used for newly created bitmaps.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_n\bne\bew\bw_\b_b\bbi\bit\btm\bma\bap\bp_\b_f\bfo\bor\brm\bma\bat\bt *\b**\b**\b**\b**\b*\n int al_get_new_bitmap_format(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the format used for newly created bitmaps.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bI_\bX_\bE_\bL_\b__\bF_\bO_\bR_\bM_\bA_\bT, _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bo_\br_\bm_\ba_\bt\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_n\bne\bew\bw_\b_b\bbi\bit\btm\bma\bap\bp_\b_f\bfl\bla\bag\bgs\bs *\b**\b**\b**\b**\b*\n void al_set_new_bitmap_flags(int flags)\n@@ -746,36 +797,48 @@\n ALLEGRO_MIPMAP\n This can only be used for bitmaps whose width and height is a power of\n two. In that case, it will generate mipmaps and use them when drawing\n scaled down versions. For example if the bitmap is 64x64, then extra\n bitmaps of sizes 32x32, 16x16, 8x8, 4x4, 2x2 and 1x1 will be created\n always containing a scaled down version of the original.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs, _\ba_\bl_\b__\bg_\be_\bt_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bn_\bv_\be_\br_\bt_\b._\bc\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bb_\be_\bn_\bc_\bh_\b._\bc\n+ * _\be_\bx_\b__\bi_\bc_\bo_\bn_\b2_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_a\bad\bdd\bd_\b_n\bne\bew\bw_\b_b\bbi\bit\btm\bma\bap\bp_\b_f\bfl\bla\bag\bg *\b**\b**\b**\b**\b*\n void al_add_new_bitmap_flag(int flag)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n A convenience function which does the same as\n al_set_new_bitmap_flags(al_get_new_bitmap_flags() | flag);\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs, _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs, _\ba_\bl_\b__\bg_\be_\bt_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs\n+Examples:\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b2_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_n\bne\bew\bw_\b_b\bbi\bit\btm\bma\bap\bp_\b_f\bfo\bor\brm\bma\bat\bt *\b**\b**\b**\b**\b*\n void al_set_new_bitmap_format(int format)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets the pixel format (_\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bI_\bX_\bE_\bL_\b__\bF_\bO_\bR_\bM_\bA_\bT) for newly created bitmaps. The\n default format is 0 and means the display driver will choose the best format.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bI_\bX_\bE_\bL_\b__\bF_\bO_\bR_\bM_\bA_\bT, _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bo_\br_\bm_\ba_\bt, _\ba_\bl_\b__\bg_\be_\bt_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bo_\br_\bm_\ba_\bt\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bn_\bv_\be_\br_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\bi_\bx_\be_\bl_\bf_\bo_\br_\bm_\ba_\bt_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_n\bne\bew\bw_\b_b\bbi\bit\btm\bma\bap\bp_\b_d\bde\bep\bpt\bth\bh *\b**\b**\b**\b**\b*\n void al_set_new_bitmap_depth(int depth)\n SETTER(new_bitmap_depth, depth)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets the depthbuffer depth used by newly created bitmaps (on the current\n thread) if they are used with _\ba_\bl_\b__\bs_\be_\bt_\b__\bt_\ba_\br_\bg_\be_\bt_\b__\bb_\bi_\bt_\bm_\ba_\bp. 0 means no depth-buffer\n will be created when drawing into the bitmap, which is the default.\n Since: 5.2.1\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: This is an experimental feature and currently only\n works for the OpenGL backend.\n+Examples:\n+ * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_n\bne\bew\bw_\b_b\bbi\bit\btm\bma\bap\bp_\b_d\bde\bep\bpt\bth\bh *\b**\b**\b**\b**\b*\n int al_get_new_bitmap_depth(void)\n GETTER(new_bitmap_depth, 0)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the value currently set with _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bd_\be_\bp_\bt_\bh on the current\n thread or 0 if none was set.\n Since: 5.2.1\n@@ -803,14 +866,17 @@\n al_set_target_bitmap(backbuffer);\n al_lock_bitmap(multisample, ...)\n // CORRECT: at this point, the bitmap contents are updated and\n // there will be an anti-aliased line in it.\n Since: 5.2.1\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: This is an experimental feature and currently only\n works for the OpenGL backend.\n+Examples:\n+ * _\be_\bx_\b__\bm_\bu_\bl_\bt_\bi_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_n\bne\bew\bw_\b_b\bbi\bit\btm\bma\bap\bp_\b_s\bsa\bam\bmp\bpl\ble\bes\bs *\b**\b**\b**\b**\b*\n int al_get_new_bitmap_samples(void)\n GETTER(new_bitmap_samples, 0)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the value currently set with _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bs_\ba_\bm_\bp_\bl_\be_\bs on the current\n thread or 0 if none was set.\n Since: 5.2.1\n@@ -828,14 +894,17 @@\n per-texture. This interacts particularly poorly with the primitives\n addon which (for backwards compatibility) alters the wrapping\n setting. To minimize this issue, use a wrapping setting that\u2019s not\n ALLEGRO_BITMAP_WRAP_DEFAULT.\n Since: 5.2.8\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: This is an experimental feature.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bB_\bI_\bT_\bM_\bA_\bP_\b__\bW_\bR_\bA_\bP\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bw_\br_\ba_\bp_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_n\bne\bew\bw_\b_b\bbi\bit\btm\bma\bap\bp_\b_w\bwr\bra\bap\bp *\b**\b**\b**\b**\b*\n Source Code\n Returns the value currently set with _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bw_\br_\ba_\bp on the current\n thread.\n Since: 5.2.8\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: This is an experimental feature.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bB_\bI_\bT_\bM_\bA_\bP_\b__\bW_\bR_\bA_\bP\n@@ -849,14 +918,17 @@\n ALLEGRO_BITMAP_WRAP_CLAMP otherwise.\n * ALLEGRO_BITMAP_WRAP_REPEAT - The texture coordinates get shifted to the\n opposite edge that they go past.\n * ALLEGRO_BITMAP_WRAP_CLAMP - The texture coordinates get clamped to the\n edges that they go past.\n * ALLEGRO_BITMAP_WRAP_MIRROR - The texture coordinates get mirrored across\n the edges that they go past.\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bw_\br_\ba_\bp_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b**\b* B\bBi\bit\btm\bma\bap\bp p\bpr\bro\bop\bpe\ber\brt\bti\bie\bes\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_b\bbi\bit\btm\bma\bap\bp_\b_f\bfl\bla\bag\bgs\bs *\b**\b**\b**\b**\b*\n int al_get_bitmap_flags(ALLEGRO_BITMAP *bitmap)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the flags used to create the bitmap.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs\n Examples:\n@@ -871,25 +943,25 @@\n * _\be_\bx_\b__\bc_\bo_\bm_\bp_\br_\be_\bs_\bs_\be_\bd_\b._\bc\n * _\be_\bx_\b__\bd_\br_\ba_\bw_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_b\bbi\bit\btm\bma\bap\bp_\b_h\bhe\bei\big\bgh\bht\bt *\b**\b**\b**\b**\b*\n int al_get_bitmap_height(ALLEGRO_BITMAP *bitmap)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the height of a bitmap in pixels.\n Examples:\n- * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n- * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n+ * _\be_\bx_\b__\bm_\bu_\bl_\bt_\bi_\bw_\bi_\bn_\b._\bc\n * _\be_\bx_\b__\br_\be_\bs_\bi_\bz_\be_\b._\bc\n+ * _\be_\bx_\b__\bm_\be_\bm_\bb_\bm_\bp_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_b\bbi\bit\btm\bma\bap\bp_\b_w\bwi\bid\bdt\bth\bh *\b**\b**\b**\b**\b*\n int al_get_bitmap_width(ALLEGRO_BITMAP *bitmap)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the width of a bitmap in pixels.\n Examples:\n- * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b._\bc_\bp_\bp\n * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bj_\bu_\bs_\bt_\bi_\bf_\by_\b._\bc_\bp_\bp\n- * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n+ * _\be_\bx_\b__\bm_\bu_\bl_\bt_\bi_\bw_\bi_\bn_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bs_\bi_\bz_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_b\bbi\bit\btm\bma\bap\bp_\b_d\bde\bep\bpt\bth\bh *\b**\b**\b**\b**\b*\n int al_get_bitmap_depth(ALLEGRO_BITMAP *bitmap)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the depthbuffer depth used by this bitmap if it is used with\n _\ba_\bl_\b__\bs_\be_\bt_\b__\bt_\ba_\br_\bg_\be_\bt_\b__\bb_\bi_\bt_\bm_\ba_\bp.\n Since: 5.2.1\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: This is an experimental feature and currently only\n@@ -907,16 +979,16 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get a pixel\u2019s color value from the specified bitmap. This operation is slow on\n non-memory bitmaps. Consider locking the bitmap if you are going to use this\n function multiple times on the same bitmap.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR, _\ba_\bl_\b__\bp_\bu_\bt_\b__\bp_\bi_\bx_\be_\bl, _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp\n Examples:\n * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bt_\be_\bs_\bt_\b._\bc\n- * _\be_\bx_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br_\b._\bc\n * _\be_\bx_\b__\bc_\bo_\bm_\bp_\br_\be_\bs_\bs_\be_\bd_\b._\bc\n+ * _\be_\bx_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_b\bbi\bit\btm\bma\bap\bp_\b_l\blo\boc\bck\bke\bed\bd *\b**\b**\b**\b**\b*\n bool al_is_bitmap_locked(ALLEGRO_BITMAP *bitmap)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns whether or not a bitmap is already locked.\n See also: _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\br_\be_\bg_\bi_\bo_\bn, _\ba_\bl_\b__\bu_\bn_\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_c\bco\bom\bmp\bpa\bat\bti\bib\bbl\ble\be_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n bool al_is_compatible_bitmap(ALLEGRO_BITMAP *bitmap)\n@@ -977,16 +1049,16 @@\n bitmap pointer stays the same. This has many uses, for example an animation\n player could return a single bitmap which can just be re-parented to different\n animation frames without having to re-draw the contents. Or a sprite atlas\n could re-arrange its sprites without having to invalidate all existing bitmaps.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bs_\bu_\bb_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\ba_\br_\be_\bn_\bt_\b__\bb_\bi_\bt_\bm_\ba_\bp\n Since: 5.1.12\n Examples:\n- * _\be_\bx_\b__\bm_\bu_\bl_\bt_\bi_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n * _\be_\bx_\b__\br_\be_\bp_\ba_\br_\be_\bn_\bt_\b._\bc\n+ * _\be_\bx_\b__\bm_\bu_\bl_\bt_\bi_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_b\bbi\bit\btm\bma\bap\bp_\b_b\bbl\ble\ben\bnd\bde\ber\br *\b**\b**\b**\b**\b*\n void al_get_bitmap_blender(int *op, int *src, int *dst)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the current blender being used by the target bitmap. You can pass NULL\n for values you are not interested in.\n Since: 5.2.5\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: New API.\n@@ -1058,17 +1130,17 @@\n created in a thread.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcl\ble\bea\bar\br_\b_t\bto\bo_\b_c\bco\bol\blo\bor\br *\b**\b**\b**\b**\b*\n void al_clear_to_color(ALLEGRO_COLOR color)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Clear the complete target bitmap, but confined by the clipping rectangle.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR, _\ba_\bl_\b__\bs_\be_\bt_\b__\bc_\bl_\bi_\bp_\bp_\bi_\bn_\bg_\b__\br_\be_\bc_\bt_\ba_\bn_\bg_\bl_\be, _\ba_\bl_\b__\bc_\bl_\be_\ba_\br_\b__\bd_\be_\bp_\bt_\bh_\b__\bb_\bu_\bf_\bf_\be_\br\n Examples:\n- * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bp_\br_\bo_\bp_\bs_\b._\bc_\bp_\bp\n * _\be_\bx_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n- * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bn_\bo_\bd_\bi_\bs_\bp_\bl_\ba_\by_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcl\ble\bea\bar\br_\b_d\bde\bep\bpt\bth\bh_\b_b\bbu\buf\bff\bfe\ber\br *\b**\b**\b**\b**\b*\n void al_clear_depth_buffer(float z)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Clear the depth buffer (confined by the clipping rectangle) to the given value.\n A depth buffer is only available if it was requested with\n _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bd_\bi_\bs_\bp_\bl_\ba_\by_\b__\bo_\bp_\bt_\bi_\bo_\bn and the requirement could be met by the\n _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bd_\bi_\bs_\bp_\bl_\ba_\by call creating the current display. Operations involving the\n@@ -1076,17 +1148,17 @@\n For example, if ALLEGRO_DEPTH_FUNCTION is set to ALLEGRO_RENDER_LESS then depth\n buffer value of 1 represents infinite distance, and thus is a good value to use\n when clearing the depth buffer.\n Since: 5.1.2\n See also: _\ba_\bl_\b__\bc_\bl_\be_\ba_\br_\b__\bt_\bo_\b__\bc_\bo_\bl_\bo_\br, _\ba_\bl_\b__\bs_\be_\bt_\b__\bc_\bl_\bi_\bp_\bp_\bi_\bn_\bg_\b__\br_\be_\bc_\bt_\ba_\bn_\bg_\bl_\be, _\ba_\bl_\b__\bs_\be_\bt_\b__\br_\be_\bn_\bd_\be_\br_\b__\bs_\bt_\ba_\bt_\be,\n _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bd_\bi_\bs_\bp_\bl_\ba_\by_\b__\bo_\bp_\bt_\bi_\bo_\bn\n Examples:\n- * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bm_\ba_\bs_\bk_\b._\bc\n- * _\be_\bx_\b__\bc_\ba_\bm_\be_\br_\ba_\b._\bc\n+ * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b2_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n void al_draw_bitmap(ALLEGRO_BITMAP *bitmap, float dx, float dy, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws an unscaled, unrotated bitmap at the given position to the current target\n bitmap (see _\ba_\bl_\b__\bs_\be_\bt_\b__\bt_\ba_\br_\bg_\be_\bt_\b__\bb_\bi_\bt_\bm_\ba_\bp).\n flags can be a combination of:\n * ALLEGRO_FLIP_HORIZONTAL - flip the bitmap about the y-axis\n@@ -1100,17 +1172,17 @@\n transformed, blended or tinted. If you need to draw the backbuffer\n draw it to a temporary bitmap first with no active transformation\n (except translation). Blending and tinting settings/parameters will\n be ignored. This does not apply when drawing into a memory bitmap.\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\br_\be_\bg_\bi_\bo_\bn, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bs_\bc_\ba_\bl_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\br_\bo_\bt_\ba_\bt_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp,\n _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bs_\bc_\ba_\bl_\be_\bd_\b__\br_\bo_\bt_\ba_\bt_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp\n Examples:\n- * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b._\bc\n+ * _\be_\bx_\b__\bn_\bo_\bd_\bi_\bs_\bp_\bl_\ba_\by_\b._\bc\n * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\bp_\bi_\bx_\be_\bl_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n- * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bb_\be_\bn_\bc_\bh_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_t\bti\bin\bnt\bte\bed\bd_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n void al_draw_tinted_bitmap(ALLEGRO_BITMAP *bitmap, ALLEGRO_COLOR tint,\n float dx, float dy, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp but multiplies all colors in the bitmap with the given\n color. For example:\n al_draw_tinted_bitmap(bitmap, al_map_rgba_f(0.5, 0.5, 0.5, 0.5), x, y, 0);\n@@ -1119,15 +1191,15 @@\n al_draw_tinted_bitmap(bitmap, al_map_rgba_f(1, 0, 0, 1), x, y, 0);\n The above will only draw the red component of the bitmap.\n See _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp for a note on restrictions on which bitmaps can be drawn\n where.\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp\n Examples:\n * _\be_\bx_\b__\bn_\bo_\bd_\bi_\bs_\bp_\bl_\ba_\by_\b._\bc\n- * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\be_\bx_\bp_\bo_\bs_\be_\b._\bc\n * _\be_\bx_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\bi_\bp_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_b\bbi\bit\btm\bma\bap\bp_\b_r\bre\beg\bgi\bio\bon\bn *\b**\b**\b**\b**\b*\n void al_draw_bitmap_region(ALLEGRO_BITMAP *bitmap,\n float sx, float sy, float sw, float sh, float dx, float dy, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a region of the given bitmap to the target bitmap.\n * sx - source x\n@@ -1138,31 +1210,31 @@\n * dy - destination y\n * flags - same as for _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp\n See _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp for a note on restrictions on which bitmaps can be drawn\n where.\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bs_\bc_\ba_\bl_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\br_\bo_\bt_\ba_\bt_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp,\n _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bs_\bc_\ba_\bl_\be_\bd_\b__\br_\bo_\bt_\ba_\bt_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp\n Examples:\n- * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b._\bc\n * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b._\bc\n+ * _\be_\bx_\b__\bc_\bl_\bi_\bp_\b._\bc\n * _\be_\bx_\b__\bb_\bl_\bi_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_t\bti\bin\bnt\bte\bed\bd_\b_b\bbi\bit\btm\bma\bap\bp_\b_r\bre\beg\bgi\bio\bon\bn *\b**\b**\b**\b**\b*\n void al_draw_tinted_bitmap_region(ALLEGRO_BITMAP *bitmap,\n ALLEGRO_COLOR tint,\n float sx, float sy, float sw, float sh, float dx, float dy,\n int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\br_\be_\bg_\bi_\bo_\bn but multiplies all colors in the bitmap with the\n given color.\n See _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp for a note on restrictions on which bitmaps can be drawn\n where.\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bt_\bi_\bn_\bt_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp\n Examples:\n- * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n * _\be_\bx_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm_\b._\bc\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_p\bpi\bix\bxe\bel\bl *\b**\b**\b**\b**\b*\n void al_draw_pixel(float x, float y, ALLEGRO_COLOR color)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a single pixel at x, y. This function, unlike _\ba_\bl_\b__\bp_\bu_\bt_\b__\bp_\bi_\bx_\be_\bl, does blending\n and, unlike _\ba_\bl_\b__\bp_\bu_\bt_\b__\bb_\bl_\be_\bn_\bd_\be_\bd_\b__\bp_\bi_\bx_\be_\bl, respects the transformations (that is, the\n pixel\u2019s position is transformed, but its size is unaffected - it remains a\n pixel). This function can be slow if called often; if you need to draw a lot of\n@@ -1174,16 +1246,16 @@\n N\bNo\bot\bte\be:\b: This function may not draw exactly where you expect it to. See\n the _\bp_\bi_\bx_\be_\bl_\b-_\bp_\br_\be_\bc_\bi_\bs_\be_\b _\bo_\bu_\bt_\bp_\bu_\bt_\b _\bs_\be_\bc_\bt_\bi_\bo_\bn on the primitives addon\n documentation for details on how to control exactly where the pixel\n is drawn.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR, _\ba_\bl_\b__\bp_\bu_\bt_\b__\bp_\bi_\bx_\be_\bl\n Examples:\n * _\be_\bx_\b__\bd_\br_\ba_\bw_\bp_\bi_\bx_\be_\bl_\bs_\b._\bc\n- * _\be_\bx_\b__\br_\be_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\be_\bs_\bt_\b._\bc\n * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_r\bro\bot\bta\bat\bte\bed\bd_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n void al_draw_rotated_bitmap(ALLEGRO_BITMAP *bitmap,\n float cx, float cy, float dx, float dy, float angle, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a rotated version of the given bitmap to the target bitmap. The bitmap is\n rotated by \u2018angle\u2019 radians clockwise.\n The point at cx/cy relative to the upper left corner of the bitmap will be\n@@ -1202,16 +1274,16 @@\n The above code draws the bitmap centered on x/y and rotates it 90\u00b0 clockwise.\n See _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp for a note on restrictions on which bitmaps can be drawn\n where.\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\br_\be_\bg_\bi_\bo_\bn, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bs_\bc_\ba_\bl_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp,\n _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bs_\bc_\ba_\bl_\be_\bd_\b__\br_\bo_\bt_\ba_\bt_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp\n Examples:\n * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b2_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bm_\bu_\bl_\bt_\bi_\bs_\ba_\bm_\bp_\bl_\be_\b._\bc\n * _\be_\bx_\b__\bm_\bu_\bl_\bt_\bi_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n- * _\be_\bx_\b__\bp_\ba_\bl_\be_\bt_\bt_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_t\bti\bin\bnt\bte\bed\bd_\b_r\bro\bot\bta\bat\bte\bed\bd_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n void al_draw_tinted_rotated_bitmap(ALLEGRO_BITMAP *bitmap,\n ALLEGRO_COLOR tint,\n float cx, float cy, float dx, float dy, float angle, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\br_\bo_\bt_\ba_\bt_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp but multiplies all colors in the bitmap with the\n given color.\n@@ -1238,16 +1310,16 @@\n * flags - same as for _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp\n See _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp for a note on restrictions on which bitmaps can be drawn\n where.\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\br_\be_\bg_\bi_\bo_\bn, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bs_\bc_\ba_\bl_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp,\n _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\br_\bo_\bt_\ba_\bt_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp\n Examples:\n * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bb_\be_\bn_\bc_\bh_\b._\bc\n- * _\be_\bx_\b__\bp_\br_\be_\bm_\bu_\bl_\ba_\bl_\bp_\bh_\ba_\b._\bc\n- * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bm_\bu_\bl_\bt_\bi_\bt_\be_\bx_\b._\bc\n+ * _\be_\bx_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b._\bc\n+ * _\be_\bx_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bi_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_t\bti\bin\bnt\bte\bed\bd_\b_s\bsc\bca\bal\ble\bed\bd_\b_r\bro\bot\bta\bat\bte\bed\bd_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n void al_draw_tinted_scaled_rotated_bitmap(ALLEGRO_BITMAP *bitmap,\n ALLEGRO_COLOR tint,\n float cx, float cy, float dx, float dy, float xscale, float yscale,\n float angle, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bs_\bc_\ba_\bl_\be_\bd_\b__\br_\bo_\bt_\ba_\bt_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp but multiplies all colors in the bitmap with\n@@ -1298,15 +1370,15 @@\n See _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp for a note on restrictions on which bitmaps can be drawn\n where.\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\br_\be_\bg_\bi_\bo_\bn, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\br_\bo_\bt_\ba_\bt_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp,\n _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bs_\bc_\ba_\bl_\be_\bd_\b__\br_\bo_\bt_\ba_\bt_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp,\n Examples:\n * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bb_\be_\bn_\bc_\bh_\b._\bc\n * _\be_\bx_\b__\bd_\bu_\ba_\bl_\bi_\be_\bs_\b._\bc\n- * _\be_\bx_\b__\bm_\be_\bm_\bb_\bm_\bp_\b._\bc\n+ * _\be_\bx_\b__\bm_\bu_\bl_\bt_\bi_\bw_\bi_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_t\bti\bin\bnt\bte\bed\bd_\b_s\bsc\bca\bal\ble\bed\bd_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n void al_draw_tinted_scaled_bitmap(ALLEGRO_BITMAP *bitmap,\n ALLEGRO_COLOR tint,\n float sx, float sy, float sw, float sh,\n float dx, float dy, float dw, float dh, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bs_\bc_\ba_\bl_\be_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp but multiplies all colors in the bitmap with the\n@@ -1319,26 +1391,30 @@\n * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b2_\b._\bc_\bp_\bp\n * _\be_\bx_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_t\bta\bar\brg\bge\bet\bt_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n ALLEGRO_BITMAP *al_get_target_bitmap(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the target bitmap of the calling thread.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bt_\ba_\br_\bg_\be_\bt_\b__\bb_\bi_\bt_\bm_\ba_\bp\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bj_\bu_\bs_\bt_\bi_\bf_\by_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\br_\be_\bs_\bi_\bz_\be_\b._\bc\n+ * _\be_\bx_\b__\bm_\be_\bm_\bb_\bm_\bp_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_p\bpu\but\bt_\b_p\bpi\bix\bxe\bel\bl *\b**\b**\b**\b**\b*\n void al_put_pixel(int x, int y, ALLEGRO_COLOR color)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draw a single pixel on the target bitmap. This operation is slow on non-memory\n bitmaps. Consider locking the bitmap if you are going to use this function\n multiple times on the same bitmap. This function is not affected by the\n transformations or the color blenders.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR, _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\bi_\bx_\be_\bl, _\ba_\bl_\b__\bp_\bu_\bt_\b__\bb_\bl_\be_\bn_\bd_\be_\bd_\b__\bp_\bi_\bx_\be_\bl, _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bb_\bi_\bt_\bm_\ba_\bp\n Examples:\n * _\be_\bx_\b__\bd_\br_\ba_\bw_\bp_\bi_\bx_\be_\bl_\bs_\b._\bc\n- * _\be_\bx_\b__\bi_\bc_\bo_\bn_\b._\bc\n * _\be_\bx_\b__\bi_\bc_\bo_\bn_\b2_\b._\bc\n+ * _\be_\bx_\b__\bi_\bc_\bo_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_p\bpu\but\bt_\b_b\bbl\ble\ben\bnd\bde\bed\bd_\b_p\bpi\bix\bxe\bel\bl *\b**\b**\b**\b**\b*\n void al_put_blended_pixel(int x, int y, ALLEGRO_COLOR color)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bp_\bu_\bt_\b__\bp_\bi_\bx_\be_\bl, but the pixel color is blended using the current blenders\n before being drawn.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR, _\ba_\bl_\b__\bp_\bu_\bt_\b__\bp_\bi_\bx_\be_\bl\n *\b**\b**\b**\b**\b**\b* T\bTa\bar\brg\bge\bet\bt b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b**\b*\n@@ -1387,25 +1463,37 @@\n The above allows using _\ba_\bl_\b__\bp_\bu_\bt_\b__\bp_\bi_\bx_\be_\bl on a locked bitmap without creating an FBO.\n In this example an FBO is created however:\n al_set_target_bitmap(bitmap);\n al_draw_line(x1, y1, x2, y2, color, 0);\n An OpenGL command will be used to directly draw the line into the bitmap\u2019s\n associated texture.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\ba_\br_\bg_\be_\bt_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bs_\be_\bt_\b__\bt_\ba_\br_\bg_\be_\bt_\b__\bb_\ba_\bc_\bk_\bb_\bu_\bf_\bf_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bn_\bo_\bd_\bi_\bs_\bp_\bl_\ba_\by_\b._\bc\n+ * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\bp_\bi_\bx_\be_\bl_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bb_\be_\bn_\bc_\bh_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_t\bta\bar\brg\bge\bet\bt_\b_b\bba\bac\bck\bkb\bbu\buf\bff\bfe\ber\br *\b**\b**\b**\b**\b*\n void al_set_target_backbuffer(ALLEGRO_DISPLAY *display)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Same as al_set_target_bitmap(al_get_backbuffer(display));\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bt_\ba_\br_\bg_\be_\bt_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\bg_\be_\bt_\b__\bb_\ba_\bc_\bk_\bb_\bu_\bf_\bf_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n+ * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\bp_\bi_\bx_\be_\bl_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_c\bcu\bur\brr\bre\ben\bnt\bt_\b_d\bdi\bis\bsp\bpl\bla\bay\by *\b**\b**\b**\b**\b*\n ALLEGRO_DISPLAY *al_get_current_display(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the display that is \u201ccurrent\u201d for the calling thread, or NULL if there\n is none.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bt_\ba_\br_\bg_\be_\bt_\b__\bb_\bi_\bt_\bm_\ba_\bp\n+Examples:\n+ * _\bc_\bo_\bm_\bm_\bo_\bn_\b._\bc\n+ * _\be_\bx_\b__\bv_\bs_\by_\bn_\bc_\b._\bc\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b2_\b._\bc\n *\b**\b**\b**\b**\b**\b* B\bBl\ble\ben\bnd\bdi\bin\bng\bg m\bmo\bod\bde\bes\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_b\bbl\ble\ben\bnd\bde\ber\br *\b**\b**\b**\b**\b*\n void al_get_blender(int *op, int *src, int *dst)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the active blender for the current thread. You can pass NULL for values\n you are not interested in.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bb_\bl_\be_\bn_\bd_\be_\br, _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\be_\bp_\ba_\br_\ba_\bt_\be_\b__\bb_\bl_\be_\bn_\bd_\be_\br\n@@ -1500,31 +1588,41 @@\n al_set_blend_color(al_map_rgba_f(0.5, 0.5, 0.5, 0.5));\n As formula:\n r = d.r * 0 + s.r * d.r\n g = d.g * 0 + s.g * d.g\n b = d.b * 0 + s.b * d.b\n a = d.a * 0 + s.a * d.a\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\be_\bp_\ba_\br_\ba_\bt_\be_\b__\bb_\bl_\be_\bn_\bd_\be_\br, _\ba_\bl_\b__\bs_\be_\bt_\b__\bb_\bl_\be_\bn_\bd_\b__\bc_\bo_\bl_\bo_\br, _\ba_\bl_\b__\bg_\be_\bt_\b__\bb_\bl_\be_\bn_\bd_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bb_\be_\bn_\bc_\bh_\b._\bc\n+ * _\be_\bx_\b__\br_\bo_\bt_\ba_\bt_\be_\b._\bc\n+ * _\be_\bx_\b__\bm_\be_\bm_\bb_\bm_\bp_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bse\bep\bpa\bar\bra\bat\bte\be_\b_b\bbl\ble\ben\bnd\bde\ber\br *\b**\b**\b**\b**\b*\n void al_set_separate_blender(int op, int src, int dst,\n int alpha_op, int alpha_src, int alpha_dst)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bs_\be_\bt_\b__\bb_\bl_\be_\bn_\bd_\be_\br, but allows specifying a separate blending operation for\n the alpha channel. This is useful if your target bitmap also has an alpha\n channel and the two alpha channels need to be combined in a different way than\n the color components.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bb_\bl_\be_\bn_\bd_\be_\br, _\ba_\bl_\b__\bg_\be_\bt_\b__\bb_\bl_\be_\bn_\bd_\be_\br, _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\be_\bp_\ba_\br_\ba_\bt_\be_\b__\bb_\bl_\be_\bn_\bd_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b2_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bl_\bo_\bg_\bo_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_b\bbl\ble\ben\bnd\bd_\b_c\bco\bol\blo\bor\br *\b**\b**\b**\b**\b*\n void al_set_blend_color(ALLEGRO_COLOR color)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets the color to use for blending when using the ALLEGRO_CONST_COLOR or\n ALLEGRO_INVERSE_CONST_COLOR blend functions. See _\ba_\bl_\b__\bs_\be_\bt_\b__\bb_\bl_\be_\bn_\bd_\be_\br for more\n information.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bb_\bl_\be_\bn_\bd_\be_\br, _\ba_\bl_\b__\bg_\be_\bt_\b__\bb_\bl_\be_\bn_\bd_\b__\bc_\bo_\bl_\bo_\br\n Since: 5.1.12\n+Examples:\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b2_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* C\bCl\bli\bip\bpp\bpi\bin\bng\bg *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_c\bcl\bli\bip\bpp\bpi\bin\bng\bg_\b_r\bre\bec\bct\bta\ban\bng\bgl\ble\be *\b**\b**\b**\b**\b*\n void al_get_clipping_rectangle(int *x, int *y, int *w, int *h)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Gets the clipping rectangle of the target bitmap.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bc_\bl_\bi_\bp_\bp_\bi_\bn_\bg_\b__\br_\be_\bc_\bt_\ba_\bn_\bg_\bl_\be\n Examples:\n@@ -1534,17 +1632,17 @@\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_c\bcl\bli\bip\bpp\bpi\bin\bng\bg_\b_r\bre\bec\bct\bta\ban\bng\bgl\ble\be *\b**\b**\b**\b**\b*\n void al_set_clipping_rectangle(int x, int y, int width, int height)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the region of the target bitmap or display that pixels get clipped to. The\n default is to clip pixels to the entire bitmap.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bc_\bl_\bi_\bp_\bp_\bi_\bn_\bg_\b__\br_\be_\bc_\bt_\ba_\bn_\bg_\bl_\be, _\ba_\bl_\b__\br_\be_\bs_\be_\bt_\b__\bc_\bl_\bi_\bp_\bp_\bi_\bn_\bg_\b__\br_\be_\bc_\bt_\ba_\bn_\bg_\bl_\be\n Examples:\n- * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n- * _\be_\bx_\b__\bl_\bi_\bn_\be_\bs_\b._\bc\n * _\be_\bx_\b__\br_\bo_\bt_\ba_\bt_\be_\b._\bc\n+ * _\be_\bx_\b__\bs_\bc_\ba_\bl_\be_\b._\bc\n+ * _\be_\bx_\b__\bl_\bi_\bn_\be_\bs_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bes\bse\bet\bt_\b_c\bcl\bli\bip\bpp\bpi\bin\bng\bg_\b_r\bre\bec\bct\bta\ban\bng\bgl\ble\be *\b**\b**\b**\b**\b*\n void al_reset_clipping_rectangle(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Equivalent to calling `al_set_clipping_rectangle(0, 0, w, h)\u2019 where w\bw and h\bh are\n the width and height of the target bitmap respectively.\n Does nothing if there is no target bitmap.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bc_\bl_\bi_\bp_\bp_\bi_\bn_\bg_\b__\br_\be_\bc_\bt_\ba_\bn_\bg_\bl_\be\n@@ -1553,16 +1651,16 @@\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bon\bnv\bve\ber\brt\bt_\b_m\bma\bas\bsk\bk_\b_t\bto\bo_\b_a\bal\blp\bph\bha\ba *\b**\b**\b**\b**\b*\n void al_convert_mask_to_alpha(ALLEGRO_BITMAP *bitmap, ALLEGRO_COLOR mask_color)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert the given mask color to an alpha channel in the bitmap. Can be used to\n convert older 4.2-style bitmaps with magic pink to alpha-ready bitmaps.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR\n Examples:\n- * _\be_\bx_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b._\bc\n * _\be_\bx_\b__\ba_\bn_\bd_\br_\bo_\bi_\bd_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b._\bc\n *\b**\b**\b**\b**\b**\b* D\bDe\bef\bfe\ber\brr\bre\bed\bd d\bdr\bra\baw\bwi\bin\bng\bg *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_h\bho\bol\bld\bd_\b_b\bbi\bit\btm\bma\bap\bp_\b_d\bdr\bra\baw\bwi\bin\bng\bg *\b**\b**\b**\b**\b*\n void al_hold_bitmap_drawing(bool hold)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Enables or disables deferred bitmap drawing. This allows for efficient drawing\n of many bitmaps that share a parent bitmap, such as sub-bitmaps from a\n tilesheet or simply identical bitmaps. Drawing bitmaps that do not share a\n@@ -1578,16 +1676,16 @@\n as many bitmaps as possible, taking care to stagger bitmaps that share parent\n bitmaps, and then disable deferred drawing. As mentioned above, this function\n also works with bitmap and truetype fonts, so if multiple lines of text need to\n be drawn, this function can speed things up.\n See also: _\ba_\bl_\b__\bi_\bs_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bd_\br_\ba_\bw_\bi_\bn_\bg_\b__\bh_\be_\bl_\bd\n Examples:\n * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bm_\ba_\bs_\bk_\b._\bc\n- * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n * _\be_\bx_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b._\bc\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_b\bbi\bit\btm\bma\bap\bp_\b_d\bdr\bra\baw\bwi\bin\bng\bg_\b_h\bhe\bel\bld\bd *\b**\b**\b**\b**\b*\n bool al_is_bitmap_drawing_held(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns whether the deferred bitmap drawing mode is turned on or off.\n See also: _\ba_\bl_\b__\bh_\bo_\bl_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bd_\br_\ba_\bw_\bi_\bn_\bg\n *\b**\b**\b**\b**\b**\b* I\bIm\bma\bag\bge\be I\bI/\b/O\bO *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\beg\bgi\bis\bst\bte\ber\br_\b_b\bbi\bit\btm\bma\bap\bp_\b_l\blo\boa\bad\bde\ber\br *\b**\b**\b**\b**\b*\n@@ -1649,16 +1747,16 @@\n N\bNo\bot\bte\be:\b: the core Allegro library does not support any image file\n formats by default. You must use the allegro_image addon, or register\n your own format handler.\n See also: _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs, _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf, _\ba_\bl_\b__\br_\be_\bg_\bi_\bs_\bt_\be_\br_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bl_\bo_\ba_\bd_\be_\br,\n _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bo_\br_\bm_\ba_\bt, _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs, _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bi_\bm_\ba_\bg_\be_\b__\ba_\bd_\bd_\bo_\bn\n Examples:\n * _\be_\bx_\b__\bc_\bo_\bn_\bv_\be_\br_\bt_\b._\bc\n- * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b._\bc\n- * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\bp_\bi_\bx_\be_\bl_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bn_\bo_\bd_\bi_\bs_\bp_\bl_\ba_\by_\b._\bc\n+ * _\be_\bx_\b__\bf_\bi_\bl_\be_\b__\bs_\bl_\bi_\bc_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boa\bad\bd_\b_b\bbi\bit\btm\bma\bap\bp_\b_f\bfl\bla\bag\bgs\bs *\b**\b**\b**\b**\b*\n ALLEGRO_BITMAP *al_load_bitmap_flags(const char *filename, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Loads an image file into a new _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bB_\bI_\bT_\bM_\bA_\bP. The file type is determined by\n _\ba_\bl_\b__\bi_\bd_\be_\bn_\bt_\bi_\bf_\by_\b__\bb_\bi_\bt_\bm_\ba_\bp, using the extension as a fallback in case identification is\n not possible.\n Returns NULL on error.\n@@ -1750,16 +1848,16 @@\n N\bNo\bot\bte\be:\b: the core Allegro library does not support any image file\n formats by default. You must use the allegro_image addon, or register\n your own format handler.\n See also: _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\ba_\bg_\bs_\b__\bf, _\ba_\bl_\b__\bl_\bo_\ba_\bd_\b__\bb_\bi_\bt_\bm_\ba_\bp, _\ba_\bl_\b__\br_\be_\bg_\bi_\bs_\bt_\be_\br_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bl_\bo_\ba_\bd_\be_\br_\b__\bf,\n _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bi_\bm_\ba_\bg_\be_\b__\ba_\bd_\bd_\bo_\bn\n Examples:\n * _\be_\bx_\b__\bc_\bo_\bn_\bv_\be_\br_\bt_\b._\bc\n- * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bn_\ba_\bm_\be_\b._\bc\n- * _\be_\bx_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bl_\bi_\bp_\b._\bc\n+ * _\be_\bx_\b__\bf_\bi_\bl_\be_\b__\bs_\bl_\bi_\bc_\be_\b._\bc\n+ * _\be_\bx_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf_\bi_\bl_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boa\bad\bd_\b_b\bbi\bit\btm\bma\bap\bp_\b_f\bfl\bla\bag\bgs\bs_\b_f\bf *\b**\b**\b**\b**\b*\n ALLEGRO_BITMAP *al_load_bitmap_flags_f(ALLEGRO_FILE *fp,\n const char *ident, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Loads an image from an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bF_\bI_\bL_\bE stream into a new _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bB_\bI_\bT_\bM_\bA_\bP. The file\n type is determined by _\ba_\bl_\b__\bi_\bd_\be_\bn_\bt_\bi_\bf_\by_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bf. If identification is not possible,\n the passed \u2018ident\u2019 parameter, which is a file name extension including the\n@@ -1837,15 +1935,16 @@\n including the leading dot. For example \u201c.png\u201d or \u201c.jpg\u201d. Returns NULL if the\n bitmap type cannot be determined.\n Since: 5.1.12\n See also: _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bi_\bm_\ba_\bg_\be_\b__\ba_\bd_\bd_\bo_\bn, _\ba_\bl_\b__\bi_\bd_\be_\bn_\bt_\bi_\bf_\by_\b__\bb_\bi_\bt_\bm_\ba_\bp,\n _\ba_\bl_\b__\br_\be_\bg_\bi_\bs_\bt_\be_\br_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b__\bi_\bd_\be_\bn_\bt_\bi_\bf_\bi_\be_\br\n *\b**\b**\b**\b**\b**\b* R\bRe\ben\bnd\bde\ber\br S\bSt\bta\bat\bte\be *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_R\bRE\bEN\bND\bDE\bER\bR_\b_S\bST\bTA\bAT\bTE\bE *\b**\b**\b**\b**\b*\n-Source Code\n+typedef enum ALLEGRO_RENDER_STATE {\n+_\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Possible render states which can be set with _\ba_\bl_\b__\bs_\be_\bt_\b__\br_\be_\bn_\bd_\be_\br_\b__\bs_\bt_\ba_\bt_\be:\n ALLEGRO_ALPHA_TEST\n If this is set to 1, the values of ALLEGRO_ALPHA_FUNCTION and\n ALLEGRO_ALPHA_TEST_VALUE define a comparison function which is performed\n on the alpha component of each pixel. Only if it evaluates to true the\n pixel is written. Otherwise no subsequent processing (like depth test or\n blending) is performed. This can be very useful, for example if a depth\n@@ -1866,28 +1965,30 @@\n will write a value of 0 into the depth buffer.\n ALLEGRO_DEPTH_FUNCTION\n One of _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bR_\bE_\bN_\bD_\bE_\bR_\b__\bF_\bU_\bN_\bC_\bT_\bI_\bO_\bN, only used when ALLEGRO_DEPTH_TEST is 1.\n Since: 5.1.2\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\br_\be_\bn_\bd_\be_\br_\b__\bs_\bt_\ba_\bt_\be, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bR_\bE_\bN_\bD_\bE_\bR_\b__\bF_\bU_\bN_\bC_\bT_\bI_\bO_\bN,\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bW_\bR_\bI_\bT_\bE_\b__\bM_\bA_\bS_\bK_\b__\bF_\bL_\bA_\bG_\bS\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_R\bRE\bEN\bND\bDE\bER\bR_\b_F\bFU\bUN\bNC\bCT\bTI\bIO\bON\bN *\b**\b**\b**\b**\b*\n-Source Code\n+typedef enum ALLEGRO_RENDER_FUNCTION {\n+_\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Possible functions are:\n * ALLEGRO_RENDER_NEVER\n * ALLEGRO_RENDER_ALWAYS\n * ALLEGRO_RENDER_LESS\n * ALLEGRO_RENDER_EQUAL\n * ALLEGRO_RENDER_LESS_EQUAL\n * ALLEGRO_RENDER_GREATER\n * ALLEGRO_RENDER_NOT_EQUAL\n * ALLEGRO_RENDER_GREATER_EQUAL\n Since: 5.1.2\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\br_\be_\bn_\bd_\be_\br_\b__\bs_\bt_\ba_\bt_\be\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_W\bWR\bRI\bIT\bTE\bE_\b_M\bMA\bAS\bSK\bK_\b_F\bFL\bLA\bAG\bGS\bS *\b**\b**\b**\b**\b*\n-Source Code\n+typedef enum ALLEGRO_WRITE_MASK_FLAGS {\n+_\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Each enabled bit means the corresponding value is written, a disabled bit means\n it is not.\n * ALLEGRO_MASK_RED\n * ALLEGRO_MASK_GREEN\n * ALLEGRO_MASK_BLUE\n * ALLEGRO_MASK_ALPHA\n * ALLEGRO_MASK_DEPTH\n@@ -1908,17 +2009,17 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set one of several render attributes; see _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bR_\bE_\bN_\bD_\bE_\bR_\b__\bS_\bT_\bA_\bT_\bE for details.\n This function does nothing if the target bitmap is a memory bitmap.\n Since: 5.1.2\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\br_\be_\bn_\bd_\be_\br_\b__\bs_\bt_\ba_\bt_\be, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bR_\bE_\bN_\bD_\bE_\bR_\b__\bS_\bT_\bA_\bT_\bE, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bR_\bE_\bN_\bD_\bE_\bR_\b__\bF_\bU_\bN_\bC_\bT_\bI_\bO_\bN,\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bW_\bR_\bI_\bT_\bE_\b__\bM_\bA_\bS_\bK_\b__\bF_\bL_\bA_\bG_\bS\n Examples:\n- * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bm_\ba_\bs_\bk_\b._\bc\n- * _\be_\bx_\b__\bc_\ba_\bm_\be_\br_\ba_\b._\bc\n+ * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bd_\br_\ba_\bw_\b__\bb_\bi_\bt_\bm_\ba_\bp_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_b\bba\bac\bck\bku\bup\bp_\b_d\bdi\bir\brt\bty\by_\b_b\bbi\bit\btm\bma\bap\bp *\b**\b**\b**\b**\b*\n void al_backup_dirty_bitmap(ALLEGRO_BITMAP *bitmap)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n On some platforms, notably Windows Direct3D and Android, textures may be lost\n at any time for events such as display resize or switching out of the app. On\n those platforms, bitmaps created without the ALLEGRO_NO_PRESERVE_TEXTURE flag\n automatically get backed up to system memory every time al_flip_display is\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/haptic.html", "source2": "./usr/share/doc/allegro5-doc/refman/haptic.html", "unified_diff": "@@ -265,14 +265,21 @@\n

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

    \n
    \n

    See also: al_get_haptic_from_joystick

    \n+

    Examples:

    \n+
      \n+
    • ex_haptic.c
      • \n+
    • ex_haptic2.cpp
      • \n+
    \n

    ALLEGRO_HAPTIC_CONSTANTS

    \n 
    enum ALLEGRO_HAPTIC_CONSTANTS
    \n

    Source\n Code

    \n

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

    \n
    \n

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

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_haptic.c
      • \n+
    • ex_haptic2.cpp
      • \n+
    \n

    ALLEGRO_HAPTIC_EFFECT_ID

    \n 
    typedef struct ALLEGRO_HAPTIC_EFFECT_ID ALLEGRO_HAPTIC_EFFECT_ID;
    \n

    Source\n Code

    \n

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

    Since: 5.1.8

    \n
    \n

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

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_haptic.c
      • \n+
    • ex_haptic2.cpp
      • \n+
    \n

    al_install_haptic

    \n 
    bool al_install_haptic(void)
    \n

    Source\n Code

    \n

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

    Since: 5.1.8

    \n
    \n

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

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_haptic.c
      • \n+
    • ex_haptic2.cpp
      • \n+
    \n

    al_is_haptic_active

    \n 
    bool al_is_haptic_active(ALLEGRO_HAPTIC *hap)
    \n

    Source\n Code

    \n

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

    \n@@ -1201,14 +1229,21 @@\n

    Since: 5.1.8

    \n
    \n

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

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_haptic.c
      • \n+
    • ex_haptic2.cpp
      • \n+
    \n

    al_rumble_haptic

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

    Source\n Code

    \n

    Uploads a simple rumble effect to the haptic device and starts\n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -90,14 +90,17 @@\n This is an abstract data type representing a haptic device that supports force\n feedback or vibration.\n Since: 5.1.8\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: Perhaps could be simplified due to limited support for\n all the exposed features across all of the platforms. Awaiting\n feedback from users.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b__\bf_\br_\bo_\bm_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk\n+Examples:\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b._\bc\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b2_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_H\bHA\bAP\bPT\bTI\bIC\bC_\b_C\bCO\bON\bNS\bST\bTA\bAN\bNT\bTS\bS *\b**\b**\b**\b**\b**\b*\n enum ALLEGRO_HAPTIC_CONSTANTS\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This enum contains flags that are used to define haptic effects and\n capabilities. If the flag is set in the return value of\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b__\bc_\ba_\bp_\ba_\bb_\bi_\bl_\bi_\bt_\bi_\be_\bs, it means the device supports the given effect. The\n value of these flags should be set into a _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bH_\bA_\bP_\bT_\bI_\bC_\b__\bE_\bF_\bF_\bE_\bC_\bT struct to\n@@ -283,24 +286,30 @@\n If you don\u2019t want to use an envelope, then set all four fields of\n data.envelope to 0.0. The effect will then play back at full intensity\n throughout its playback.\n Since: 5.1.8\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: Perhaps could be simplified due to limited support for\n all the exposed features across all of the platforms. Awaiting\n feedback from users.\n+Examples:\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b._\bc\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b2_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_H\bHA\bAP\bPT\bTI\bIC\bC_\b_E\bEF\bFF\bFE\bEC\bCT\bT_\b_I\bID\bD *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_HAPTIC_EFFECT_ID ALLEGRO_HAPTIC_EFFECT_ID;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This struct is used as a handle to control playback of a haptic effect and\n should be considered opaque. Its implementation is visible merely to allow\n allocation by the users of the Allegro library.\n Since: 5.1.8\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: Perhaps could be simplified due to limited support for\n all the exposed features across all of the platforms. Awaiting\n feedback from users.\n+Examples:\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b._\bc\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b2_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bns\bst\bta\bal\bll\bl_\b_h\bha\bap\bpt\bti\bic\bc *\b**\b**\b**\b**\b**\b*\n bool al_install_haptic(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Installs the haptic (force feedback) device subsystem. This must be called\n before using any other haptic-related functions. Returns true if the haptics\n subsystem could be initialized correctly, false in case of error.\n For portability you should first open a display before calling\n@@ -447,14 +456,17 @@\n Returns true on success or false if the haptic device couldn\u2019t be released for\n any reason, such as NULL being passed, the device not being active or failure\n in the driver.\n Since: 5.1.8\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: Perhaps could be simplified due to limited support for\n all the exposed features across all of the platforms. Awaiting\n feedback from users.\n+Examples:\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b._\bc\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b2_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_h\bha\bap\bpt\bti\bic\bc_\b_a\bac\bct\bti\biv\bve\be *\b**\b**\b**\b**\b**\b*\n bool al_is_haptic_active(ALLEGRO_HAPTIC *hap)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if the haptic device can currently be used, false if not.\n Since: 5.1.8\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: Perhaps could be simplified due to limited support for\n all the exposed features across all of the platforms. Awaiting\n@@ -682,14 +694,17 @@\n Returns true on success, false if the effect couldn\u2019t be released for any\n reason such as when NULL is passed, the effect is not active or failure to\n release the effect by the driver.\n Since: 5.1.8\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: Perhaps could be simplified due to limited support for\n all the exposed features across all of the platforms. Awaiting\n feedback from users.\n+Examples:\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b._\bc\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b2_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bru\bum\bmb\bbl\ble\be_\b_h\bha\bap\bpt\bti\bic\bc *\b**\b**\b**\b**\b**\b*\n bool al_rumble_haptic(ALLEGRO_HAPTIC *hap,\n double intensity, double duration, ALLEGRO_HAPTIC_EFFECT_ID *id)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Uploads a simple rumble effect to the haptic device and starts playback\n immediately. The parameter intensity is a relative magnitude between 0.0 and\n 1.0 that determines the intensity of the rumble effect. The duration determines\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/image.html", "source2": "./usr/share/doc/allegro5-doc/refman/image.html", "unified_diff": "@@ -207,14 +207,23 @@\n installed libraries, but are not guaranteed and should not be assumed to\n be universally available.

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_convert.c
      • \n+
    • ex_nodisplay.c
      • \n+
    • ex_opengl_pixel_shader.c
      • \n+
    \n al_is_image_addon_initialized\n 
    bool al_is_image_addon_initialized(void)
    \n

    Source\n Code

    \n

    Returns true if the image addon is initialized, otherwise returns\n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -64,14 +64,18 @@\n Other formats may be available depending on the operating system and installed\n libraries, but are not guaranteed and should not be assumed to be universally\n available.\n The DDS format is only supported to load from, and only if the DDS file\n contains textures compressed in the DXT1, DXT3 and DXT5 formats. Note that when\n loading a DDS file, the created bitmap will always be a video bitmap and will\n have the pixel format matching the format in the file.\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bn_\bv_\be_\br_\bt_\b._\bc\n+ * _\be_\bx_\b__\bn_\bo_\bd_\bi_\bs_\bp_\bl_\ba_\by_\b._\bc\n+ * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\bp_\bi_\bx_\be_\bl_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_i\bim\bma\bag\bge\be_\b_a\bad\bdd\bdo\bon\bn_\b_i\bin\bni\bit\bti\bia\bal\bli\biz\bze\bed\bd *\b**\b**\b**\b**\b**\b*\n bool al_is_image_addon_initialized(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if the image addon is initialized, otherwise returns false.\n Since: 5.2.6\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bsh\bhu\but\btd\bdo\bow\bwn\bn_\b_i\bim\bma\bag\bge\be_\b_a\bad\bdd\bdo\bon\bn *\b**\b**\b**\b**\b**\b*\n void al_shutdown_image_addon(void)\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/joystick.html", "source2": "./usr/share/doc/allegro5-doc/refman/joystick.html", "unified_diff": "@@ -230,28 +230,44 @@\n 

    typedef struct ALLEGRO_JOYSTICK ALLEGRO_JOYSTICK;
    \n

    Source\n Code

    \n

    This is an abstract data type representing a physical joystick.

    \n

    See also: al_get_joystick

    \n+

    Examples:

    \n+
      \n+
    • ex_haptic.c
      • \n+
    • ex_joystick_hotplugging.c
      • \n+
    • ex_joystick_events.c
      • \n+
    \n

    ALLEGRO_JOYSTICK_STATE

    \n 
    typedef struct ALLEGRO_JOYSTICK_STATE ALLEGRO_JOYSTICK_STATE;
    \n

    Source\n Code

    \n

    This is a structure that is used to hold a \u201csnapshot\u201d of a joystick\u2019s\n axes and buttons at a particular instant. All fields public and\n read-only.

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

    See also: al_get_joystick_state

    \n+

    Examples:

    \n+
      \n+
    • ex_joystick_hotplugging.c
      • \n+
    • ex_joystick_events.c
      • \n+
    \n

    ALLEGRO_JOYFLAGS

    \n 
    enum ALLEGRO_JOYFLAGS
    \n

    Source\n Code

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

      Source\n Code

      \n

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

      \n

      See also: al_uninstall_joystick

      \n+

      Examples:

      \n+
        \n+
      • ex_haptic.c
        • \n+
      • ex_joystick_hotplugging.c
        • \n+
      • ex_joystick_events.c
        • \n+
      \n

      al_uninstall_joystick

      \n 
      void al_uninstall_joystick(void)
      \n

      Source\n Code

      \n

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

      \n

      See also: al_get_joystick_event_source,\n ALLEGRO_EVENT

      \n+

      Examples:

      \n+
        \n+
      • ex_joystick_hotplugging.c
        • \n+
      • ex_joystick_events.c
        • \n+
      • ex_haptic2.cpp
        • \n+
      \n

      al_get_num_joysticks

      \n 
      int al_get_num_joysticks(void)
      \n

      Source\n Code

      \n

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

      \n

      Returns 0 if there is no joystick driver installed.

      \n

      See also: al_get_joystick, al_get_joystick_active

      \n+

      Examples:

      \n+
        \n+
      • ex_haptic.c
        • \n+
      • ex_joystick_hotplugging.c
        • \n+
      • ex_haptic2.cpp
        • \n+
      \n

      al_get_joystick

      \n 
      ALLEGRO_JOYSTICK * al_get_joystick(int num)
      \n

      Source\n Code

      \n

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

      See also: al_get_num_joysticks, al_reconfigure_joysticks,\n al_get_joystick_active

      \n+

      Examples:

      \n+
        \n+
      • ex_haptic.c
        • \n+
      • ex_joystick_hotplugging.c
        • \n+
      • ex_joystick_events.c
        • \n+
      \n

      al_release_joystick

      \n 
      void al_release_joystick(ALLEGRO_JOYSTICK *joy)
      \n

      Source\n Code

      \n

      This function currently does nothing.

      \n

      See also: al_get_joystick

      \n+

      Examples:

      \n+
        \n+
      • ex_haptic.c
        • \n+
      \n

      al_get_joystick_active

      \n 
      bool al_get_joystick_active(ALLEGRO_JOYSTICK *joy)
      \n

      Source\n Code

      \n

      Return if the joystick handle is \u201cactive\u201d, i.e.\u00a0in the current\n configuration, the handle represents some physical device plugged into\n the system. al_get_joystick\n returns active handles. After reconfiguration, active handles may become\n inactive, and vice versa.

      \n

      See also: al_reconfigure_joysticks

      \n+

      Examples:

      \n+
        \n+
      • ex_joystick_hotplugging.c
        • \n+
      \n

      al_get_joystick_name

      \n 
      const char *al_get_joystick_name(ALLEGRO_JOYSTICK *joy)
      \n

      Source\n Code

      \n

      Return the name of the given joystick.

      \n

      See also: al_get_joystick_stick_name,\n al_get_joystick_axis_name,\n al_get_joystick_button_name

      \n+

      Examples:

      \n+
        \n+
      • ex_haptic.c
        • \n+
      • ex_joystick_hotplugging.c
        • \n+
      • ex_joystick_events.c
        • \n+
      \n

      al_get_joystick_stick_name

      \n 
      const char *al_get_joystick_stick_name(ALLEGRO_JOYSTICK *joy, int stick)
      \n

      Source\n Code

      \n

      Return the name of the given \u201cstick\u201d. If the stick doesn\u2019t exist,\n NULL is returned.

      \n

      See also: al_get_joystick_axis_name,\n al_get_joystick_num_sticks

      \n+

      Examples:

      \n+
        \n+
      • ex_joystick_hotplugging.c
        • \n+
      • ex_joystick_events.c
        • \n+
      \n

      al_get_joystick_axis_name

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

      Source\n Code

      \n

      Return the name of the given axis. If the axis doesn\u2019t exist, NULL is\n returned. Indices begin from 0.

      \n

      See also: al_get_joystick_stick_name,\n al_get_joystick_num_axes

      \n+

      Examples:

      \n+
        \n+
      • ex_joystick_hotplugging.c
        • \n+
      • ex_joystick_events.c
        • \n+
      \n

      al_get_joystick_button_name

      \n 
      const char *al_get_joystick_button_name(ALLEGRO_JOYSTICK *joy, int button)
      \n

      Source\n Code

      \n

      Return the name of the given button. If the button doesn\u2019t exist,\n NULL is returned. Indices begin from 0.

      \n

      See also: al_get_joystick_stick_name,\n al_get_joystick_axis_name,\n al_get_joystick_num_buttons

      \n+

      Examples:

      \n+
        \n+
      • ex_joystick_hotplugging.c
        • \n+
      • ex_joystick_events.c
        • \n+
      \n

      al_get_joystick_stick_flags

      \n 
      int al_get_joystick_stick_flags(ALLEGRO_JOYSTICK *joy, int stick)
      \n

      Source\n Code

      \n

      Return the flags of the given \u201cstick\u201d. If the stick doesn\u2019t exist,\n NULL is returned. Indices begin from 0.

      \n@@ -439,51 +531,88 @@\n Code

      \n

      Return the number of \u201csticks\u201d on the given joystick. A stick has one\n or more axes.

      \n

      See also: al_get_joystick_num_axes,\n al_get_joystick_num_buttons

      \n+

      Examples:

      \n+
        \n+
      • ex_joystick_hotplugging.c
        • \n+
      • ex_joystick_events.c
        • \n+
      \n

      al_get_joystick_num_axes

      \n 
      int al_get_joystick_num_axes(ALLEGRO_JOYSTICK *joy, int stick)
      \n

      Source\n Code

      \n

      Return the number of axes on the given \u201cstick\u201d. If the stick doesn\u2019t\n exist, 0 is returned.

      \n

      See also: al_get_joystick_num_sticks

      \n+

      Examples:

      \n+
        \n+
      • ex_joystick_hotplugging.c
        • \n+
      • ex_joystick_events.c
        • \n+
      \n

      al_get_joystick_num_buttons

      \n 
      int al_get_joystick_num_buttons(ALLEGRO_JOYSTICK *joy)
      \n

      Source\n Code

      \n

      Return the number of buttons on the joystick.

      \n

      See also: al_get_joystick_num_sticks

      \n+

      Examples:

      \n+
        \n+
      • ex_joystick_hotplugging.c
        • \n+
      • ex_joystick_events.c
        • \n+
      \n

      al_get_joystick_state

      \n 
      void al_get_joystick_state(ALLEGRO_JOYSTICK *joy, ALLEGRO_JOYSTICK_STATE *ret_state)
      \n

      Source\n Code

      \n

      Get the current joystick state.

      \n

      See also: ALLEGRO_JOYSTICK_STATE,\n al_get_joystick_num_buttons,\n al_get_joystick_num_axes

      \n+

      Examples:

      \n+
        \n+
      • ex_joystick_hotplugging.c
        • \n+
      • ex_joystick_events.c
        • \n+
      \n

      al_get_joystick_event_source

      \n 
      ALLEGRO_EVENT_SOURCE *al_get_joystick_event_source(void)
      \n

      Source\n Code

      \n

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

      \n+

      Examples:

      \n+
        \n+
      • ex_joystick_hotplugging.c
        • \n+
      • ex_joystick_events.c
        • \n+
      • ex_haptic2.cpp
        • \n+
      \n

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

      \n \n \n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -74,37 +74,48 @@\n mutually exclusive. The haptics subsystem will use the same driver as the\n joystick system does.\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_J\bJO\bOY\bYS\bST\bTI\bIC\bCK\bK *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_JOYSTICK ALLEGRO_JOYSTICK;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This is an abstract data type representing a physical joystick.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk\n+Examples:\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_J\bJO\bOY\bYS\bST\bTI\bIC\bCK\bK_\b_S\bST\bTA\bAT\bTE\bE *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_JOYSTICK_STATE ALLEGRO_JOYSTICK_STATE;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This is a structure that is used to hold a \u201csnapshot\u201d of a joystick\u2019s axes and\n buttons at a particular instant. All fields public and read-only.\n struct {\n float axis[num_axes]; // -1.0 to 1.0\n } stick[num_sticks];\n int button[num_buttons]; // 0 to 32767\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bs_\bt_\ba_\bt_\be\n+Examples:\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_J\bJO\bOY\bYF\bFL\bLA\bAG\bGS\bS *\b**\b**\b**\b**\b**\b*\n enum ALLEGRO_JOYFLAGS\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n * ALLEGRO_JOYFLAG_DIGITAL - the stick provides digital input\n * ALLEGRO_JOYFLAG_ANALOGUE - the stick provides analogue input\n (this enum is a holdover from the old API and may be removed)\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bs_\bt_\bi_\bc_\bk_\b__\bf_\bl_\ba_\bg_\bs\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bns\bst\bta\bal\bll\bl_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk *\b**\b**\b**\b**\b**\b*\n bool al_install_joystick(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Install a joystick driver, returning true if successful. If a joystick driver\n was already installed, returns true immediately.\n See also: _\ba_\bl_\b__\bu_\bn_\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk\n+Examples:\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bni\bin\bns\bst\bta\bal\bll\bl_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk *\b**\b**\b**\b**\b**\b*\n void al_uninstall_joystick(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Uninstalls the active joystick driver. All outstanding _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bJ_\bO_\bY_\bS_\bT_\bI_\bC_\bK\n structures are invalidated. If no joystick driver was active, this function\n does nothing.\n This function is automatically called when Allegro is shut down.\n@@ -130,102 +141,147 @@\n again, being reused to represent newly connected devices.\n Returns true if the joystick configuration changed, otherwise returns false.\n It is possible that on some systems, Allegro won\u2019t be able to generate\n ALLEGRO_EVENT_JOYSTICK_CONFIGURATION events. If your game has an input\n configuration screen or similar, you may wish to call _\ba_\bl_\b__\br_\be_\bc_\bo_\bn_\bf_\bi_\bg_\bu_\br_\be_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\bs\n when entering that screen.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT\n+Examples:\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b2_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_n\bnu\bum\bm_\b_j\bjo\boy\bys\bst\bti\bic\bck\bks\bs *\b**\b**\b**\b**\b**\b*\n int al_get_num_joysticks(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the number of joysticks currently on the system (or potentially on the\n system). This number can change after _\ba_\bl_\b__\br_\be_\bc_\bo_\bn_\bf_\bi_\bg_\bu_\br_\be_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\bs is called, in\n order to support hotplugging.\n Returns 0 if there is no joystick driver installed.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk, _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\ba_\bc_\bt_\bi_\bv_\be\n+Examples:\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b2_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk *\b**\b**\b**\b**\b**\b*\n ALLEGRO_JOYSTICK * al_get_joystick(int num)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get a handle for a joystick on the system. The number may be from 0 to\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\bu_\bm_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\bs-1. If successful a pointer to a joystick object is\n returned, which represents a physical device. Otherwise NULL is returned.\n The handle and the index are only incidentally linked. After\n _\ba_\bl_\b__\br_\be_\bc_\bo_\bn_\bf_\bi_\bg_\bu_\br_\be_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\bs is called, _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk may return handles in a\n different order, and handles which represent disconnected devices will not be\n returned.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\bu_\bm_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\bs, _\ba_\bl_\b__\br_\be_\bc_\bo_\bn_\bf_\bi_\bg_\bu_\br_\be_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\bs,\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\ba_\bc_\bt_\bi_\bv_\be\n+Examples:\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bel\ble\bea\bas\bse\be_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk *\b**\b**\b**\b**\b**\b*\n void al_release_joystick(ALLEGRO_JOYSTICK *joy)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This function currently does nothing.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk\n+Examples:\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk_\b_a\bac\bct\bti\biv\bve\be *\b**\b**\b**\b**\b**\b*\n bool al_get_joystick_active(ALLEGRO_JOYSTICK *joy)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return if the joystick handle is \u201cactive\u201d, i.e.\u00a0in the current configuration,\n the handle represents some physical device plugged into the system.\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk returns active handles. After reconfiguration, active handles\n may become inactive, and vice versa.\n See also: _\ba_\bl_\b__\br_\be_\bc_\bo_\bn_\bf_\bi_\bg_\bu_\br_\be_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\bs\n+Examples:\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk_\b_n\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n const char *al_get_joystick_name(ALLEGRO_JOYSTICK *joy)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the name of the given joystick.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bs_\bt_\bi_\bc_\bk_\b__\bn_\ba_\bm_\be, _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\ba_\bx_\bi_\bs_\b__\bn_\ba_\bm_\be,\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bb_\bu_\bt_\bt_\bo_\bn_\b__\bn_\ba_\bm_\be\n+Examples:\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk_\b_s\bst\bti\bic\bck\bk_\b_n\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n const char *al_get_joystick_stick_name(ALLEGRO_JOYSTICK *joy, int stick)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the name of the given \u201cstick\u201d. If the stick doesn\u2019t exist, NULL is\n returned.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\ba_\bx_\bi_\bs_\b__\bn_\ba_\bm_\be, _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bn_\bu_\bm_\b__\bs_\bt_\bi_\bc_\bk_\bs\n+Examples:\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk_\b_a\bax\bxi\bis\bs_\b_n\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n const char *al_get_joystick_axis_name(ALLEGRO_JOYSTICK *joy, int stick, int\n axis)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the name of the given axis. If the axis doesn\u2019t exist, NULL is returned.\n Indices begin from 0.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bs_\bt_\bi_\bc_\bk_\b__\bn_\ba_\bm_\be, _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bn_\bu_\bm_\b__\ba_\bx_\be_\bs\n+Examples:\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk_\b_b\bbu\but\btt\bto\bon\bn_\b_n\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n const char *al_get_joystick_button_name(ALLEGRO_JOYSTICK *joy, int button)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the name of the given button. If the button doesn\u2019t exist, NULL is\n returned. Indices begin from 0.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bs_\bt_\bi_\bc_\bk_\b__\bn_\ba_\bm_\be, _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\ba_\bx_\bi_\bs_\b__\bn_\ba_\bm_\be,\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bn_\bu_\bm_\b__\bb_\bu_\bt_\bt_\bo_\bn_\bs\n+Examples:\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk_\b_s\bst\bti\bic\bck\bk_\b_f\bfl\bla\bag\bgs\bs *\b**\b**\b**\b**\b**\b*\n int al_get_joystick_stick_flags(ALLEGRO_JOYSTICK *joy, int stick)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the flags of the given \u201cstick\u201d. If the stick doesn\u2019t exist, NULL is\n returned. Indices begin from 0.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bJ_\bO_\bY_\bF_\bL_\bA_\bG_\bS\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk_\b_n\bnu\bum\bm_\b_s\bst\bti\bic\bck\bks\bs *\b**\b**\b**\b**\b**\b*\n int al_get_joystick_num_sticks(ALLEGRO_JOYSTICK *joy)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the number of \u201csticks\u201d on the given joystick. A stick has one or more\n axes.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bn_\bu_\bm_\b__\ba_\bx_\be_\bs, _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bn_\bu_\bm_\b__\bb_\bu_\bt_\bt_\bo_\bn_\bs\n+Examples:\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk_\b_n\bnu\bum\bm_\b_a\bax\bxe\bes\bs *\b**\b**\b**\b**\b**\b*\n int al_get_joystick_num_axes(ALLEGRO_JOYSTICK *joy, int stick)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the number of axes on the given \u201cstick\u201d. If the stick doesn\u2019t exist, 0\n is returned.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bn_\bu_\bm_\b__\bs_\bt_\bi_\bc_\bk_\bs\n+Examples:\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk_\b_n\bnu\bum\bm_\b_b\bbu\but\btt\bto\bon\bns\bs *\b**\b**\b**\b**\b**\b*\n int al_get_joystick_num_buttons(ALLEGRO_JOYSTICK *joy)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the number of buttons on the joystick.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bn_\bu_\bm_\b__\bs_\bt_\bi_\bc_\bk_\bs\n+Examples:\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk_\b_s\bst\bta\bat\bte\be *\b**\b**\b**\b**\b**\b*\n void al_get_joystick_state(ALLEGRO_JOYSTICK *joy, ALLEGRO_JOYSTICK_STATE\n *ret_state)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get the current joystick state.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bJ_\bO_\bY_\bS_\bT_\bI_\bC_\bK_\b__\bS_\bT_\bA_\bT_\bE, _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bn_\bu_\bm_\b__\bb_\bu_\bt_\bt_\bo_\bn_\bs,\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bn_\bu_\bm_\b__\ba_\bx_\be_\bs\n+Examples:\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_j\bjo\boy\bys\bst\bti\bic\bck\bk_\b_e\bev\bve\ben\bnt\bt_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_EVENT_SOURCE *al_get_joystick_event_source(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the global joystick event source. All _\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b _\be_\bv_\be_\bn_\bt_\bs are generated by\n this event source.\n+Examples:\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n+ * _\be_\bx_\b__\bh_\ba_\bp_\bt_\bi_\bc_\b2_\b._\bc_\bp_\bp\n Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/keyboard.html", "source2": "./usr/share/doc/allegro5-doc/refman/keyboard.html", "unified_diff": "@@ -212,14 +212,23 @@\n
        \n
      • display - points to the display that had keyboard focus at the time\n the state was saved. If no display was focused, this points to\n NULL.
        • \n
      \n

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

      \n+

      Examples:

      \n+
        \n+
      • ex_d3d.cpp
        • \n+
      • ex_keyboard_focus.c
        • \n+
      • ex_mouse_focus.c
        • \n+
      \n

      Key codes

      \n

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

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

      \n

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

      \n

      See also: al_uninstall_keyboard, al_is_keyboard_installed

      \n+

      Examples:

      \n+
        \n+
      • ex_d3d.cpp
        • \n+
      • ex_keyboard_focus.c
        • \n+
      • ex_mouse_focus.c
        • \n+
      \n

      al_is_keyboard_installed

      \n 
      bool al_is_keyboard_installed(void)
      \n

      Source\n Code

      \n

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

      \n

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

      \n

      See also: al_key_down, al_clear_keyboard_state,\n ALLEGRO_KEYBOARD_STATE

      \n+

      Examples:

      \n+
        \n+
      • ex_d3d.cpp
        • \n+
      • ex_keyboard_focus.c
        • \n+
      • ex_mouse_focus.c
        • \n+
      \n

      al_clear_keyboard_state

      \n 
      void al_clear_keyboard_state(ALLEGRO_DISPLAY *display)
      \n

      Source\n Code

      \n

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

      \n

      Since: 5.2.3

      \n
      \n

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

      \n
      \n+

      Examples:

      \n+
        \n+
      • ex_keyboard_events.c
        • \n+
      \n

      al_key_down

      \n 
      bool al_key_down(const ALLEGRO_KEYBOARD_STATE *state, int keycode)
      \n

      Source\n Code

      \n

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

      \n

      See also: ALLEGRO_KEYBOARD_STATE

      \n+

      Examples:

      \n+
        \n+
      • ex_d3d.cpp
        • \n+
      • ex_keyboard_focus.c
        • \n+
      • ex_mouse_focus.c
        • \n+
      \n

      al_keycode_to_name

      \n 
      const char *al_keycode_to_name(int keycode)
      \n

      Source\n Code

      \n

      Converts the given keycode to a description of the key.

      \n+

      Examples:

      \n+
        \n+
      • ex_keyboard_events.c
        • \n+
      \n

      al_can_set_keyboard_leds

      \n 
      bool al_can_set_keyboard_leds(void)
      \n

      Source\n Code

      \n

      Returns true if setting the keyboard LED indicators is available.

      \n

      Since: 5.2.9

      \n@@ -444,14 +490,23 @@\n

      Source\n Code

      \n

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

      \n

      Returns NULL if the keyboard subsystem was not installed.

      \n+

      Examples:

      \n+
        \n+
      • ex_keyboard_events.c
        • \n+
      • ex_opengl.c
        • \n+
      • ex_winfull.c
        • \n+
      \n

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

      \n \n \n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -62,14 +62,18 @@\n typedef struct ALLEGRO_KEYBOARD_STATE ALLEGRO_KEYBOARD_STATE;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This is a structure that is used to hold a \u201csnapshot\u201d of a keyboard\u2019s state at\n a particular instant. It contains the following publically readable fields:\n * display - points to the display that had keyboard focus at the time the\n state was saved. If no display was focused, this points to NULL.\n You cannot read the state of keys directly. Use the function _\ba_\bl_\b__\bk_\be_\by_\b__\bd_\bo_\bw_\bn.\n+Examples:\n+ * _\be_\bx_\b__\bd_\b3_\bd_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* K\bKe\bey\by c\bco\bod\bde\bes\bs *\b**\b**\b**\b**\b**\b*\n The constant ALLEGRO_KEY_MAX is always one higher than the highest key code. So\n if you want to use the key code as array index you can do something like this:\n bool pressed_keys[ALLEGRO_KEY_MAX];\n //...\n pressed_keys[key_code] = true;\n These are the list of key codes used by Allegro, which are returned in the\n@@ -185,14 +189,18 @@\n typed.\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bns\bst\bta\bal\bll\bl_\b_k\bke\bey\byb\bbo\boa\bar\brd\bd *\b**\b**\b**\b**\b**\b*\n bool al_install_keyboard(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Install a keyboard driver. Returns true if successful. If a driver was already\n installed, nothing happens and true is returned.\n See also: _\ba_\bl_\b__\bu_\bn_\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd, _\ba_\bl_\b__\bi_\bs_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\be_\bd\n+Examples:\n+ * _\be_\bx_\b__\bd_\b3_\bd_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_k\bke\bey\byb\bbo\boa\bar\brd\bd_\b_i\bin\bns\bst\bta\bal\bll\ble\bed\bd *\b**\b**\b**\b**\b**\b*\n bool al_is_keyboard_installed(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd was called successfully.\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bni\bin\bns\bst\bta\bal\bll\bl_\b_k\bke\bey\byb\bbo\boa\bar\brd\bd *\b**\b**\b**\b**\b**\b*\n void al_uninstall_keyboard(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n@@ -202,14 +210,18 @@\n See also: _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_k\bke\bey\byb\bbo\boa\bar\brd\bd_\b_s\bst\bta\bat\bte\be *\b**\b**\b**\b**\b**\b*\n void al_get_keyboard_state(ALLEGRO_KEYBOARD_STATE *ret_state)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Save the state of the keyboard specified at the time the function is called\n into the structure pointed to by r\bre\bet\bt_\b_s\bst\bta\bat\bte\be.\n See also: _\ba_\bl_\b__\bk_\be_\by_\b__\bd_\bo_\bw_\bn, _\ba_\bl_\b__\bc_\bl_\be_\ba_\br_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\bs_\bt_\ba_\bt_\be, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bK_\bE_\bY_\bB_\bO_\bA_\bR_\bD_\b__\bS_\bT_\bA_\bT_\bE\n+Examples:\n+ * _\be_\bx_\b__\bd_\b3_\bd_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcl\ble\bea\bar\br_\b_k\bke\bey\byb\bbo\boa\bar\brd\bd_\b_s\bst\bta\bat\bte\be *\b**\b**\b**\b**\b**\b*\n void al_clear_keyboard_state(ALLEGRO_DISPLAY *display)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Clear the state of the keyboard, emitting _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bK_\bE_\bY_\b__\bU_\bP for each\n currently pressed key. The given display is regarded as the one which had the\n keyboard focus when the event occurred. In case display is NULL no event is\n emitted. For most keyboard drivers Allegro maintains its own state of the\n@@ -217,23 +229,31 @@\n intended to remedy such situation by resetting Allegro\u2019s keyboard state to a\n known default (no key pressed). This is particularly useful in response to\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bD_\bI_\bS_\bP_\bL_\bA_\bY_\b__\bS_\bW_\bI_\bT_\bC_\bH_\b__\bO_\bU_\bT events.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\bs_\bt_\ba_\bt_\be, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bK_\bE_\bY_\bB_\bO_\bA_\bR_\bD_\b__\bS_\bT_\bA_\bT_\bE\n Since: 5.2.3\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: This is a new feature and the exact semantics are still\n being decided upon.\n+Examples:\n+ * _\be_\bx_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_k\bke\bey\by_\b_d\bdo\bow\bwn\bn *\b**\b**\b**\b**\b**\b*\n bool al_key_down(const ALLEGRO_KEYBOARD_STATE *state, int keycode)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return true if the key specified was held down in the state specified.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bK_\bE_\bY_\bB_\bO_\bA_\bR_\bD_\b__\bS_\bT_\bA_\bT_\bE\n+Examples:\n+ * _\be_\bx_\b__\bd_\b3_\bd_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_k\bke\bey\byc\bco\bod\bde\be_\b_t\bto\bo_\b_n\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n const char *al_keycode_to_name(int keycode)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Converts the given keycode to a description of the key.\n+Examples:\n+ * _\be_\bx_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bca\ban\bn_\b_s\bse\bet\bt_\b_k\bke\bey\byb\bbo\boa\bar\brd\bd_\b_l\ble\bed\bds\bs *\b**\b**\b**\b**\b**\b*\n bool al_can_set_keyboard_leds(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if setting the keyboard LED indicators is available.\n Since: 5.2.9\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\bl_\be_\bd_\bs\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_k\bke\bey\byb\bbo\boa\bar\brd\bd_\b_l\ble\bed\bds\bs *\b**\b**\b**\b**\b**\b*\n@@ -247,8 +267,12 @@\n See also: _\ba_\bl_\b__\bc_\ba_\bn_\b__\bs_\be_\bt_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\bl_\be_\bd_\bs\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_k\bke\bey\byb\bbo\boa\bar\brd\bd_\b_e\bev\bve\ben\bnt\bt_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_EVENT_SOURCE *al_get_keyboard_event_source(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Retrieve the keyboard event source. All _\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b _\be_\bv_\be_\bn_\bt_\bs are generated by this\n event source.\n Returns NULL if the keyboard subsystem was not installed.\n+Examples:\n+ * _\be_\bx_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n+ * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b._\bc\n+ * _\be_\bx_\b__\bw_\bi_\bn_\bf_\bu_\bl_\bl_\b._\bc\n Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/memfile.html", "source2": "./usr/share/doc/allegro5-doc/refman/memfile.html", "unified_diff": "@@ -196,14 +196,19 @@\n Regardless of the mode, the file always opens at position 0. The file\n size is fixed and cannot be expanded. The file is always read\n from/written to in binary mode, which means that no newline translation\n is performed.

      \n

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

      \n+

      Examples:

      \n+
        \n+
      • ex_memfile.c
        • \n+
      \n al_get_allegro_memfile_version\n 
      uint32_t al_get_allegro_memfile_version(void)
      \n

      Source\n Code

      \n

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

      This is a macro.

      \n

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

      \n+

      Examples:

      \n+
        \n+
      • ex_audio_timer.c
        • \n+
      • ex_vertex_buffer.c
        • \n+
      \n

      al_free

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

      Source\n Code

      \n

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

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

      \n

      This is a macro.

      \n

      See also: al_malloc, al_free_with_context

      \n+

      Examples:

      \n+
        \n+
      • ex_clipboard.c
        • \n+
      • ex_drag_and_drop.c
        • \n+
      • ex_record_name.c
        • \n+
      \n

      al_realloc

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

      Source\n Code

      \n

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

      \n

      This is a macro.

      \n

      See also: al_malloc, al_realloc_with_context

      \n

      al_calloc

      \n-

      Source Code

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

      Source\n+Code

      \n

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

      \n

      This is a macro.

      \n

      See also: al_malloc, al_calloc_with_context

      \n+

      Examples:

      \n+
        \n+
      • ex_record_name.c
        • \n+
      \n

      al_malloc_with_context

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

      Source\n Code

      \n

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

      \n

      Generally you should use the al_malloc macro.

      \n

      al_free_with_context

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

      Source\n Code

      \n

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

      \n

      Generally you should use the al_free macro.

      \n

      al_realloc_with_context

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

      Source\n Code

      \n

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

      \n

      Generally you should use the al_realloc macro.

      \n

      al_calloc_with_context

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

      Source\n Code

      \n

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

      \n

      Generally you should use the al_calloc macro.

      \n

      ALLEGRO_MEMORY_INTERFACE

      \n-
      typedef struct ALLEGRO_MEMORY_INTERFACE ALLEGRO_MEMORY_INTERFACE;
      \n+
      typedef struct ALLEGRO_MEMORY_INTERFACE ALLEGRO_MEMORY_INTERFACE;
      \n

      Source\n Code

      \n

      This structure has the following fields.

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

      See also: al_set_memory_interface

      \n

      al_set_memory_interface

      \n-
      void al_set_memory_interface(ALLEGRO_MEMORY_INTERFACE *memory_interface)
      \n+
      void al_set_memory_interface(ALLEGRO_MEMORY_INTERFACE *memory_interface)
      \n

      Source\n Code

      \n

      Override the memory management functions with implementations of al_malloc_with_context, al_free_with_context, al_realloc_with_context\n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -60,38 +60,50 @@\n (al_malloc_with_context((n), __LINE__, __FILE__, __func__))\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like malloc() in the C standard library, but the implementation may be\n overridden.\n This is a macro.\n See also: _\ba_\bl_\b__\bf_\br_\be_\be, _\ba_\bl_\b__\br_\be_\ba_\bl_\bl_\bo_\bc, _\ba_\bl_\b__\bc_\ba_\bl_\bl_\bo_\bc, _\ba_\bl_\b__\bm_\ba_\bl_\bl_\bo_\bc_\b__\bw_\bi_\bt_\bh_\b__\bc_\bo_\bn_\bt_\be_\bx_\bt,\n _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\be_\bm_\bo_\br_\by_\b__\bi_\bn_\bt_\be_\br_\bf_\ba_\bc_\be\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bt_\bi_\bm_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_f\bfr\bre\bee\be *\b**\b**\b**\b**\b**\b*\n #define al_free(p) \\\n (al_free_with_context((p), __LINE__, __FILE__, __func__))\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like free() in the C standard library, but the implementation may be\n overridden.\n Additionally, on Windows, a memory block allocated by one DLL must be freed\n from the same DLL. In the few places where an Allegro function returns a\n pointer that must be freed, you must use _\ba_\bl_\b__\bf_\br_\be_\be for portability to Windows.\n This is a macro.\n See also: _\ba_\bl_\b__\bm_\ba_\bl_\bl_\bo_\bc, _\ba_\bl_\b__\bf_\br_\be_\be_\b__\bw_\bi_\bt_\bh_\b__\bc_\bo_\bn_\bt_\be_\bx_\bt\n+Examples:\n+ * _\be_\bx_\b__\bc_\bl_\bi_\bp_\bb_\bo_\ba_\br_\bd_\b._\bc\n+ * _\be_\bx_\b__\bd_\br_\ba_\bg_\b__\ba_\bn_\bd_\b__\bd_\br_\bo_\bp_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bn_\ba_\bm_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bea\bal\bll\blo\boc\bc *\b**\b**\b**\b**\b**\b*\n #define al_realloc(p, n) \\\n+ (al_realloc_with_context((p), (n), __LINE__, __FILE__, __func__))\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like realloc() in the C standard library, but the implementation may be\n overridden.\n This is a macro.\n See also: _\ba_\bl_\b__\bm_\ba_\bl_\bl_\bo_\bc, _\ba_\bl_\b__\br_\be_\ba_\bl_\bl_\bo_\bc_\b__\bw_\bi_\bt_\bh_\b__\bc_\bo_\bn_\bt_\be_\bx_\bt\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bca\bal\bll\blo\boc\bc *\b**\b**\b**\b**\b**\b*\n-Source Code\n+#define al_calloc(c, n) \\\n+ (al_calloc_with_context((c), (n), __LINE__, __FILE__, __func__))\n+_\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like calloc() in the C standard library, but the implementation may be\n overridden.\n This is a macro.\n See also: _\ba_\bl_\b__\bm_\ba_\bl_\bl_\bo_\bc, _\ba_\bl_\b__\bc_\ba_\bl_\bl_\bo_\bc_\b__\bw_\bi_\bt_\bh_\b__\bc_\bo_\bn_\bt_\be_\bx_\bt\n+Examples:\n+ * _\be_\bx_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bn_\ba_\bm_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_m\bma\bal\bll\blo\boc\bc_\b_w\bwi\bit\bth\bh_\b_c\bco\bon\bnt\bte\bex\bxt\bt *\b**\b**\b**\b**\b**\b*\n void *al_malloc_with_context(size_t n,\n int line, const char *file, const char *func)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This calls malloc() from the Allegro library (this matters on Windows), unless\n overridden with _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\be_\bm_\bo_\br_\by_\b__\bi_\bn_\bt_\be_\br_\bf_\ba_\bc_\be,\n Generally you should use the _\ba_\bl_\b__\bm_\ba_\bl_\bl_\bo_\bc macro.\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/misc.html", "source2": "./usr/share/doc/allegro5-doc/refman/misc.html", "unified_diff": "@@ -182,14 +182,23 @@\n

      ALLEGRO_PI

      \n 
      #define ALLEGRO_PI        3.14159265358979323846
      \n

      Source\n Code

      \n

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

      \n+

      Examples:

      \n+
        \n+
      • ex_convert.c
        • \n+
      • ex_opengl.c
        • \n+
      • ex_blend_bench.c
        • \n+
      \n

      al_run_main

      \n 
      int al_run_main(int argc, char **argv, int (*user_main)(int, char **))
      \n

      Source\n Code

      \n

      This function is useful in cases where you don\u2019t have a main()\n function but want to run Allegro (mostly useful in a wrapper library).\n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -48,14 +48,18 @@\n These functions are declared in the main Allegro header file:\n #include \n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_P\bPI\bI *\b**\b**\b**\b**\b**\b*\n #define ALLEGRO_PI 3.14159265358979323846\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n C99 compilers have no predefined value like M_PI for the constant \u03c0, but you\n can use this one instead.\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bn_\bv_\be_\br_\bt_\b._\bc\n+ * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b._\bc\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bb_\be_\bn_\bc_\bh_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bru\bun\bn_\b_m\bma\bai\bin\bn *\b**\b**\b**\b**\b**\b*\n int al_run_main(int argc, char **argv, int (*user_main)(int, char **))\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This function is useful in cases where you don\u2019t have a main() function but\n want to run Allegro (mostly useful in a wrapper library). Under Windows and\n Linux this is no problem because you simply can call _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bs_\by_\bs_\bt_\be_\bm. But\n some other system (like OSX) don\u2019t allow calling _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bs_\by_\bs_\bt_\be_\bm in the main\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/monitor.html", "source2": "./usr/share/doc/allegro5-doc/refman/monitor.html", "unified_diff": "@@ -184,72 +184,107 @@\n

    • al_get_monitor_refresh_rate
      • \n
    \n \n

    These functions are declared in the main Allegro header file:

    \n 
     #include <allegro5/allegro.h>
    \n

    ALLEGRO_MONITOR_INFO

    \n-

    Source Code

    \n+
    typedef struct ALLEGRO_MONITOR_INFO
    \n+

    Source\n+Code

    \n

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

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

    See also: al_get_monitor_info

    \n+

    Examples:

    \n+
      \n+
    • ex_monitorinfo.c
      • \n+
    • ex_drag_and_drop.c
      • \n+
    • ex_windows.c
      • \n+
    \n

    al_get_monitor_info

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

    Source\n Code

    \n

    Get information about a monitor\u2019s position on the desktop. adapter is\n a number from 0 to al_get_num_video_adapters()-1.

    \n

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

    \n

    Returns true on success, false on\n failure.

    \n

    See also: ALLEGRO_MONITOR_INFO, al_get_num_video_adapters

    \n+

    Examples:

    \n+
      \n+
    • ex_monitorinfo.c
      • \n+
    • ex_drag_and_drop.c
      • \n+
    • ex_windows.c
      • \n+
    \n

    al_get_monitor_dpi

    \n-
    int al_get_monitor_dpi(int adapter)
    \n+
    int al_get_monitor_dpi(int adapter)
    \n

    Source\n Code

    \n

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

    \n

    Since: 5.2.5

    \n

    See also: al_get_num_video_adapters

    \n+

    Examples:

    \n+
      \n+
    • ex_monitorinfo.c
      • \n+
    \n

    al_get_num_video_adapters

    \n-
    int al_get_num_video_adapters(void)
    \n+
    int al_get_num_video_adapters(void)
    \n

    Source\n Code

    \n

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

    \n

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

    \n

    See also: al_get_monitor_info

    \n+

    Examples:

    \n+
      \n+
    • ex_monitorinfo.c
      • \n+
    • ex_winfull.c
      • \n+
    • ex_dualies.c
      • \n+
    \n

    al_get_monitor_refresh_rate

    \n-
    int al_get_monitor_refresh_rate(int adapter)
    \n+
    int al_get_monitor_refresh_rate(int adapter)
    \n

    Source\n Code

    \n

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

    \n

    Since: 5.2.6

    \n
    \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -47,52 +47,67 @@\n * _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bn_\bi_\bt_\bo_\br_\b__\bi_\bn_\bf_\bo\n * _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bn_\bi_\bt_\bo_\br_\b__\bd_\bp_\bi\n * _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\bu_\bm_\b__\bv_\bi_\bd_\be_\bo_\b__\ba_\bd_\ba_\bp_\bt_\be_\br_\bs\n * _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bn_\bi_\bt_\bo_\br_\b__\br_\be_\bf_\br_\be_\bs_\bh_\b__\br_\ba_\bt_\be\n These functions are declared in the main Allegro header file:\n #include \n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_M\bMO\bON\bNI\bIT\bTO\bOR\bR_\b_I\bIN\bNF\bFO\bO *\b**\b**\b**\b**\b**\b*\n-Source Code\n+typedef struct ALLEGRO_MONITOR_INFO\n+_\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Describes a monitor\u2019s size and position relative to other monitors. x1, y1 will\n be 0, 0 on the primary display. Other monitors can have negative values if they\n are to the left or above the primary display. x2, y2 are the coordinates one\n beyond the bottom right pixel, so that x2-x1 gives the width and y2-y1 gives\n the height of the display.\n typedef struct ALLEGRO_MONITOR_INFO\n {\n int x1;\n int y1;\n int x2;\n int y2;\n } ALLEGRO_MONITOR_INFO;\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bn_\bi_\bt_\bo_\br_\b__\bi_\bn_\bf_\bo\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bn_\bi_\bt_\bo_\br_\bi_\bn_\bf_\bo_\b._\bc\n+ * _\be_\bx_\b__\bd_\br_\ba_\bg_\b__\ba_\bn_\bd_\b__\bd_\br_\bo_\bp_\b._\bc\n+ * _\be_\bx_\b__\bw_\bi_\bn_\bd_\bo_\bw_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmo\bon\bni\bit\bto\bor\br_\b_i\bin\bnf\bfo\bo *\b**\b**\b**\b**\b**\b*\n bool al_get_monitor_info(int adapter, ALLEGRO_MONITOR_INFO *info)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get information about a monitor\u2019s position on the desktop. adapter is a number\n from 0 to al_get_num_video_adapters()-1.\n On Windows, use _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bd_\bi_\bs_\bp_\bl_\ba_\by_\b__\bf_\bl_\ba_\bg_\bs to switch between Direct3D and OpenGL\n backends, which will often have different adapters available.\n Returns true on success, false on failure.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bM_\bO_\bN_\bI_\bT_\bO_\bR_\b__\bI_\bN_\bF_\bO, _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\bu_\bm_\b__\bv_\bi_\bd_\be_\bo_\b__\ba_\bd_\ba_\bp_\bt_\be_\br_\bs\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bn_\bi_\bt_\bo_\br_\bi_\bn_\bf_\bo_\b._\bc\n+ * _\be_\bx_\b__\bd_\br_\ba_\bg_\b__\ba_\bn_\bd_\b__\bd_\br_\bo_\bp_\b._\bc\n+ * _\be_\bx_\b__\bw_\bi_\bn_\bd_\bo_\bw_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmo\bon\bni\bit\bto\bor\br_\b_d\bdp\bpi\bi *\b**\b**\b**\b**\b**\b*\n int al_get_monitor_dpi(int adapter)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get the dots per inch of a monitor attached to the display adapter.\n Since: 5.2.5\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\bu_\bm_\b__\bv_\bi_\bd_\be_\bo_\b__\ba_\bd_\ba_\bp_\bt_\be_\br_\bs\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bn_\bi_\bt_\bo_\br_\bi_\bn_\bf_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_n\bnu\bum\bm_\b_v\bvi\bid\bde\beo\bo_\b_a\bad\bda\bap\bpt\bte\ber\brs\bs *\b**\b**\b**\b**\b**\b*\n int al_get_num_video_adapters(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get the number of video \u201cadapters\u201d attached to the computer. Each video card\n attached to the computer counts as one or more adapters. An adapter is thus\n really a video port that can have a monitor connected to it.\n On Windows, use _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bd_\bi_\bs_\bp_\bl_\ba_\by_\b__\bf_\bl_\ba_\bg_\bs to switch between Direct3D and OpenGL\n backends, which will often have different adapters available.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bn_\bi_\bt_\bo_\br_\b__\bi_\bn_\bf_\bo\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bn_\bi_\bt_\bo_\br_\bi_\bn_\bf_\bo_\b._\bc\n+ * _\be_\bx_\b__\bw_\bi_\bn_\bf_\bu_\bl_\bl_\b._\bc\n+ * _\be_\bx_\b__\bd_\bu_\ba_\bl_\bi_\be_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmo\bon\bni\bit\bto\bor\br_\b_r\bre\bef\bfr\bre\bes\bsh\bh_\b_r\bra\bat\bte\be *\b**\b**\b**\b**\b**\b*\n int al_get_monitor_refresh_rate(int adapter)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the current refresh rate of a monitor attached to the display adapter.\n Since: 5.2.6\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: This is an experimental feature and currently only\n works on Windows.\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/mouse.html", "source2": "./usr/share/doc/allegro5-doc/refman/mouse.html", "unified_diff": "@@ -231,15 +231,18 @@\n id=\"toc-al_ungrab_mouse\">al_ungrab_mouse\n \n \n \n

    These functions are declared in the main Allegro header file:

    \n 
     #include <allegro5/allegro.h>
    \n

    ALLEGRO_MOUSE_STATE

    \n-

    Source Code

    \n+
    typedef struct ALLEGRO_MOUSE_STATE ALLEGRO_MOUSE_STATE;
    \n+

    Source\n+Code

    \n

    Public fields (read only):

    \n
      \n

    • x - mouse x position

      • \n

    • y - mouse y position

      • \n

    • w, z - mouse wheel position (2D \u2018ball\u2019)

      • \n

    • buttons - mouse buttons bitfield

      \n

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

    • pressure - pressure, ranging from 0.0 to\n 1.0

      • \n
    \n

    See also: al_get_mouse_state, al_get_mouse_state_axis,\n al_mouse_button_down

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse_focus.c
      • \n+
    • ex_mouse.c
      • \n+
    • nihgui.cpp
      • \n+
    \n

    Mouse button constants

    \n

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

    \n

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

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

    Since: 5.2.10

    \n

    See also: al_get_mouse_num_buttons,\n al_mouse_button_down

    \n

    al_install_mouse

    \n-
    bool al_install_mouse(void)
    \n+
    bool al_install_mouse(void)
    \n

    Source\n Code

    \n

    Install a mouse driver.

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse_focus.c
      • \n+
    • ex_mouse.c
      • \n+
    • ex_font_justify.cpp
      • \n+
    \n

    al_is_mouse_installed

    \n-
    bool al_is_mouse_installed(void)
    \n+
    bool al_is_mouse_installed(void)
    \n

    Source\n Code

    \n

    Returns true if al_install_mouse was called\n successfully.

    \n

    al_uninstall_mouse

    \n-
    void al_uninstall_mouse(void)
    \n+
    void al_uninstall_mouse(void)
    \n

    Source\n Code

    \n

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

    \n

    This function is automatically called when Allegro is shut down.

    \n

    al_get_mouse_num_axes

    \n-
    unsigned int al_get_mouse_num_axes(void)
    \n+
    unsigned int al_get_mouse_num_axes(void)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_get_mouse_num_buttons

    \n

    al_get_mouse_num_buttons

    \n-
    unsigned int al_get_mouse_num_buttons(void)
    \n+
    unsigned int al_get_mouse_num_buttons(void)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_get_mouse_num_axes

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse_events.c
      • \n+
    \n

    al_get_mouse_state

    \n-
    void al_get_mouse_state(ALLEGRO_MOUSE_STATE *ret_state)
    \n+
    void al_get_mouse_state(ALLEGRO_MOUSE_STATE *ret_state)
    \n

    Source\n Code

    \n

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

    \n

    Example:

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

    See also: ALLEGRO_MOUSE_STATE, al_get_mouse_state_axis,\n al_mouse_button_down

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse_focus.c
      • \n+
    • ex_mouse.c
      • \n+
    • nihgui.cpp
      • \n+
    \n

    al_get_mouse_state_axis

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

    Source\n Code

    \n

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

    \n

    See also: ALLEGRO_MOUSE_STATE, al_get_mouse_state, al_mouse_button_down

    \n

    al_mouse_button_down

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

    Source\n Code

    \n

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

    \n

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

    \n

    See also: ALLEGRO_MOUSE_STATE, al_get_mouse_state, al_get_mouse_state_axis

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse.c
      • \n+
    \n

    al_set_mouse_xy

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

    Source\n Code

    \n

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

    \n

    Returns true on success, false on failure.

    \n

    See also: al_set_mouse_z, al_set_mouse_w

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse_warp.c
      • \n+
    • ex_ogre3d.cpp
      • \n+
    \n

    al_set_mouse_z

    \n-
    bool al_set_mouse_z(int z)
    \n+
    bool al_set_mouse_z(int z)
    \n

    Source\n Code

    \n

    Set the mouse wheel position to the given value.

    \n

    Returns true on success, false on failure.

    \n

    See also: al_set_mouse_w

    \n

    al_set_mouse_w

    \n-
    bool al_set_mouse_w(int w)
    \n+
    bool al_set_mouse_w(int w)
    \n

    Source\n Code

    \n

    Set the second mouse wheel position to the given value.

    \n

    Returns true on success, false on failure.

    \n

    See also: al_set_mouse_z

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse_events.c
      • \n+
    \n

    al_set_mouse_axis

    \n-
    bool al_set_mouse_axis(int which, int value)
    \n+
    bool al_set_mouse_axis(int which, int value)
    \n

    Source\n Code

    \n

    Set the given mouse axis to the given value.

    \n

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

    \n

    Returns true on success, false on failure.

    \n

    See also: al_set_mouse_xy,\n al_set_mouse_z, al_set_mouse_w

    \n

    al_get_mouse_event_source

    \n-
    ALLEGRO_EVENT_SOURCE *al_get_mouse_event_source(void)
    \n+
    ALLEGRO_EVENT_SOURCE *al_get_mouse_event_source(void)
    \n

    Source\n Code

    \n

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

    \n

    Returns NULL if the mouse subsystem was not installed.

    \n+

    Examples:

    \n+
      \n+
    • ex_display_events.c
      • \n+
    • ex_mouse_warp.c
      • \n+
    • ex_noframe.c
      • \n+
    \n

    al_set_mouse_wheel_precision

    \n-
    void al_set_mouse_wheel_precision(int precision)
    \n+
    void al_set_mouse_wheel_precision(int precision)
    \n

    Source\n Code

    \n

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

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

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

    \n

    Since: 5.1.10

    \n

    See also: al_get_mouse_wheel_precision

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse_events.c
      • \n+
    \n

    al_get_mouse_wheel_precision

    \n-
    int al_get_mouse_wheel_precision(void)
    \n+
    int al_get_mouse_wheel_precision(void)
    \n

    Source\n Code

    \n

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

    \n

    Since: 5.1.10

    \n

    See also: al_set_mouse_wheel_precision

    \n

    Mouse cursors

    \n

    al_create_mouse_cursor

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

    Source\n Code

    \n

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

    \n

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

    \n

    See also: al_set_mouse_cursor, al_destroy_mouse_cursor

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse_cursor.c
      • \n+
    \n

    al_destroy_mouse_cursor

    \n-
    void al_destroy_mouse_cursor(ALLEGRO_MOUSE_CURSOR *cursor)
    \n+
    void al_destroy_mouse_cursor(ALLEGRO_MOUSE_CURSOR *cursor)
    \n

    Source\n Code

    \n

    Free the memory used by the given cursor.

    \n

    Has no effect if cursor is NULL.

    \n

    See also: al_create_mouse_cursor

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse_cursor.c
      • \n+
    \n

    al_set_mouse_cursor

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

    Source\n Code

    \n

    Set the given mouse cursor to be the current mouse cursor for the\n given display.

    \n

    If the cursor is currently \u2018shown\u2019 (as opposed to \u2018hidden\u2019) the\n change is immediately visible.

    \n

    Returns true on success, false on failure.

    \n

    See also: al_set_system_mouse_cursor,\n al_show_mouse_cursor, al_hide_mouse_cursor

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse_cursor.c
      • \n+
    \n

    al_set_system_mouse_cursor

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

    Source\n Code

    \n

    Set the given system mouse cursor to be the current mouse cursor for\n the given display. If the cursor is currently \u2018shown\u2019 (as opposed to\n \u2018hidden\u2019) the change is immediately visible.

    \n

    If the cursor doesn\u2019t exist on the current platform another cursor\n@@ -525,61 +606,87 @@\n

  • ALLEGRO_SYSTEM_MOUSE_CURSOR_UNAVAILABLE
    • \n \n

    Returns true on success, false on failure.

    \n

    See also: al_set_mouse_cursor, al_show_mouse_cursor, al_hide_mouse_cursor

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse_cursor.c
      • \n+
    \n al_can_get_mouse_cursor_position\n-
    bool al_can_get_mouse_cursor_position(void)
    \n+
    bool al_can_get_mouse_cursor_position(void)
    \n

    Source\n Code

    \n

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

    \n

    Since: 5.2.9

    \n

    See also: al_get_mouse_cursor_position

    \n

    al_get_mouse_cursor_position

    \n-
    bool al_get_mouse_cursor_position(int *ret_x, int *ret_y)
    \n+
    bool al_get_mouse_cursor_position(int *ret_x, int *ret_y)
    \n

    Source\n Code

    \n

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

    \n

    Returns true on success, false on failure.

    \n

    See also: al_can_get_mouse_cursor_position

    \n+

    Examples:

    \n+
      \n+
    • ex_noframe.c
      • \n+
    \n

    al_hide_mouse_cursor

    \n-
    bool al_hide_mouse_cursor(ALLEGRO_DISPLAY *display)
    \n+
    bool al_hide_mouse_cursor(ALLEGRO_DISPLAY *display)
    \n

    Source\n Code

    \n

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

    \n

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

    \n

    See also: al_show_mouse_cursor

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse.c
      • \n+
    • ex_ogre3d.cpp
      • \n+
    • ex_mouse_events.c
      • \n+
    \n

    al_show_mouse_cursor

    \n-
    bool al_show_mouse_cursor(ALLEGRO_DISPLAY *display)
    \n+
    bool al_show_mouse_cursor(ALLEGRO_DISPLAY *display)
    \n

    Source\n Code

    \n

    Make a mouse cursor visible in the given display.

    \n

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

    \n

    See also: al_hide_mouse_cursor

    \n+

    Examples:

    \n+
      \n+
    • ex_ogre3d.cpp
      • \n+
    • ex_mouse_cursor.c
      • \n+
    \n

    al_grab_mouse

    \n-
    bool al_grab_mouse(ALLEGRO_DISPLAY *display)
    \n+
    bool al_grab_mouse(ALLEGRO_DISPLAY *display)
    \n

    Source\n Code

    \n

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

    \n

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

    \n

    Note: not yet implemented on Mac OS X.

    \n
    \n

    See also: al_ungrab_mouse

    \n

    al_ungrab_mouse

    \n-
    bool al_ungrab_mouse(void)
    \n+
    bool al_ungrab_mouse(void)
    \n

    Source\n Code

    \n

    Stop confining the mouse cursor to any display belonging to the\n program.

    \n
    \n

    Note: not yet implemented on Mac OS X.

    \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -70,24 +70,29 @@\n o _\ba_\bl_\b__\bh_\bi_\bd_\be_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br\n o _\ba_\bl_\b__\bs_\bh_\bo_\bw_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br\n o _\ba_\bl_\b__\bg_\br_\ba_\bb_\b__\bm_\bo_\bu_\bs_\be\n o _\ba_\bl_\b__\bu_\bn_\bg_\br_\ba_\bb_\b__\bm_\bo_\bu_\bs_\be\n These functions are declared in the main Allegro header file:\n #include \n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_M\bMO\bOU\bUS\bSE\bE_\b_S\bST\bTA\bAT\bTE\bE *\b**\b**\b**\b**\b**\b*\n-Source Code\n+typedef struct ALLEGRO_MOUSE_STATE ALLEGRO_MOUSE_STATE;\n+_\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Public fields (read only):\n * x - mouse x position\n * y - mouse y position\n * w, z - mouse wheel position (2D \u2018ball\u2019)\n * buttons - mouse buttons bitfield\n The zeroth bit is set if the primary mouse button is held down, the first\n bit is set if the secondary mouse button is held down, and so on.\n * pressure - pressure, ranging from 0.0 to 1.0\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bs_\bt_\ba_\bt_\be, _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bs_\bt_\ba_\bt_\be_\b__\ba_\bx_\bi_\bs, _\ba_\bl_\b__\bm_\bo_\bu_\bs_\be_\b__\bb_\bu_\bt_\bt_\bo_\bn_\b__\bd_\bo_\bw_\bn\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b._\bc\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* M\bMo\bou\bus\bse\be b\bbu\but\btt\bto\bon\bn c\bco\bon\bns\bst\bta\ban\bnt\bts\bs *\b**\b**\b**\b**\b**\b*\n Unlike other indexes, the first mouse button is numbered 1 when returned in the\n event.mouse.button field of ALLEGRO_EVENT_MOUSE_BUTTON_UP and\n ALLEGRO_EVENT_MOUSE_BUTTON_DOWN events.\n As a convenience, the following ALLEGRO_MOUSE_BUTTON constants are provided\n below. However, depending on the hardware there may be more or fewer mouse\n buttons. You can check _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bn_\bu_\bm_\b__\bb_\bu_\bt_\bt_\bo_\bn_\bs if you want to be sure.\n@@ -101,14 +106,18 @@\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bn_\bu_\bm_\b__\bb_\bu_\bt_\bt_\bo_\bn_\bs, _\ba_\bl_\b__\bm_\bo_\bu_\bs_\be_\b__\bb_\bu_\bt_\bt_\bo_\bn_\b__\bd_\bo_\bw_\bn\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bns\bst\bta\bal\bll\bl_\b_m\bmo\bou\bus\bse\be *\b**\b**\b**\b**\b**\b*\n bool al_install_mouse(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Install a mouse driver.\n Returns true if successful. If a driver was already installed, nothing happens\n and true is returned.\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b._\bc\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bj_\bu_\bs_\bt_\bi_\bf_\by_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_m\bmo\bou\bus\bse\be_\b_i\bin\bns\bst\bta\bal\bll\ble\bed\bd *\b**\b**\b**\b**\b**\b*\n bool al_is_mouse_installed(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bm_\bo_\bu_\bs_\be was called successfully.\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bni\bin\bns\bst\bta\bal\bll\bl_\b_m\bmo\bou\bus\bse\be *\b**\b**\b**\b**\b**\b*\n void al_uninstall_mouse(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n@@ -121,14 +130,16 @@\n Return the number of axes on the mouse. The first axis is 0.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bn_\bu_\bm_\b__\bb_\bu_\bt_\bt_\bo_\bn_\bs\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_n\bnu\bum\bm_\b_b\bbu\but\btt\bto\bon\bns\bs *\b**\b**\b**\b**\b**\b*\n unsigned int al_get_mouse_num_buttons(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the number of buttons on the mouse. The first button is 1.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bn_\bu_\bm_\b__\ba_\bx_\be_\bs\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_s\bst\bta\bat\bte\be *\b**\b**\b**\b**\b**\b*\n void al_get_mouse_state(ALLEGRO_MOUSE_STATE *ret_state)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Save the state of the mouse specified at the time the function is called into\n the given structure.\n Example:\n ALLEGRO_MOUSE_STATE state;\n@@ -141,14 +152,18 @@\n if (state.buttons & 2) {\n /* Secondary (e.g. right) mouse button is held. */\n }\n if (state.buttons & 4) {\n /* Tertiary (e.g. middle) mouse button is held. */\n }\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bM_\bO_\bU_\bS_\bE_\b__\bS_\bT_\bA_\bT_\bE, _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bs_\bt_\ba_\bt_\be_\b__\ba_\bx_\bi_\bs, _\ba_\bl_\b__\bm_\bo_\bu_\bs_\be_\b__\bb_\bu_\bt_\bt_\bo_\bn_\b__\bd_\bo_\bw_\bn\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b._\bc\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_s\bst\bta\bat\bte\be_\b_a\bax\bxi\bis\bs *\b**\b**\b**\b**\b**\b*\n int al_get_mouse_state_axis(const ALLEGRO_MOUSE_STATE *state, int axis)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Extract the mouse axis value from the saved state. The axes are numbered from\n 0, in this order: x-axis, y-axis, z-axis, w-axis.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bM_\bO_\bU_\bS_\bE_\b__\bS_\bT_\bA_\bT_\bE, _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bs_\bt_\ba_\bt_\be, _\ba_\bl_\b__\bm_\bo_\bu_\bs_\be_\b__\bb_\bu_\bt_\bt_\bo_\bn_\b__\bd_\bo_\bw_\bn\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_m\bmo\bou\bus\bse\be_\b_b\bbu\but\btt\bto\bon\bn_\b_d\bdo\bow\bwn\bn *\b**\b**\b**\b**\b**\b*\n@@ -157,48 +172,59 @@\n Return true if the mouse button specified was held down in the state specified.\n Unlike most things, the first mouse button is numbered 1. As a convenience, the\n constants ALLEGRO_MOUSE_BUTTON_LEFT, ALLEGRO_MOUSE_BUTTON_RIGHT,\n ALLEGRO_MOUSE_BUTTON_MIDDLE are provided. However, depending on the hardware\n there may be more or fewer mouse buttons. You can check\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bn_\bu_\bm_\b__\bb_\bu_\bt_\bt_\bo_\bn_\bs if you want to be sure.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bM_\bO_\bU_\bS_\bE_\b__\bS_\bT_\bA_\bT_\bE, _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bs_\bt_\ba_\bt_\be, _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bs_\bt_\ba_\bt_\be_\b__\ba_\bx_\bi_\bs\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_x\bxy\by *\b**\b**\b**\b**\b**\b*\n bool al_set_mouse_xy(ALLEGRO_DISPLAY *display, int x, int y)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Try to position the mouse at the given coordinates on the given display. The\n mouse movement resulting from a successful move will generate an\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bM_\bO_\bU_\bS_\bE_\b__\bW_\bA_\bR_\bP_\bE_\bD event.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bz, _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bw\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bw_\ba_\br_\bp_\b._\bc\n+ * _\be_\bx_\b__\bo_\bg_\br_\be_\b3_\bd_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_z\bz *\b**\b**\b**\b**\b**\b*\n bool al_set_mouse_z(int z)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the mouse wheel position to the given value.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bw\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_w\bw *\b**\b**\b**\b**\b**\b*\n bool al_set_mouse_w(int w)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the second mouse wheel position to the given value.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bz\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_a\bax\bxi\bis\bs *\b**\b**\b**\b**\b**\b*\n bool al_set_mouse_axis(int which, int value)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the given mouse axis to the given value.\n The axis number must not be 0 or 1, which are the X and Y axes. Use\n _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bx_\by for that.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bx_\by, _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bz, _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bw\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_e\bev\bve\ben\bnt\bt_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_EVENT_SOURCE *al_get_mouse_event_source(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Retrieve the mouse event source. All _\bm_\bo_\bu_\bs_\be_\b _\be_\bv_\be_\bn_\bt_\bs are generated by this event\n source.\n Returns NULL if the mouse subsystem was not installed.\n+Examples:\n+ * _\be_\bx_\b__\bd_\bi_\bs_\bp_\bl_\ba_\by_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bw_\ba_\br_\bp_\b._\bc\n+ * _\be_\bx_\b__\bn_\bo_\bf_\br_\ba_\bm_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_w\bwh\bhe\bee\bel\bl_\b_p\bpr\bre\bec\bci\bis\bsi\bio\bon\bn *\b**\b**\b**\b**\b**\b*\n void al_set_mouse_wheel_precision(int precision)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets the precision of the mouse wheel (the z and w coordinates). This precision\n manifests itself as a multiplier on the dz and dw fields in mouse events. It\n also affects the z and w fields of events and _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bM_\bO_\bU_\bS_\bE_\b__\bS_\bT_\bA_\bT_\bE, but not in a\n simple way if you alter the precision often, so it is suggested to reset those\n@@ -215,14 +241,16 @@\n double dz = (double)event.mouse.dz / al_get_mouse_wheel_precision();\n /* Use dz in some way... */\n }\n Precision is set to 1 by default. It is impossible to set it to a lower\n precision than that.\n Since: 5.1.10\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bw_\bh_\be_\be_\bl_\b__\bp_\br_\be_\bc_\bi_\bs_\bi_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_w\bwh\bhe\bee\bel\bl_\b_p\bpr\bre\bec\bci\bis\bsi\bio\bon\bn *\b**\b**\b**\b**\b**\b*\n int al_get_mouse_wheel_precision(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Gets the precision of the mouse wheel (the z and w coordinates).\n Since: 5.1.10\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bw_\bh_\be_\be_\bl_\b__\bp_\br_\be_\bc_\bi_\bs_\bi_\bo_\bn\n *\b**\b**\b**\b**\b**\b* M\bMo\bou\bus\bse\be c\bcu\bur\brs\bso\bor\brs\bs *\b**\b**\b**\b**\b**\b*\n@@ -230,31 +258,37 @@\n ALLEGRO_MOUSE_CURSOR *al_create_mouse_cursor(ALLEGRO_BITMAP *bmp,\n int x_focus, int y_focus)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a mouse cursor from the bitmap provided. x_focus and y_focus describe\n the bit of the cursor that will represent the actual mouse position.\n Returns a pointer to the cursor on success, or NULL on failure.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_m\bmo\bou\bus\bse\be_\b_c\bcu\bur\brs\bso\bor\br *\b**\b**\b**\b**\b*\n void al_destroy_mouse_cursor(ALLEGRO_MOUSE_CURSOR *cursor)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Free the memory used by the given cursor.\n Has no effect if cursor is NULL.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_c\bcu\bur\brs\bso\bor\br *\b**\b**\b**\b**\b*\n bool al_set_mouse_cursor(ALLEGRO_DISPLAY *display, ALLEGRO_MOUSE_CURSOR\n *cursor)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the given mouse cursor to be the current mouse cursor for the given\n display.\n If the cursor is currently \u2018shown\u2019 (as opposed to \u2018hidden\u2019) the change is\n immediately visible.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\by_\bs_\bt_\be_\bm_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br, _\ba_\bl_\b__\bs_\bh_\bo_\bw_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br,\n _\ba_\bl_\b__\bh_\bi_\bd_\be_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bsy\bys\bst\bte\bem\bm_\b_m\bmo\bou\bus\bse\be_\b_c\bcu\bur\brs\bso\bor\br *\b**\b**\b**\b**\b*\n bool al_set_system_mouse_cursor(ALLEGRO_DISPLAY *display,\n ALLEGRO_SYSTEM_MOUSE_CURSOR cursor_id)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the given system mouse cursor to be the current mouse cursor for the given\n display. If the cursor is currently \u2018shown\u2019 (as opposed to \u2018hidden\u2019) the change\n is immediately visible.\n@@ -278,14 +312,16 @@\n * ALLEGRO_SYSTEM_MOUSE_CURSOR_PROGRESS\n * ALLEGRO_SYSTEM_MOUSE_CURSOR_PRECISION\n * ALLEGRO_SYSTEM_MOUSE_CURSOR_LINK\n * ALLEGRO_SYSTEM_MOUSE_CURSOR_ALT_SELECT\n * ALLEGRO_SYSTEM_MOUSE_CURSOR_UNAVAILABLE\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br, _\ba_\bl_\b__\bs_\bh_\bo_\bw_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br, _\ba_\bl_\b__\bh_\bi_\bd_\be_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bca\ban\bn_\b_g\bge\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_c\bcu\bur\brs\bso\bor\br_\b_p\bpo\bos\bsi\bit\bti\bio\bon\bn *\b**\b**\b**\b**\b*\n bool al_can_get_mouse_cursor_position(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if getting the global mouse cursor position is available.\n Since: 5.2.9\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br_\b__\bp_\bo_\bs_\bi_\bt_\bi_\bo_\bn\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_c\bcu\bur\brs\bso\bor\br_\b_p\bpo\bos\bsi\bit\bti\bio\bon\bn *\b**\b**\b**\b**\b*\n@@ -293,28 +329,37 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n On platforms where this information is available, this function returns the\n global location of the mouse cursor, relative to the desktop. You should not\n normally use this function, as the information is not useful except for special\n scenarios as moving a window.\n Returns true on success, false on failure.\n See also: _\ba_\bl_\b__\bc_\ba_\bn_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br_\b__\bp_\bo_\bs_\bi_\bt_\bi_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\bn_\bo_\bf_\br_\ba_\bm_\be_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_h\bhi\bid\bde\be_\b_m\bmo\bou\bus\bse\be_\b_c\bcu\bur\brs\bso\bor\br *\b**\b**\b**\b**\b*\n bool al_hide_mouse_cursor(ALLEGRO_DISPLAY *display)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Hide the mouse cursor in the given display. This has no effect on what the\n current mouse cursor looks like; it just makes it disappear.\n Returns true on success (or if the cursor already was hidden), false otherwise.\n See also: _\ba_\bl_\b__\bs_\bh_\bo_\bw_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b._\bc\n+ * _\be_\bx_\b__\bo_\bg_\br_\be_\b3_\bd_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bsh\bho\bow\bw_\b_m\bmo\bou\bus\bse\be_\b_c\bcu\bur\brs\bso\bor\br *\b**\b**\b**\b**\b*\n bool al_show_mouse_cursor(ALLEGRO_DISPLAY *display)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Make a mouse cursor visible in the given display.\n Returns true if a mouse cursor is shown as a result of the call (or one already\n was visible), false otherwise.\n See also: _\ba_\bl_\b__\bh_\bi_\bd_\be_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br\n+Examples:\n+ * _\be_\bx_\b__\bo_\bg_\br_\be_\b3_\bd_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bc_\bu_\br_\bs_\bo_\br_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bgr\bra\bab\bb_\b_m\bmo\bou\bus\bse\be *\b**\b**\b**\b**\b*\n bool al_grab_mouse(ALLEGRO_DISPLAY *display)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Confine the mouse cursor to the given display. The mouse cursor can only be\n confined to one display at a time.\n Returns true if successful, otherwise returns false. Do not assume that the\n cursor will remain confined until you call _\ba_\bl_\b__\bu_\bn_\bg_\br_\ba_\bb_\b__\bm_\bo_\bu_\bs_\be. It may lose the\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/native_dialog.html", "source2": "./usr/share/doc/allegro5-doc/refman/native_dialog.html", "unified_diff": "@@ -267,20 +267,32 @@\n 
     #include <allegro5/allegro_native_dialog.h>
    \n

    ALLEGRO_FILECHOOSER

    \n 
    typedef struct ALLEGRO_FILECHOOSER ALLEGRO_FILECHOOSER;
    \n

    Source\n Code

    \n

    Opaque handle to a native file dialog.

    \n+

    Examples:

    \n+
      \n+
    • ex_native_filechooser.c
      • \n+
    \n

    ALLEGRO_TEXTLOG

    \n 
    typedef struct ALLEGRO_TEXTLOG ALLEGRO_TEXTLOG;
    \n

    Source\n Code

    \n

    Opaque handle to a text log window.

    \n+

    Examples:

    \n+
      \n+
    • common.c
      • \n+
    • ex_native_filechooser.c
      • \n+
    \n

    al_init_native_dialog_addon

    \n 
    bool al_init_native_dialog_addon(void)
    \n

    Source\n Code

    \n

    Initialise the native dialog addon.

    \n

    Returns true on success, false on error.

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

    \n
    \n

    See also: al_shutdown_native_dialog_addon

    \n+

    Examples:

    \n+
      \n+
    • common.c
      • \n+
    • ex_window_maximized.c
      • \n+
    • ex_menu.c
      • \n+
    \n al_is_native_dialog_addon_initialized\n 
    bool al_is_native_dialog_addon_initialized(void)
    \n

    Source\n Code

    \n

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

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_native_filechooser.c
      • \n+
    \n

    al_show_native_file_dialog

    \n 
    bool al_show_native_file_dialog(ALLEGRO_DISPLAY *display,\n    ALLEGRO_FILECHOOSER *dialog)
    \n

    Source\n Code

    \n

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

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

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_native_filechooser.c
      • \n+
    \n al_get_native_file_dialog_count\n 
    int al_get_native_file_dialog_count(const ALLEGRO_FILECHOOSER *dialog)
    \n

    Source\n Code

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_native_filechooser.c
      • \n+
    \n al_get_native_file_dialog_path\n 
    const char *al_get_native_file_dialog_path(\n    const ALLEGRO_FILECHOOSER *dialog, size_t i)
    \n

    Source\n Code

    \n@@ -452,21 +488,31 @@\n -1.

    \n
    \n

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

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_native_filechooser.c
      • \n+
    \n al_destroy_native_file_dialog\n 
    void al_destroy_native_file_dialog(ALLEGRO_FILECHOOSER *dialog)
    \n

    Source\n Code

    \n

    Frees up all resources used by the file dialog.

    \n+

    Examples:

    \n+
      \n+
    • ex_native_filechooser.c
      • \n+
    \n

    al_show_native_message_box

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

    Source\n Code

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

    Examples:

    \n+
      \n+
    • ex_nodisplay.c
      • \n+
    • common.c
      • \n+
    • ex_menu.c
      • \n+
    \n

    al_open_native_text_log

    \n 
    ALLEGRO_TEXTLOG *al_open_native_text_log(char const *title, int flags)
    \n

    Source\n Code

    \n

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

    \n

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

    \n
    \n

    See also: al_append_native_text_log,\n al_close_native_text_log

    \n+

    Examples:

    \n+
      \n+
    • common.c
      • \n+
    • ex_native_filechooser.c
      • \n+
    \n

    al_close_native_text_log

    \n 
    void al_close_native_text_log(ALLEGRO_TEXTLOG *textlog)
    \n

    Source\n Code

    \n

    Closes a message log window opened with al_open_native_text_log\n earlier.

    \n

    Does nothing if passed NULL.

    \n

    See also: al_open_native_text_log

    \n+

    Examples:

    \n+
      \n+
    • common.c
      • \n+
    • ex_native_filechooser.c
      • \n+
    \n

    al_append_native_text_log

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

    Source\n Code

    \n

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

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • common.c
      • \n+
    • ex_native_filechooser.c
      • \n+
    \n al_get_native_text_log_event_source\n 
    ALLEGRO_EVENT_SOURCE *al_get_native_text_log_event_source(\n    ALLEGRO_TEXTLOG *textlog)
    \n

    Source\n Code

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

    Examples:

    \n+
      \n+
    • common.c
      • \n+
    • ex_saw.c
      • \n+
    • ex_resample_test.c
      • \n+
    \n al_get_allegro_native_dialog_version\n 
    uint32_t al_get_allegro_native_dialog_version(void)
    \n

    Source\n Code

    \n

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

    typedef struct ALLEGRO_MENU ALLEGRO_MENU;
    \n

    Source\n Code

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    ALLEGRO_MENU_INFO

    \n 
    typedef struct ALLEGRO_MENU_INFO {
    \n

    Source\n Code

    \n

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

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

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

    \n

    See also: al_build_menu

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_create_menu

    \n 
    ALLEGRO_MENU *al_create_menu(void)
    \n

    Source\n Code

    \n

    Creates a menu container that can hold menu items.

    \n

    Returns NULL on failure.

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

    \n

    Returns NULL on failure.

    \n

    Since: 5.1.0

    \n

    See also: al_create_menu, al_build_menu

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_build_menu

    \n 
    ALLEGRO_MENU *al_build_menu(ALLEGRO_MENU_INFO *info)
    \n

    Source\n Code

    \n

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

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

    \n

    Since: 5.1.0

    \n

    See also: ALLEGRO_MENU_INFO, al_create_menu, al_create_popup_menu

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_append_menu_item

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

    Source\n Code

    \n

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

    \n

    Since: 5.1.0

    \n

    See also: al_insert_menu_item,\n al_remove_menu_item

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_insert_menu_item

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

    Source\n Code

    \n

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

    Returns true if an item was removed.

    \n

    Since: 5.1.0

    \n

    See also: al_append_menu_item,\n al_insert_menu_item,\n al_destroy_menu

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_clone_menu

    \n 
    ALLEGRO_MENU *al_clone_menu(ALLEGRO_MENU *menu)
    \n

    Source\n Code

    \n

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

    \n

    Returns the cloned menu.

    \n

    Since: 5.1.0

    \n

    See also: al_clone_menu_for_popup

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_clone_menu_for_popup

    \n 
    ALLEGRO_MENU *al_clone_menu_for_popup(ALLEGRO_MENU *menu)
    \n

    Source\n Code

    \n

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

    \n

    Since: 5.1.0

    \n

    See also: al_clone_menu

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_destroy_menu

    \n 
    void al_destroy_menu(ALLEGRO_MENU *menu)
    \n

    Source\n Code

    \n

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

    \n

    Since: 5.1.0

    \n

    See also: al_remove_menu_item

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_get_menu_item_caption

    \n 
    const char *al_get_menu_item_caption(ALLEGRO_MENU *menu, int pos)
    \n

    Source\n Code

    \n

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

    \n@@ -882,41 +1012,56 @@\n Code

    \n

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

    \n

    Since: 5.1.0

    \n

    See also: al_get_menu_item_caption

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_get_menu_item_flags

    \n 
    int al_get_menu_item_flags(ALLEGRO_MENU *menu, int pos)
    \n

    Source\n Code

    \n

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

    \n

    Returns -1 if the item was not found.

    \n

    Since: 5.1.0

    \n

    See also: al_set_menu_item_flags,\n al_toggle_menu_item_flags

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_set_menu_item_flags

    \n 
    void al_set_menu_item_flags(ALLEGRO_MENU *menu, int pos, int flags)
    \n

    Source\n Code

    \n

    Updates the menu item\u2019s flags. See al_insert_menu_item\n for a description of the available flags.

    \n

    Since: 5.1.0

    \n

    See also: al_get_menu_item_flags,\n al_toggle_menu_item_flags

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_toggle_menu_item_flags

    \n 
    int al_toggle_menu_item_flags(ALLEGRO_MENU *menu, int pos, int flags)
    \n

    Source\n Code

    \n

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

    \n

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

    \n

    Since: 5.1.0

    \n

    See also: al_get_menu_item_icon,\n al_clone_bitmap

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_find_menu

    \n 
    ALLEGRO_MENU *al_find_menu(ALLEGRO_MENU *haystack, uint16_t id)
    \n

    Source\n Code

    \n

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

    \n

    Returns the menu, if found. Otherwise returns NULL.

    \n

    Since: 5.1.0

    \n

    See also: al_find_menu_item

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_find_menu_item

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

    Source\n Code

    \n

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

    Since: 5.1.0

    \n

    See also: al_register_event_source,\n al_enable_menu_event_source,\n al_disable_menu_event_source

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_enable_menu_event_source

    \n 
    ALLEGRO_EVENT_SOURCE *al_enable_menu_event_source(ALLEGRO_MENU *menu)
    \n

    Source\n Code

    \n

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

    \n \n

    Returns true if successful.

    \n

    Since: 5.1.0

    \n

    See also: al_create_menu, al_remove_display_menu

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_popup_menu

    \n 
    bool al_popup_menu(ALLEGRO_MENU *popup, ALLEGRO_DISPLAY *display)
    \n

    Source\n Code

    \n

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

    \n \n

    Since: 5.1.0

    \n

    See also: al_create_popup_menu

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

    al_remove_display_menu

    \n 
    ALLEGRO_MENU *al_remove_display_menu(ALLEGRO_DISPLAY *display)
    \n

    Source\n Code

    \n

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

    \n

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

    \n

    Since: 5.1.0

    \n

    See also: al_set_display_menu

    \n+

    Examples:

    \n+
      \n+
    • ex_menu.c
      • \n+
    \n

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

    \n \n \n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -90,30 +90,39 @@\n These functions are declared in the following header file. Link with\n allegro_dialog.\n #include \n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_F\bFI\bIL\bLE\bEC\bCH\bHO\bOO\bOS\bSE\bER\bR *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_FILECHOOSER ALLEGRO_FILECHOOSER;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Opaque handle to a native file dialog.\n+Examples:\n+ * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_T\bTE\bEX\bXT\bTL\bLO\bOG\bG *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_TEXTLOG ALLEGRO_TEXTLOG;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Opaque handle to a text log window.\n+Examples:\n+ * _\bc_\bo_\bm_\bm_\bo_\bn_\b._\bc\n+ * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bni\bit\bt_\b_n\bna\bat\bti\biv\bve\be_\b_d\bdi\bia\bal\blo\bog\bg_\b_a\bad\bdd\bdo\bon\bn *\b**\b**\b**\b**\b**\b*\n bool al_init_native_dialog_addon(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Initialise the native dialog addon.\n Returns true on success, false on error.\n Since: 5.0.9, 5.1.0\n N\bNo\bot\bte\be:\b: Prior to Allegro 5.1.0 native dialog functions could be called\n without explicit initialisation, but that is now deprecated. Future\n functionality may require explicit initialisation. An exception is\n _\ba_\bl_\b__\bs_\bh_\bo_\bw_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bm_\be_\bs_\bs_\ba_\bg_\be_\b__\bb_\bo_\bx, which may be useful to show an error\n message if Allegro fails to initialise.\n See also: _\ba_\bl_\b__\bs_\bh_\bu_\bt_\bd_\bo_\bw_\bn_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bd_\bi_\ba_\bl_\bo_\bg_\b__\ba_\bd_\bd_\bo_\bn\n+Examples:\n+ * _\bc_\bo_\bm_\bm_\bo_\bn_\b._\bc\n+ * _\be_\bx_\b__\bw_\bi_\bn_\bd_\bo_\bw_\b__\bm_\ba_\bx_\bi_\bm_\bi_\bz_\be_\bd_\b._\bc\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_n\bna\bat\bti\biv\bve\be_\b_d\bdi\bia\bal\blo\bog\bg_\b_a\bad\bdd\bdo\bon\bn_\b_i\bin\bni\bit\bti\bia\bal\bli\biz\bze\bed\bd *\b**\b**\b**\b**\b**\b*\n bool al_is_native_dialog_addon_initialized(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if the native dialog addon is initialized, otherwise returns\n false.\n Since: 5.2.6\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bsh\bhu\but\btd\bdo\bow\bwn\bn_\b_n\bna\bat\bti\biv\bve\be_\b_d\bdi\bia\bal\blo\bog\bg_\b_a\bad\bdd\bdo\bon\bn *\b**\b**\b**\b**\b**\b*\n@@ -180,45 +189,55 @@\n If supported, allow selecting multiple files.\n Returns:\n A handle to the dialog which you can pass to _\ba_\bl_\b__\bs_\bh_\bo_\bw_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\b__\bd_\bi_\ba_\bl_\bo_\bg to\n display it, and from which you then can query the results using\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\b__\bd_\bi_\ba_\bl_\bo_\bg_\b__\bc_\bo_\bu_\bn_\bt and _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\b__\bd_\bi_\ba_\bl_\bo_\bg_\b__\bp_\ba_\bt_\bh. When you\n are done, call _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\b__\bd_\bi_\ba_\bl_\bo_\bg on it.\n If a dialog window could not be created then this function returns NULL.\n+Examples:\n+ * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bsh\bho\bow\bw_\b_n\bna\bat\bti\biv\bve\be_\b_f\bfi\bil\ble\be_\b_d\bdi\bia\bal\blo\bog\bg *\b**\b**\b**\b**\b**\b*\n bool al_show_native_file_dialog(ALLEGRO_DISPLAY *display,\n ALLEGRO_FILECHOOSER *dialog)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Show the dialog window. The display may be NULL, otherwise the given display is\n treated as the parent if possible.\n This function blocks the calling thread until it returns, so you may want to\n spawn a thread with _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bt_\bh_\br_\be_\ba_\bd and call it from inside that thread.\n Returns true on success, false on failure.\n N\bNo\bot\bte\be:\b: On Android, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bD_\bI_\bS_\bP_\bL_\bA_\bY_\b__\bH_\bA_\bL_\bT_\b__\bD_\bR_\bA_\bW_\bI_\bN_\bG and\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bD_\bI_\bS_\bP_\bL_\bA_\bY_\b__\bR_\bE_\bS_\bU_\bM_\bE_\b__\bD_\bR_\bA_\bW_\bI_\bN_\bG need to be handled before this\n function returns. This means that you must call it from a different\n thread.\n+Examples:\n+ * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_n\bna\bat\bti\biv\bve\be_\b_f\bfi\bil\ble\be_\b_d\bdi\bia\bal\blo\bog\bg_\b_c\bco\bou\bun\bnt\bt *\b**\b**\b**\b**\b**\b*\n int al_get_native_file_dialog_count(const ALLEGRO_FILECHOOSER *dialog)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the number of files selected, or 0 if the dialog was cancelled.\n+Examples:\n+ * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_n\bna\bat\bti\biv\bve\be_\b_f\bfi\bil\ble\be_\b_d\bdi\bia\bal\blo\bog\bg_\b_p\bpa\bat\bth\bh *\b**\b**\b**\b**\b**\b*\n const char *al_get_native_file_dialog_path(\n const ALLEGRO_FILECHOOSER *dialog, size_t i)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns one of the selected paths with index i. The index should range from 0\n to the return value of _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\b__\bd_\bi_\ba_\bl_\bo_\bg_\b__\bc_\bo_\bu_\bn_\bt -1.\n N\bNo\bot\bte\be:\b: On Android, this function returns a content:// Universal\n Resource Identifier instead of a file path due to the constraints of\n Scoped Storage. Selected files may be accessed using\n _\ba_\bl_\b__\ba_\bn_\bd_\br_\bo_\bi_\bd_\b__\bo_\bp_\be_\bn_\b__\bf_\bd.\n+Examples:\n+ * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_n\bna\bat\bti\biv\bve\be_\b_f\bfi\bil\ble\be_\b_d\bdi\bia\bal\blo\bog\bg *\b**\b**\b**\b**\b**\b*\n void al_destroy_native_file_dialog(ALLEGRO_FILECHOOSER *dialog)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Frees up all resources used by the file dialog.\n+Examples:\n+ * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bsh\bho\bow\bw_\b_n\bna\bat\bti\biv\bve\be_\b_m\bme\bes\bss\bsa\bag\bge\be_\b_b\bbo\box\bx *\b**\b**\b**\b**\b**\b*\n int al_show_native_message_box(ALLEGRO_DISPLAY *display,\n char const *title, char const *heading, char const *text,\n char const *buttons, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Show a native GUI message box. This can be used for example to display an error\n message if creation of an initial display fails. The display may be NULL,\n@@ -261,14 +280,18 @@\n \"If you click yes then you are confirming that \\\"Yes\\\" \"\n \"is your response to the query which you have \"\n \"generated by the action you took to open this \"\n \"message box.\",\n NULL,\n ALLEGRO_MESSAGEBOX_YES_NO\n );\n+Examples:\n+ * _\be_\bx_\b__\bn_\bo_\bd_\bi_\bs_\bp_\bl_\ba_\by_\b._\bc\n+ * _\bc_\bo_\bm_\bm_\bo_\bn_\b._\bc\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_o\bop\bpe\ben\bn_\b_n\bna\bat\bti\biv\bve\be_\b_t\bte\bex\bxt\bt_\b_l\blo\bog\bg *\b**\b**\b**\b**\b**\b*\n ALLEGRO_TEXTLOG *al_open_native_text_log(char const *title, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Opens a window to which you can append log messages with\n _\ba_\bl_\b__\ba_\bp_\bp_\be_\bn_\bd_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bt_\be_\bx_\bt_\b__\bl_\bo_\bg. This can be useful for debugging if you don\u2019t want\n to depend on a console being available.\n Use _\ba_\bl_\b__\bc_\bl_\bo_\bs_\be_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bt_\be_\bx_\bt_\b__\bl_\bo_\bg to close the window again.\n@@ -279,40 +302,53 @@\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bt_\be_\bx_\bt_\b__\bl_\bo_\bg_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be.\n ALLEGRO_TEXTLOG_MONOSPACE\n Use a monospace font to display the text.\n Returns NULL if there was an error opening the window, or if text log windows\n are not implemented on the platform.\n N\bNo\bot\bte\be:\b: On Android, logs can be viewed using logcat.\n See also: _\ba_\bl_\b__\ba_\bp_\bp_\be_\bn_\bd_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bt_\be_\bx_\bt_\b__\bl_\bo_\bg, _\ba_\bl_\b__\bc_\bl_\bo_\bs_\be_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bt_\be_\bx_\bt_\b__\bl_\bo_\bg\n+Examples:\n+ * _\bc_\bo_\bm_\bm_\bo_\bn_\b._\bc\n+ * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcl\blo\bos\bse\be_\b_n\bna\bat\bti\biv\bve\be_\b_t\bte\bex\bxt\bt_\b_l\blo\bog\bg *\b**\b**\b**\b**\b**\b*\n void al_close_native_text_log(ALLEGRO_TEXTLOG *textlog)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Closes a message log window opened with _\ba_\bl_\b__\bo_\bp_\be_\bn_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bt_\be_\bx_\bt_\b__\bl_\bo_\bg earlier.\n Does nothing if passed NULL.\n See also: _\ba_\bl_\b__\bo_\bp_\be_\bn_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bt_\be_\bx_\bt_\b__\bl_\bo_\bg\n+Examples:\n+ * _\bc_\bo_\bm_\bm_\bo_\bn_\b._\bc\n+ * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_a\bap\bpp\bpe\ben\bnd\bd_\b_n\bna\bat\bti\biv\bve\be_\b_t\bte\bex\bxt\bt_\b_l\blo\bog\bg *\b**\b**\b**\b**\b**\b*\n void al_append_native_text_log(ALLEGRO_TEXTLOG *textlog,\n char const *format, ...)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Appends a line of text to the message log window and scrolls to the bottom (if\n the line would not be visible otherwise). This works like printf. A line is\n continued until you add a newline character.\n If the window is NULL then this function will fall back to calling printf. This\n makes it convenient to support logging to a window or a terminal.\n+Examples:\n+ * _\bc_\bo_\bm_\bm_\bo_\bn_\b._\bc\n+ * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_n\bna\bat\bti\biv\bve\be_\b_t\bte\bex\bxt\bt_\b_l\blo\bog\bg_\b_e\bev\bve\ben\bnt\bt_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_EVENT_SOURCE *al_get_native_text_log_event_source(\n ALLEGRO_TEXTLOG *textlog)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get an event source for a text log window. The possible events are:\n ALLEGRO_EVENT_NATIVE_DIALOG_CLOSE\n The window was requested to be closed, either by pressing the close\n button or pressing Escape on the keyboard. The user.data1 field will hold\n a pointer to the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bT_\bE_\bX_\bT_\bL_\bO_\bG which generated the event. The\n user.data2 field will be 1 if the event was generated as a result of a\n key press; otherwise it will be zero.\n+Examples:\n+ * _\bc_\bo_\bm_\bm_\bo_\bn_\b._\bc\n+ * _\be_\bx_\b__\bs_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\br_\be_\bs_\ba_\bm_\bp_\bl_\be_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bal\bll\ble\beg\bgr\bro\bo_\b_n\bna\bat\bti\biv\bve\be_\b_d\bdi\bia\bal\blo\bog\bg_\b_v\bve\ber\brs\bsi\bio\bon\bn *\b**\b**\b**\b**\b**\b*\n uint32_t al_get_allegro_native_dialog_version(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the (compiled) version of the addon, in the same format as\n _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bl_\bl_\be_\bg_\br_\bo_\b__\bv_\be_\br_\bs_\bi_\bo_\bn.\n *\b**\b**\b**\b**\b**\b* M\bMe\ben\bnu\bus\bs *\b**\b**\b**\b**\b**\b*\n Menus are implemented on Windows, X and OS X. Menus on X are implemented with\n@@ -361,14 +397,16 @@\n al_set_display_menu(display, NULL) before destroying any display with a menu\n attached, to avoid leaking resources.\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_M\bME\bEN\bNU\bU *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_MENU ALLEGRO_MENU;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An opaque data type that represents a menu that contains menu items. Each of\n the menu items may optionally include a sub-menu.\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_M\bME\bEN\bNU\bU_\b_I\bIN\bNF\bFO\bO *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_MENU_INFO {\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n A structure that defines how to create a complete menu system. For standard\n menu items, the following format is used:\n { caption, id, flags, icon }\n For special items, these macros are helpful:\n@@ -394,14 +432,16 @@\n ALLEGRO_END_OF_MENU\n };\n \n ALLEGRO_MENU *menu = al_build_menu(menu_info);\n If you prefer, you can build the menu without the structure by using\n _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bm_\be_\bn_\bu and _\ba_\bl_\b__\bi_\bn_\bs_\be_\br_\bt_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm.\n See also: _\ba_\bl_\b__\bb_\bu_\bi_\bl_\bd_\b__\bm_\be_\bn_\bu\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_m\bme\ben\bnu\bu *\b**\b**\b**\b**\b*\n ALLEGRO_MENU *al_create_menu(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Creates a menu container that can hold menu items.\n Returns NULL on failure.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bp_\bo_\bp_\bu_\bp_\b__\bm_\be_\bn_\bu, _\ba_\bl_\b__\bb_\bu_\bi_\bl_\bd_\b__\bm_\be_\bn_\bu\n@@ -410,32 +450,38 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Creates a menu container for popup menus. Only the root (outermost) menu should\n be created with this function. Sub menus of popups should be created with\n _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bm_\be_\bn_\bu.\n Returns NULL on failure.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bm_\be_\bn_\bu, _\ba_\bl_\b__\bb_\bu_\bi_\bl_\bd_\b__\bm_\be_\bn_\bu\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_b\bbu\bui\bil\bld\bd_\b_m\bme\ben\bnu\bu *\b**\b**\b**\b**\b*\n ALLEGRO_MENU *al_build_menu(ALLEGRO_MENU_INFO *info)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Builds a menu based on the specifications of a sequence of ALLEGRO_MENU_INFO\n elements.\n Returns a pointer to the root ALLEGRO_MENU, or NULL on failure. To gain access\n to the other menus and items, you will need to search for them using\n _\ba_\bl_\b__\bf_\bi_\bn_\bd_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm.\n Since: 5.1.0\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bM_\bE_\bN_\bU_\b__\bI_\bN_\bF_\bO, _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bm_\be_\bn_\bu, _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bp_\bo_\bp_\bu_\bp_\b__\bm_\be_\bn_\bu\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_a\bap\bpp\bpe\ben\bnd\bd_\b_m\bme\ben\bnu\bu_\b_i\bit\bte\bem\bm *\b**\b**\b**\b**\b*\n int al_append_menu_item(ALLEGRO_MENU *parent, char const *title, uint16_t id,\n int flags, ALLEGRO_BITMAP *icon, ALLEGRO_MENU *submenu)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Appends a menu item to the end of the menu. See _\ba_\bl_\b__\bi_\bn_\bs_\be_\br_\bt_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm for more\n information.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bi_\bn_\bs_\be_\br_\bt_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm, _\ba_\bl_\b__\br_\be_\bm_\bo_\bv_\be_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bns\bse\ber\brt\bt_\b_m\bme\ben\bnu\bu_\b_i\bit\bte\bem\bm *\b**\b**\b**\b**\b*\n int al_insert_menu_item(ALLEGRO_MENU *parent, int pos, char const *title,\n uint16_t id, int flags, ALLEGRO_BITMAP *icon, ALLEGRO_MENU *submenu)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Inserts a menu item at the spot specified. See the introductory text for a\n detailed explanation of how the pos parameter is interpreted.\n The parent menu can be a popup menu or a regular menu. To underline one\n@@ -463,36 +509,44 @@\n a sub-menu, it too is destroyed. Any references to it are invalidated. If you\n want to preserve that sub-menu, you should first make a copy with\n _\ba_\bl_\b__\bc_\bl_\bo_\bn_\be_\b__\bm_\be_\bn_\bu.\n This is safe to call on a menu that is currently being displayed.\n Returns true if an item was removed.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\ba_\bp_\bp_\be_\bn_\bd_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm, _\ba_\bl_\b__\bi_\bn_\bs_\be_\br_\bt_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bm_\be_\bn_\bu\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcl\blo\bon\bne\be_\b_m\bme\ben\bnu\bu *\b**\b**\b**\b**\b*\n ALLEGRO_MENU *al_clone_menu(ALLEGRO_MENU *menu)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Makes a copy of a menu so that it can be reused on another display. The menu\n being cloned can be anything: a regular menu, a popup menu, or a sub-menu.\n Returns the cloned menu.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bc_\bl_\bo_\bn_\be_\b__\bm_\be_\bn_\bu_\b__\bf_\bo_\br_\b__\bp_\bo_\bp_\bu_\bp\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcl\blo\bon\bne\be_\b_m\bme\ben\bnu\bu_\b_f\bfo\bor\br_\b_p\bpo\bop\bpu\bup\bp *\b**\b**\b**\b**\b*\n ALLEGRO_MENU *al_clone_menu_for_popup(ALLEGRO_MENU *menu)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Exactly like _\ba_\bl_\b__\bc_\bl_\bo_\bn_\be_\b__\bm_\be_\bn_\bu, except that the copy is for a popup menu.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bc_\bl_\bo_\bn_\be_\b__\bm_\be_\bn_\bu\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_m\bme\ben\bnu\bu *\b**\b**\b**\b**\b*\n void al_destroy_menu(ALLEGRO_MENU *menu)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Destroys an entire menu, including its sub-menus. Any references to it or a\n sub-menu are no longer valid. It is safe to call this on a menu that is\n currently being displayed.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\br_\be_\bm_\bo_\bv_\be_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bme\ben\bnu\bu_\b_i\bit\bte\bem\bm_\b_c\bca\bap\bpt\bti\bio\bon\bn *\b**\b**\b**\b**\b*\n const char *al_get_menu_item_caption(ALLEGRO_MENU *menu, int pos)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the caption associated with the menu item. It is valid as long as the\n caption is not modified.\n Returns NULL if the item was not found.\n Since: 5.1.0\n@@ -500,29 +554,35 @@\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_m\bme\ben\bnu\bu_\b_i\bit\bte\bem\bm_\b_c\bca\bap\bpt\bti\bio\bon\bn *\b**\b**\b**\b**\b*\n void al_set_menu_item_caption(ALLEGRO_MENU *menu, int pos, const char *caption)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Updates the menu item caption with the new caption. This will invalidate any\n previous calls to _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm_\b__\bc_\ba_\bp_\bt_\bi_\bo_\bn.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm_\b__\bc_\ba_\bp_\bt_\bi_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bme\ben\bnu\bu_\b_i\bit\bte\bem\bm_\b_f\bfl\bla\bag\bgs\bs *\b**\b**\b**\b**\b*\n int al_get_menu_item_flags(ALLEGRO_MENU *menu, int pos)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the currently set flags. See _\ba_\bl_\b__\bi_\bn_\bs_\be_\br_\bt_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm for a description of\n the available flags.\n Returns -1 if the item was not found.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm_\b__\bf_\bl_\ba_\bg_\bs, _\ba_\bl_\b__\bt_\bo_\bg_\bg_\bl_\be_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm_\b__\bf_\bl_\ba_\bg_\bs\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_m\bme\ben\bnu\bu_\b_i\bit\bte\bem\bm_\b_f\bfl\bla\bag\bgs\bs *\b**\b**\b**\b**\b*\n void al_set_menu_item_flags(ALLEGRO_MENU *menu, int pos, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Updates the menu item\u2019s flags. See _\ba_\bl_\b__\bi_\bn_\bs_\be_\br_\bt_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm for a description of the\n available flags.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm_\b__\bf_\bl_\ba_\bg_\bs, _\ba_\bl_\b__\bt_\bo_\bg_\bg_\bl_\be_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm_\b__\bf_\bl_\ba_\bg_\bs\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_t\bto\bog\bgg\bgl\ble\be_\b_m\bme\ben\bnu\bu_\b_i\bit\bte\bem\bm_\b_f\bfl\bla\bag\bgs\bs *\b**\b**\b**\b**\b*\n int al_toggle_menu_item_flags(ALLEGRO_MENU *menu, int pos, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Toggles the specified menu item\u2019s flags. See _\ba_\bl_\b__\bi_\bn_\bs_\be_\br_\bt_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm for a\n description of the available flags.\n Returns a bitfield of only the specified flags that are set after the toggle. A\n flag that was not toggled will not be returned, even if it is set. Returns -\n@@ -545,22 +605,26 @@\n Sets the icon for the specified menu item. The menu assumes ownership of the\n ALLEGRO_BITMAP and may invalidate the pointer, so you must clone it if you wish\n to continue using it.\n If a video bitmap is passed, it will automatically be converted to a memory\n bitmap, so it is preferable to pass a memory bitmap.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm_\b__\bi_\bc_\bo_\bn, _\ba_\bl_\b__\bc_\bl_\bo_\bn_\be_\b__\bb_\bi_\bt_\bm_\ba_\bp\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_f\bfi\bin\bnd\bd_\b_m\bme\ben\bnu\bu *\b**\b**\b**\b**\b*\n ALLEGRO_MENU *al_find_menu(ALLEGRO_MENU *haystack, uint16_t id)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Searches in the haystack menu for any submenu with the given id. (Note that\n this only represents a literal ID, and cannot be used as an index.)\n Returns the menu, if found. Otherwise returns NULL.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bf_\bi_\bn_\bd_\b__\bm_\be_\bn_\bu_\b__\bi_\bt_\be_\bm\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_f\bfi\bin\bnd\bd_\b_m\bme\ben\bnu\bu_\b_i\bit\bte\bem\bm *\b**\b**\b**\b**\b*\n bool al_find_menu_item(ALLEGRO_MENU *haystack, uint16_t id, ALLEGRO_MENU\n **menu,\n int *index)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Searches in the haystack menu for an item with the given id. (Note that this\n only represents a literal ID, and cannot be used as an index.)\n@@ -575,14 +639,16 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the default event source used for menu clicks. If a menu was not given\n its own event source via _\ba_\bl_\b__\be_\bn_\ba_\bb_\bl_\be_\b__\bm_\be_\bn_\bu_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be, then it will use this\n default source.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\br_\be_\bg_\bi_\bs_\bt_\be_\br_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be, _\ba_\bl_\b__\be_\bn_\ba_\bb_\bl_\be_\b__\bm_\be_\bn_\bu_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be,\n _\ba_\bl_\b__\bd_\bi_\bs_\ba_\bb_\bl_\be_\b__\bm_\be_\bn_\bu_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_e\ben\bna\bab\bbl\ble\be_\b_m\bme\ben\bnu\bu_\b_e\bev\bve\ben\bnt\bt_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b*\n ALLEGRO_EVENT_SOURCE *al_enable_menu_event_source(ALLEGRO_MENU *menu)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Enables a unique event source for this menu. It and all of its sub-menus will\n use this event source. (It is safe to call this multiple times on the same\n menu.)\n Returns the event source.\n@@ -614,14 +680,16 @@\n N\bNo\bot\bte\be:\b: Attaching a menu may cause the window as available to your\n application to be resized! You should listen for a resize event,\n check how much space was lost, and resize the window accordingly if\n you want to maintain your window\u2019s prior size.\n Returns true if successful.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bm_\be_\bn_\bu, _\ba_\bl_\b__\br_\be_\bm_\bo_\bv_\be_\b__\bd_\bi_\bs_\bp_\bl_\ba_\by_\b__\bm_\be_\bn_\bu\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_p\bpo\bop\bpu\bup\bp_\b_m\bme\ben\bnu\bu *\b**\b**\b**\b**\b*\n bool al_popup_menu(ALLEGRO_MENU *popup, ALLEGRO_DISPLAY *display)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Displays a context menu next to the mouse cursor. The menu must have been\n created with _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bp_\bo_\bp_\bu_\bp_\b__\bm_\be_\bn_\bu. It generates events just like a regular\n display menu does. It is possible that the menu will be canceled without any\n selection being made.\n@@ -631,17 +699,21 @@\n Returns true if the context menu was displayed.\n N\bNo\bot\bte\be:\b: On Linux this function will fail if any of the mouse keys are\n held down. I.e. it will only reliably work if you handle it in\n ALLEGRO_MOUSE_BUTTON_UP events and even then only if that event\n corresponds to the final mouse button that was pressed.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bp_\bo_\bp_\bu_\bp_\b__\bm_\be_\bn_\bu\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bem\bmo\bov\bve\be_\b_d\bdi\bis\bsp\bpl\bla\bay\by_\b_m\bme\ben\bnu\bu *\b**\b**\b**\b**\b*\n ALLEGRO_MENU *al_remove_display_menu(ALLEGRO_DISPLAY *display)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Detaches the menu associated with the display and returns it. The menu can then\n be used on a different display.\n If you simply want to destroy the active menu, you can call _\ba_\bl_\b__\bs_\be_\bt_\b__\bd_\bi_\bs_\bp_\bl_\ba_\by_\b__\bm_\be_\bn_\bu\n with a NULL menu.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bd_\bi_\bs_\bp_\bl_\ba_\by_\b__\bm_\be_\bn_\bu\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/opengl.html", "source2": "./usr/share/doc/allegro5-doc/refman/opengl.html", "unified_diff": "@@ -233,14 +233,21 @@\n

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

    \n \n+

    Examples:

    \n+
      \n+
    • ex_opengl.c
      • \n+
    • ex_glext.c
      • \n+
    \n

    al_get_opengl_proc_address

    \n 
    void *al_get_opengl_proc_address(const char *name)
    \n

    Source\n Code

    \n

    Helper to get the address of an OpenGL symbol

    \n

    Example:

    \n@@ -274,14 +281,21 @@\n

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

    \n

    Example:

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

    Examples:

    \n+
      \n+
    • ex_opengl_pixel_shader.c
      • \n+
    • ex_gldepth.c
      • \n+
    \n

    al_get_opengl_texture_size

    \n 
    bool al_get_opengl_texture_size(ALLEGRO_BITMAP *bitmap, int *w, int *h)
    \n

    Source\n Code

    \n

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

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

    \n

    Example:

    \n 
    bool packedpixels = al_have_opengl_extension("GL_EXT_packed_pixels");
    \n

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

    \n

    Returns true if the extension is available; false otherwise.

    \n+

    Examples:

    \n+
      \n+
    • ex_opengl_pixel_shader.c
      • \n+
    \n

    al_get_opengl_version

    \n 
    uint32_t al_get_opengl_version(void)
    \n

    Source\n Code

    \n

    Returns the OpenGL or OpenGL ES version number of the client (the\n computer the program is running on), for the current display. \u201c1.0\u201d is\n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -78,14 +78,17 @@\n In case you want to manually check for extensions and load function pointers\n yourself (say, in case the Allegro developers did not include it yet), you can\n use the _\ba_\bl_\b__\bh_\ba_\bv_\be_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\be_\bx_\bt_\be_\bn_\bs_\bi_\bo_\bn and _\ba_\bl_\b__\bg_\be_\bt_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\bp_\br_\bo_\bc_\b__\ba_\bd_\bd_\br_\be_\bs_\bs functions\n instead.\n N\bNo\bot\bte\be:\b: the exact extensions exposed depend on how Allegro was\n compiled. It is recommended to use _\ba_\bl_\b__\bh_\ba_\bv_\be_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\be_\bx_\bt_\be_\bn_\bs_\bi_\bo_\bn and\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\bp_\br_\bo_\bc_\b__\ba_\bd_\bd_\br_\be_\bs_\bs for the most stable experience.\n+Examples:\n+ * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b._\bc\n+ * _\be_\bx_\b__\bg_\bl_\be_\bx_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_o\bop\bpe\ben\bng\bgl\bl_\b_p\bpr\bro\boc\bc_\b_a\bad\bdd\bdr\bre\bes\bss\bs *\b**\b**\b**\b**\b**\b*\n void *al_get_opengl_proc_address(const char *name)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Helper to get the address of an OpenGL symbol\n Example:\n How to get the function g\bgl\blM\bMu\bul\blt\bti\biT\bTe\bex\bxC\bCo\boo\bor\brd\bd3\b3f\bfA\bAR\bRB\bB that comes with ARB\u2019s Multitexture\n extension:\n@@ -113,14 +116,17 @@\n Returns the OpenGL texture id internally used by the given bitmap if it uses\n one, else 0.\n Example:\n bitmap = al_load_bitmap(\"my_texture.png\");\n texture = al_get_opengl_texture(bitmap);\n if (texture != 0)\n glBindTexture(GL_TEXTURE_2D, texture);\n+Examples:\n+ * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\bp_\bi_\bx_\be_\bl_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bg_\bl_\bd_\be_\bp_\bt_\bh_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_o\bop\bpe\ben\bng\bgl\bl_\b_t\bte\bex\bxt\btu\bur\bre\be_\b_s\bsi\biz\bze\be *\b**\b**\b**\b**\b**\b*\n bool al_get_opengl_texture_size(ALLEGRO_BITMAP *bitmap, int *w, int *h)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Retrieves the size of the texture used for the bitmap. This can be different\n from the bitmap size if OpenGL only supports power-of-two sizes or if it is a\n sub-bitmap.\n Returns true on success, false on failure. Zero width and height are returned\n@@ -161,14 +167,16 @@\n This function is a helper to determine whether an OpenGL extension is available\n on the given display or not.\n Example:\n bool packedpixels = al_have_opengl_extension(\"GL_EXT_packed_pixels\");\n If p\bpa\bac\bck\bke\bed\bdp\bpi\bix\bxe\bel\bls\bs is true then you can safely use the constants related to the\n packed pixels extension.\n Returns true if the extension is available; false otherwise.\n+Examples:\n+ * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\bp_\bi_\bx_\be_\bl_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_o\bop\bpe\ben\bng\bgl\bl_\b_v\bve\ber\brs\bsi\bio\bon\bn *\b**\b**\b**\b**\b**\b*\n uint32_t al_get_opengl_version(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the OpenGL or OpenGL ES version number of the client (the computer the\n program is running on), for the current display. \u201c1.0\u201d is returned as\n 0x01000000, \u201c1.2.1\u201d is returned as 0x01020100, and \u201c1.2.2\u201d as 0x01020200, etc.\n A valid OpenGL context must exist for this function to work, which means you\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/path.html", "source2": "./usr/share/doc/allegro5-doc/refman/path.html", "unified_diff": "@@ -240,14 +240,23 @@\n followed by a directory separator and is neither \u201c.\u201d nor \u201c..\u201d, is\n treated as the last directory name in the path. Otherwise the last\n component is treated as the filename. The string may be NULL for an\n empty path.

    \n

    See also: al_create_path_for_directory,\n al_destroy_path

    \n+

    Examples:

    \n+
      \n+
    • ex_path.c
      • \n+
    • ex_path_test.c
      • \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_create_path_for_directory

    \n 
    ALLEGRO_PATH *al_create_path_for_directory(const char *str)
    \n

    Source\n Code

    \n

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

    void al_destroy_path(ALLEGRO_PATH *path)
    \n

    Source\n Code

    \n

    Free a path structure. Does nothing if passed NULL.

    \n

    See also: al_create_path, al_create_path_for_directory

    \n+

    Examples:

    \n+
      \n+
    • ex_get_path.c
      • \n+
    • ex_path.c
      • \n+
    • ex_path_test.c
      • \n+
    \n

    al_clone_path

    \n 
    ALLEGRO_PATH *al_clone_path(const ALLEGRO_PATH *path)
    \n

    Source\n Code

    \n

    Clones an ALLEGRO_PATH structure. Returns NULL on failure.

    \n

    See also: al_destroy_path

    \n+

    Examples:

    \n+
      \n+
    • ex_path.c
      • \n+
    • ex_path_test.c
      • \n+
    \n

    al_join_paths

    \n 
    bool al_join_paths(ALLEGRO_PATH *path, const ALLEGRO_PATH *tail)
    \n

    Source\n Code

    \n

    Concatenate two path structures. The first path structure is\n modified. If \u2018tail\u2019 is an absolute path, this function does nothing.

    \n

    If \u2018tail\u2019 is a relative path, all of its directory components will be\n appended to \u2018path\u2019. tail\u2019s filename will also overwrite path\u2019s filename,\n even if it is just the empty string.

    \n

    Tail\u2019s drive is ignored.

    \n

    Returns true if \u2018tail\u2019 was a relative path and so concatenated to\n \u2018path\u2019, otherwise returns false.

    \n

    See also: al_rebase_path

    \n+

    Examples:

    \n+
      \n+
    • ex_path_test.c
      • \n+
    \n

    al_rebase_path

    \n 
    bool al_rebase_path(const ALLEGRO_PATH *head, ALLEGRO_PATH *tail)
    \n

    Source\n Code

    \n

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

    \n

    For example, if head is \u201c/anchor/\u201d and tail is\n \u201cdata/file.ext\u201d, then after the call tail becomes\n \u201c/anchor/data/file.ext\u201d.

    \n

    See also: al_join_paths

    \n+

    Examples:

    \n+
      \n+
    • ex_path_test.c
      • \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_get_path_drive

    \n 
    const char *al_get_path_drive(const ALLEGRO_PATH *path)
    \n

    Source\n Code

    \n

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

    \n

    The \u201cdrive letter\u201d is only used on Windows, and is usually a string\n like \u201cc:\u201d, but may be something like \u201c\\\\Computer Name\u201d in the case of\n UNC (Uniform Naming Convention) syntax.

    \n+

    Examples:

    \n+
      \n+
    • ex_path.c
      • \n+
    • ex_path_test.c
      • \n+
    \n

    al_get_path_num_components

    \n 
    int al_get_path_num_components(const ALLEGRO_PATH *path)
    \n

    Source\n Code

    \n

    Return the number of directory components in a path.

    \n

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

    \n

    See also: al_get_path_component

    \n+

    Examples:

    \n+
      \n+
    • ex_path.c
      • \n+
    • ex_path_test.c
      • \n+
    \n

    al_get_path_component

    \n 
    const char *al_get_path_component(const ALLEGRO_PATH *path, int i)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_get_path_num_components,\n al_get_path_tail

    \n+

    Examples:

    \n+
      \n+
    • ex_path.c
      • \n+
    • ex_path_test.c
      • \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_get_path_tail

    \n 
    const char *al_get_path_tail(const ALLEGRO_PATH *path)
    \n

    Source\n Code

    \n

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

    \n+

    Examples:

    \n+
      \n+
    • ex_path_test.c
      • \n+
    \n

    al_get_path_filename

    \n 
    const char *al_get_path_filename(const ALLEGRO_PATH *path)
    \n

    Source\n Code

    \n

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

    \n

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

    \n

    See also: al_get_path_basename, al_get_path_extension, al_get_path_component

    \n+

    Examples:

    \n+
      \n+
    • ex_path.c
      • \n+
    • ex_path_test.c
      • \n+
    \n

    al_get_path_basename

    \n 
    const char *al_get_path_basename(const ALLEGRO_PATH *path)
    \n

    Source\n Code

    \n

    Return the basename, i.e.\u00a0filename with the extension removed. If the\n filename doesn\u2019t have an extension, the whole filename is the basename.\n If there is no filename part then the empty string is returned.

    \n

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

    \n

    See also: al_get_path_filename, al_get_path_extension

    \n+

    Examples:

    \n+
      \n+
    • ex_path_test.c
      • \n+
    \n

    al_get_path_extension

    \n 
    const char *al_get_path_extension(const ALLEGRO_PATH *path)
    \n

    Source\n Code

    \n

    Return a pointer to the start of the extension of the filename,\n i.e.\u00a0everything from the final dot (\u2018.\u2019) character onwards. If no dot\n exists, returns an empty string.

    \n

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

    \n

    See also: al_get_path_filename, al_get_path_basename

    \n+

    Examples:

    \n+
      \n+
    • ex_path_test.c
      • \n+
    • ex_physfs.c
      • \n+
    \n

    al_set_path_drive

    \n 
    void al_set_path_drive(ALLEGRO_PATH *path, const char *drive)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_get_path_drive

    \n+

    Examples:

    \n+
      \n+
    • ex_path_test.c
      • \n+
    \n

    al_append_path_component

    \n 
    void al_append_path_component(ALLEGRO_PATH *path, const char *s)
    \n

    Source\n Code

    \n

    Append a directory component.

    \n

    See also: al_insert_path_component

    \n+

    Examples:

    \n+
      \n+
    • ex_path_test.c
      • \n+
    \n

    al_insert_path_component

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

    Source\n Code

    \n

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

    \n

    See also: al_append_path_component,\n al_replace_path_component,\n al_remove_path_component

    \n+

    Examples:

    \n+
      \n+
    • ex_path_test.c
      • \n+
    \n

    al_replace_path_component

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

    Source\n Code

    \n

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

    \n

    See also: al_insert_path_component,\n al_remove_path_component

    \n+

    Examples:

    \n+
      \n+
    • ex_path_test.c
      • \n+
    \n

    al_remove_path_component

    \n 
    void al_remove_path_component(ALLEGRO_PATH *path, int i)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_insert_path_component,\n al_replace_path_component,\n al_drop_path_tail

    \n+

    Examples:

    \n+
      \n+
    • ex_path_test.c
      • \n+
    • ex_audio_chain.cpp
      • \n+
    \n

    al_drop_path_tail

    \n 
    void al_drop_path_tail(ALLEGRO_PATH *path)
    \n

    Source\n Code

    \n

    Remove the last directory component, if any.

    \n

    See also: al_remove_path_component

    \n+

    Examples:

    \n+
      \n+
    • ex_path_test.c
      • \n+
    \n

    al_set_path_filename

    \n 
    void al_set_path_filename(ALLEGRO_PATH *path, const char *filename)
    \n

    Source\n Code

    \n

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

    \n

    See also: al_set_path_extension, al_get_path_filename

    \n+

    Examples:

    \n+
      \n+
    • ex_path_test.c
      • \n+
    • ex_android.c
      • \n+
    \n

    al_set_path_extension

    \n 
    bool al_set_path_extension(ALLEGRO_PATH *path, char const *extension)
    \n

    Source\n Code

    \n

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

    \n

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

    \n

    See also: al_set_path_filename, al_get_path_extension

    \n+

    Examples:

    \n+
      \n+
    • ex_path_test.c
      • \n+
    \n

    al_path_cstr

    \n 
    const char *al_path_cstr(const ALLEGRO_PATH *path, char delim)
    \n

    Source\n Code

    \n

    Convert a path to its string representation, i.e.\u00a0optional drive,\n followed by directory components separated by \u2018delim\u2019, followed by an\n@@ -477,14 +605,23 @@\n

    To use the current native path separator, use ALLEGRO_NATIVE_PATH_SEP\n for \u2018delim\u2019.

    \n

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

    \n

    See also: al_path_ustr

    \n+

    Examples:

    \n+
      \n+
    • ex_get_path.c
      • \n+
    • ex_path.c
      • \n+
    • ex_file_slice.c
      • \n+
    \n

    al_path_ustr

    \n 
    const ALLEGRO_USTR *al_path_ustr(const ALLEGRO_PATH *path, char delim)
    \n

    Source\n Code

    \n

    Convert a path to its string representation, i.e.\u00a0optional drive,\n followed by directory components separated by \u2018delim\u2019, followed by an\n@@ -504,14 +641,21 @@\n Code

    \n

    Removes any leading \u2018..\u2019 directory components in absolute paths.\n Removes all \u2018.\u2019 directory components.

    \n

    Note that this does not collapse \u201cx/../y\u201d sections into \u201cy\u201d.\n This is by design. If \u201c/foo\u201d on your system is a symlink to \u201c/bar/baz\u201d,\n then \u201c/foo/../quux\u201d is actually \u201c/bar/quux\u201d, not \u201c/quux\u201d as a naive\n removal of \u201c..\u201d components would give you.

    \n+

    Examples:

    \n+
      \n+
    • ex_path.c
      • \n+
    • ex_path_test.c
      • \n+
    \n

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

    \n \n \n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -79,170 +79,228 @@\n ALLEGRO_PATH *al_create_path(const char *str)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a path structure from a string. The last component, if it is followed by\n a directory separator and is neither \u201c.\u201d nor \u201c..\u201d, is treated as the last\n directory name in the path. Otherwise the last component is treated as the\n filename. The string may be NULL for an empty path.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bp_\ba_\bt_\bh_\b__\bf_\bo_\br_\b__\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bp_\ba_\bt_\bh\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b._\bc\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_p\bpa\bat\bth\bh_\b_f\bfo\bor\br_\b_d\bdi\bir\bre\bec\bct\bto\bor\bry\by *\b**\b**\b**\b**\b**\b*\n ALLEGRO_PATH *al_create_path_for_directory(const char *str)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This is the same as _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bp_\ba_\bt_\bh, but interprets the passed string as a\n directory path. The filename component of the returned path will always be\n empty.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bp_\ba_\bt_\bh, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bp_\ba_\bt_\bh\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_p\bpa\bat\bth\bh *\b**\b**\b**\b**\b**\b*\n void al_destroy_path(ALLEGRO_PATH *path)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Free a path structure. Does nothing if passed NULL.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bp_\ba_\bt_\bh, _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bp_\ba_\bt_\bh_\b__\bf_\bo_\br_\b__\bd_\bi_\br_\be_\bc_\bt_\bo_\br_\by\n+Examples:\n+ * _\be_\bx_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b._\bc\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b._\bc\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcl\blo\bon\bne\be_\b_p\bpa\bat\bth\bh *\b**\b**\b**\b**\b**\b*\n ALLEGRO_PATH *al_clone_path(const ALLEGRO_PATH *path)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Clones an ALLEGRO_PATH structure. Returns NULL on failure.\n See also: _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bp_\ba_\bt_\bh\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b._\bc\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_j\bjo\boi\bin\bn_\b_p\bpa\bat\bth\bhs\bs *\b**\b**\b**\b**\b**\b*\n bool al_join_paths(ALLEGRO_PATH *path, const ALLEGRO_PATH *tail)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Concatenate two path structures. The first path structure is modified. If\n \u2018tail\u2019 is an absolute path, this function does nothing.\n If \u2018tail\u2019 is a relative path, all of its directory components will be appended\n to \u2018path\u2019. tail\u2019s filename will also overwrite path\u2019s filename, even if it is\n just the empty string.\n Tail\u2019s drive is ignored.\n Returns true if \u2018tail\u2019 was a relative path and so concatenated to \u2018path\u2019,\n otherwise returns false.\n See also: _\ba_\bl_\b__\br_\be_\bb_\ba_\bs_\be_\b__\bp_\ba_\bt_\bh\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\beb\bba\bas\bse\be_\b_p\bpa\bat\bth\bh *\b**\b**\b**\b**\b**\b*\n bool al_rebase_path(const ALLEGRO_PATH *head, ALLEGRO_PATH *tail)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Concatenate two path structures, modifying the second path structure. If t\bta\bai\bil\bl\n is an absolute path, this function does nothing. Otherwise, the drive and path\n components in h\bhe\bea\bad\bd are inserted at the start of t\bta\bai\bil\bl.\n For example, if h\bhe\bea\bad\bd is \u201c/anchor/\u201d and t\bta\bai\bil\bl is \u201cdata/file.ext\u201d, then after the\n call t\bta\bai\bil\bl becomes \u201c/anchor/data/file.ext\u201d.\n See also: _\ba_\bl_\b__\bj_\bo_\bi_\bn_\b__\bp_\ba_\bt_\bh_\bs\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_p\bpa\bat\bth\bh_\b_d\bdr\bri\biv\bve\be *\b**\b**\b**\b**\b**\b*\n const char *al_get_path_drive(const ALLEGRO_PATH *path)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the drive letter on a path, or the empty string if there is none.\n The \u201cdrive letter\u201d is only used on Windows, and is usually a string like \u201cc:\u201d,\n but may be something like \u201c\\\\Computer Name\u201d in the case of UNC (Uniform Naming\n Convention) syntax.\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b._\bc\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_p\bpa\bat\bth\bh_\b_n\bnu\bum\bm_\b_c\bco\bom\bmp\bpo\bon\bne\ben\bnt\bts\bs *\b**\b**\b**\b**\b**\b*\n int al_get_path_num_components(const ALLEGRO_PATH *path)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the number of directory components in a path.\n The directory components do not include the final part of a path (the\n filename).\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\bc_\bo_\bm_\bp_\bo_\bn_\be_\bn_\bt\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b._\bc\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_p\bpa\bat\bth\bh_\b_c\bco\bom\bmp\bpo\bon\bne\ben\bnt\bt *\b**\b**\b**\b**\b**\b*\n const char *al_get_path_component(const ALLEGRO_PATH *path, int i)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the i\u2019th directory component of a path, counting from zero. If the index\n is negative then count from the right, i.e.\u00a0-1 refers to the last path\n component. It is an error to pass an index which is out of bounds.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\bn_\bu_\bm_\b__\bc_\bo_\bm_\bp_\bo_\bn_\be_\bn_\bt_\bs, _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\bt_\ba_\bi_\bl\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b._\bc\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_p\bpa\bat\bth\bh_\b_t\bta\bai\bil\bl *\b**\b**\b**\b**\b**\b*\n const char *al_get_path_tail(const ALLEGRO_PATH *path)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the last directory component, or NULL if there are no directory\n components.\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_p\bpa\bat\bth\bh_\b_f\bfi\bil\ble\ben\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n const char *al_get_path_filename(const ALLEGRO_PATH *path)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the filename part of the path, or the empty string if there is none.\n The returned pointer is valid only until the filename part of the path is\n modified in any way, or until the path is destroyed.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\bb_\ba_\bs_\be_\bn_\ba_\bm_\be, _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\be_\bx_\bt_\be_\bn_\bs_\bi_\bo_\bn, _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\bc_\bo_\bm_\bp_\bo_\bn_\be_\bn_\bt\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b._\bc\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_p\bpa\bat\bth\bh_\b_b\bba\bas\bse\ben\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n const char *al_get_path_basename(const ALLEGRO_PATH *path)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the basename, i.e.\u00a0filename with the extension removed. If the filename\n doesn\u2019t have an extension, the whole filename is the basename. If there is no\n filename part then the empty string is returned.\n The returned pointer is valid only until the filename part of the path is\n modified in any way, or until the path is destroyed.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\be_\bx_\bt_\be_\bn_\bs_\bi_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_p\bpa\bat\bth\bh_\b_e\bex\bxt\bte\ben\bns\bsi\bio\bon\bn *\b**\b**\b**\b**\b**\b*\n const char *al_get_path_extension(const ALLEGRO_PATH *path)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return a pointer to the start of the extension of the filename, i.e.\u00a0everything\n from the final dot (\u2018.\u2019) character onwards. If no dot exists, returns an empty\n string.\n The returned pointer is valid only until the filename part of the path is\n modified in any way, or until the path is destroyed.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\bb_\ba_\bs_\be_\bn_\ba_\bm_\be\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\bh_\by_\bs_\bf_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_p\bpa\bat\bth\bh_\b_d\bdr\bri\biv\bve\be *\b**\b**\b**\b**\b**\b*\n void al_set_path_drive(ALLEGRO_PATH *path, const char *drive)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the drive string on a path. The drive may be NULL, which is equivalent to\n setting the drive string to the empty string.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\bd_\br_\bi_\bv_\be\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_a\bap\bpp\bpe\ben\bnd\bd_\b_p\bpa\bat\bth\bh_\b_c\bco\bom\bmp\bpo\bon\bne\ben\bnt\bt *\b**\b**\b**\b**\b**\b*\n void al_append_path_component(ALLEGRO_PATH *path, const char *s)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Append a directory component.\n See also: _\ba_\bl_\b__\bi_\bn_\bs_\be_\br_\bt_\b__\bp_\ba_\bt_\bh_\b__\bc_\bo_\bm_\bp_\bo_\bn_\be_\bn_\bt\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bns\bse\ber\brt\bt_\b_p\bpa\bat\bth\bh_\b_c\bco\bom\bmp\bpo\bon\bne\ben\bnt\bt *\b**\b**\b**\b**\b**\b*\n void al_insert_path_component(ALLEGRO_PATH *path, int i, const char *s)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Insert a directory component at index i. If the index is negative then count\n from the right, i.e.\u00a0-1 refers to the last path component.\n It is an error to pass an index i which is not within these bounds: 0 <= i <=\n al_get_path_num_components(path).\n See also: _\ba_\bl_\b__\ba_\bp_\bp_\be_\bn_\bd_\b__\bp_\ba_\bt_\bh_\b__\bc_\bo_\bm_\bp_\bo_\bn_\be_\bn_\bt, _\ba_\bl_\b__\br_\be_\bp_\bl_\ba_\bc_\be_\b__\bp_\ba_\bt_\bh_\b__\bc_\bo_\bm_\bp_\bo_\bn_\be_\bn_\bt,\n _\ba_\bl_\b__\br_\be_\bm_\bo_\bv_\be_\b__\bp_\ba_\bt_\bh_\b__\bc_\bo_\bm_\bp_\bo_\bn_\be_\bn_\bt\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bep\bpl\bla\bac\bce\be_\b_p\bpa\bat\bth\bh_\b_c\bco\bom\bmp\bpo\bon\bne\ben\bnt\bt *\b**\b**\b**\b**\b**\b*\n void al_replace_path_component(ALLEGRO_PATH *path, int i, const char *s)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Replace the i\u2019th directory component by another string. If the index is\n negative then count from the right, i.e.\u00a0-1 refers to the last path component.\n It is an error to pass an index which is out of bounds.\n See also: _\ba_\bl_\b__\bi_\bn_\bs_\be_\br_\bt_\b__\bp_\ba_\bt_\bh_\b__\bc_\bo_\bm_\bp_\bo_\bn_\be_\bn_\bt, _\ba_\bl_\b__\br_\be_\bm_\bo_\bv_\be_\b__\bp_\ba_\bt_\bh_\b__\bc_\bo_\bm_\bp_\bo_\bn_\be_\bn_\bt\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bem\bmo\bov\bve\be_\b_p\bpa\bat\bth\bh_\b_c\bco\bom\bmp\bpo\bon\bne\ben\bnt\bt *\b**\b**\b**\b**\b**\b*\n void al_remove_path_component(ALLEGRO_PATH *path, int i)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Delete the i\u2019th directory component. If the index is negative then count from\n the right, i.e.\u00a0-1 refers to the last path component. It is an error to pass an\n index which is out of bounds.\n See also: _\ba_\bl_\b__\bi_\bn_\bs_\be_\br_\bt_\b__\bp_\ba_\bt_\bh_\b__\bc_\bo_\bm_\bp_\bo_\bn_\be_\bn_\bt, _\ba_\bl_\b__\br_\be_\bp_\bl_\ba_\bc_\be_\b__\bp_\ba_\bt_\bh_\b__\bc_\bo_\bm_\bp_\bo_\bn_\be_\bn_\bt,\n _\ba_\bl_\b__\bd_\br_\bo_\bp_\b__\bp_\ba_\bt_\bh_\b__\bt_\ba_\bi_\bl\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bro\bop\bp_\b_p\bpa\bat\bth\bh_\b_t\bta\bai\bil\bl *\b**\b**\b**\b**\b**\b*\n void al_drop_path_tail(ALLEGRO_PATH *path)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Remove the last directory component, if any.\n See also: _\ba_\bl_\b__\br_\be_\bm_\bo_\bv_\be_\b__\bp_\ba_\bt_\bh_\b__\bc_\bo_\bm_\bp_\bo_\bn_\be_\bn_\bt\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_p\bpa\bat\bth\bh_\b_f\bfi\bil\ble\ben\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n void al_set_path_filename(ALLEGRO_PATH *path, const char *filename)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the optional filename part of the path. The filename may be NULL, which is\n equivalent to setting the filename to the empty string.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\be_\bx_\bt_\be_\bn_\bs_\bi_\bo_\bn, _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\bf_\bi_\bl_\be_\bn_\ba_\bm_\be\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n+ * _\be_\bx_\b__\ba_\bn_\bd_\br_\bo_\bi_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_p\bpa\bat\bth\bh_\b_e\bex\bxt\bte\ben\bns\bsi\bio\bon\bn *\b**\b**\b**\b**\b**\b*\n bool al_set_path_extension(ALLEGRO_PATH *path, char const *extension)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Replaces the extension of the path with the given one, i.e.\u00a0replaces everything\n from the final dot (\u2018.\u2019) character onwards, including the dot. If the filename\n of the path has no extension, the given one is appended. Usually the new\n extension you supply should include a leading dot.\n Returns false if the path contains no filename part, i.e.\u00a0the filename part is\n the empty string.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, _\ba_\bl_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b__\be_\bx_\bt_\be_\bn_\bs_\bi_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_p\bpa\bat\bth\bh_\b_c\bcs\bst\btr\br *\b**\b**\b**\b**\b**\b*\n const char *al_path_cstr(const ALLEGRO_PATH *path, char delim)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert a path to its string representation, i.e.\u00a0optional drive, followed by\n directory components separated by \u2018delim\u2019, followed by an optional filename.\n To use the current native path separator, use ALLEGRO_NATIVE_PATH_SEP for\n \u2018delim\u2019.\n The returned pointer is valid only until the path is modified in any way, or\n until the path is destroyed. This returns a null-terminated string. If you need\n an ALLEGRO_USTR instead, use _\ba_\bl_\b__\bp_\ba_\bt_\bh_\b__\bu_\bs_\bt_\br.\n See also: _\ba_\bl_\b__\bp_\ba_\bt_\bh_\b__\bu_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b._\bc\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b._\bc\n+ * _\be_\bx_\b__\bf_\bi_\bl_\be_\b__\bs_\bl_\bi_\bc_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_p\bpa\bat\bth\bh_\b_u\bus\bst\btr\br *\b**\b**\b**\b**\b**\b*\n const ALLEGRO_USTR *al_path_ustr(const ALLEGRO_PATH *path, char delim)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert a path to its string representation, i.e.\u00a0optional drive, followed by\n directory components separated by \u2018delim\u2019, followed by an optional filename.\n To use the current native path separator, use ALLEGRO_NATIVE_PATH_SEP for\n \u2018delim\u2019.\n@@ -256,8 +314,11 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Removes any leading \u2018..\u2019 directory components in absolute paths. Removes all\n \u2018.\u2019 directory components.\n Note that this does n\bno\bot\bt collapse \u201cx/../y\u201d sections into \u201cy\u201d. This is by design.\n If \u201c/foo\u201d on your system is a symlink to \u201c/bar/baz\u201d, then \u201c/foo/../quux\u201d is\n actually \u201c/bar/quux\u201d, not \u201c/quux\u201d as a naive removal of \u201c..\u201d components would\n give you.\n+Examples:\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b._\bc\n+ * _\be_\bx_\b__\bp_\ba_\bt_\bh_\b__\bt_\be_\bs_\bt_\b._\bc\n Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/physfs.html", "source2": "./usr/share/doc/allegro5-doc/refman/physfs.html", "unified_diff": "@@ -224,19 +224,27 @@\n
    \n

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

    \n
    \n

    See also: al_set_new_file_interface.

    \n+

    Examples:

    \n+
      \n+
    • ex_physfs.c
      • \n+
    \n al_get_allegro_physfs_version\n 
    uint32_t al_get_allegro_physfs_version(void)
    \n

    Source\n Code

    \n

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

    \n-\n+

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

    \n \n \n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -70,12 +70,15 @@\n _\ba_\bl_\b__\br_\be_\bs_\bt_\bo_\br_\be_\b__\bs_\bt_\ba_\bt_\be.\n N\bNo\bot\bte\be:\b: due to an oversight, this function differs from\n _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bf_\bi_\bl_\be_\b__\bi_\bn_\bt_\be_\br_\bf_\ba_\bc_\be and _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd_\b__\bf_\bi_\bl_\be_\b__\bi_\bn_\bt_\be_\br_\bf_\ba_\bc_\be which\n only alter the current _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bF_\bI_\bL_\bE_\b__\bI_\bN_\bT_\bE_\bR_\bF_\bA_\bC_\bE.\n N\bNo\bot\bte\be:\b: PhysFS does not support the text-mode reading and writing,\n which means that Windows-style newlines will not be preserved.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bn_\be_\bw_\b__\bf_\bi_\bl_\be_\b__\bi_\bn_\bt_\be_\br_\bf_\ba_\bc_\be.\n+Examples:\n+ * _\be_\bx_\b__\bp_\bh_\by_\bs_\bf_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bal\bll\ble\beg\bgr\bro\bo_\b_p\bph\bhy\bys\bsf\bfs\bs_\b_v\bve\ber\brs\bsi\bio\bon\bn *\b**\b**\b**\b**\b**\b*\n uint32_t al_get_allegro_physfs_version(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the (compiled) version of the addon, in the same format as\n _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bl_\bl_\be_\bg_\br_\bo_\b__\bv_\be_\br_\bs_\bi_\bo_\bn.\n+Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/platform.html", "source2": "./usr/share/doc/allegro5-doc/refman/platform.html", "unified_diff": "@@ -226,14 +226,19 @@\n

    al_get_win_window_handle

    \n 
    HWND al_get_win_window_handle(ALLEGRO_DISPLAY *display)
    \n

    Source\n Code

    \n

    Returns the handle to the window that the passed display is\n using.

    \n+

    Examples:

    \n+
      \n+
    • ex_ogre3d.cpp
      • \n+
    \n

    al_win_add_window_callback

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

    Source\n Code

    \n@@ -326,17 +331,17 @@\n \n

    Since: 5.1.2

    \n

    Examples:

    \n
      \n
    • common.c
      • \n
    • ex_native_filechooser.c
      • \n-
    • ex_android.c
      • \n+
    • ex_native_filechooser.c
      • \n
    \n al_android_set_apk_fs_interface\n 
    void al_android_set_apk_fs_interface(void)
    \n

    Source\n Code

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

    \n

    Since: 5.2.3

    \n
    \n

    Unstable\n API: New API.

    \n
    \n+

    Examples:

    \n+
      \n+
    • ex_icon2.c
      • \n+
    \n

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

    \n \n \n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -66,14 +66,16 @@\n *\b**\b**\b**\b**\b**\b* W\bWi\bin\bnd\bdo\bow\bws\bs *\b**\b**\b**\b**\b**\b*\n These functions are declared in the following header file:\n #include \n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_w\bwi\bin\bn_\b_w\bwi\bin\bnd\bdo\bow\bw_\b_h\bha\ban\bnd\bdl\ble\be *\b**\b**\b**\b**\b*\n HWND al_get_win_window_handle(ALLEGRO_DISPLAY *display)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the handle to the window that the passed display is using.\n+Examples:\n+ * _\be_\bx_\b__\bo_\bg_\br_\be_\b3_\bd_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_w\bwi\bin\bn_\b_a\bad\bdd\bd_\b_w\bwi\bin\bnd\bdo\bow\bw_\b_c\bca\bal\bll\blb\bba\bac\bck\bk *\b**\b**\b**\b**\b*\n bool al_win_add_window_callback(ALLEGRO_DISPLAY *display,\n bool (*callback)(ALLEGRO_DISPLAY *display, UINT message, WPARAM wparam,\n LPARAM lparam, LRESULT *result, void *userdata), void *userdata)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n The specified callback function will intercept the window\u2019s message before\n Allegro processes it. If the callback function consumes the event, then it\n@@ -134,16 +136,16 @@\n This function will set up a custom _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bF_\bI_\bL_\bE_\b__\bI_\bN_\bT_\bE_\bR_\bF_\bA_\bC_\bE that makes all future\n calls of _\ba_\bl_\b__\bf_\bo_\bp_\be_\bn read from the applicatons\u2019s APK file.\n N\bNo\bot\bte\be:\b: Currently, access to the APK file after calling this function\n is read only.\n Since: 5.1.2\n Examples:\n * _\bc_\bo_\bm_\bm_\bo_\bn_\b._\bc\n- * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n * _\be_\bx_\b__\ba_\bn_\bd_\br_\bo_\bi_\bd_\b._\bc\n+ * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_a\ban\bnd\bdr\bro\boi\bid\bd_\b_s\bse\bet\bt_\b_a\bap\bpk\bk_\b_f\bfs\bs_\b_i\bin\bnt\bte\ber\brf\bfa\bac\bce\be *\b**\b**\b**\b**\b*\n void al_android_set_apk_fs_interface(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This function will set up a custom _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bF_\bS_\b__\bI_\bN_\bT_\bE_\bR_\bF_\bA_\bC_\bE which allows working\n within the APK filesystem. The filesystem root is your assets directory and\n there is read-only access to all files within.\n N\bNo\bot\bte\be:\b: Some things like querying file size or attributes are not\n@@ -232,8 +234,10 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n On some window managers (notably Ubuntu\u2019s Unity) al_set_display_icon doesn\u2019t\n work and you need to use a .desktop file. But with this function you can set an\n icon before calling al_create_display. This works by setting the icon before\n XMapWindow.\n Since: 5.2.3\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: New API.\n+Examples:\n+ * _\be_\bx_\b__\bi_\bc_\bo_\bn_\b2_\b._\bc\n Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/primitives.html", "source2": "./usr/share/doc/allegro5-doc/refman/primitives.html", "unified_diff": "@@ -343,14 +343,23 @@\n

    Source\n Code

    \n

    Initializes the primitives addon.

    \n

    Returns: True on success, false on failure.

    \n

    See also: al_shutdown_primitives_addon

    \n+

    Examples:

    \n+
      \n+
    • ex_touch_input.c
      • \n+
    • ex_blend_bench.c
      • \n+
    • ex_enet_client.c
      • \n+
    \n al_is_primitives_addon_initialized\n 
    bool al_is_primitives_addon_initialized(void)
    \n

    Source\n Code

    \n

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

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

    See also: al_draw_soft_line

    \n+

    Examples:

    \n+
      \n+
    • ex_font_justify.cpp
      • \n+
    • ex_resize.c
      • \n+
    • ex_mouse_warp.c
      • \n+
    \n

    al_draw_triangle

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

    Source\n Code

    \n

    Draws an outlined triangle.

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

    See also: al_draw_filled_triangle,\n al_draw_soft_triangle

    \n+

    Examples:

    \n+
      \n+
    • ex_prim.c
      • \n+
    \n

    al_draw_filled_triangle

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

    Source\n Code

    \n

    Draws a filled triangle.

    \n

    Parameters:

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

    See also: al_draw_triangle

    \n+

    Examples:

    \n+
      \n+
    • ex_prim.c
      • \n+
    \n

    al_draw_rectangle

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

    Source\n Code

    \n

    Draws an outlined rectangle.

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

    See also: al_draw_filled_rectangle,\n al_draw_rounded_rectangle

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse.c
      • \n+
    • ex_font_justify.cpp
      • \n+
    • ex_subbitmap.c
      • \n+
    \n

    al_draw_filled_rectangle

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

    Source\n Code

    \n

    Draws a filled rectangle.

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

    See also: al_draw_rectangle, al_draw_filled_rounded_rectangle

    \n+

    Examples:

    \n+
      \n+
    • ex_mouse.c
      • \n+
    • ex_timer.c
      • \n+
    • ex_window_maximized.c
      • \n+
    \n

    al_draw_rounded_rectangle

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

    Source\n Code

    \n

    Draws an outlined rounded rectangle.

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

    See also: al_draw_filled_rounded_rectangle,\n al_draw_rectangle

    \n+

    Examples:

    \n+
      \n+
    • ex_threads.c
      • \n+
    • ex_prim.c
      • \n+
    • ex_audio_chain.cpp
      • \n+
    \n al_draw_filled_rounded_rectangle\n 
    void al_draw_filled_rounded_rectangle(float x1, float y1, float x2, float y2,\n    float rx, float ry, ALLEGRO_COLOR color)
    \n

    Source\n Code

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

    See also: al_draw_rounded_rectangle,\n al_draw_filled_rectangle

    \n+

    Examples:

    \n+
      \n+
    • ex_threads.c
      • \n+
    • ex_video.c
      • \n+
    • ex_prim.c
      • \n+
    \n

    al_calculate_arc

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

    Source\n Code

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

    See also: al_draw_arc, al_calculate_spline, al_calculate_ribbon

    \n+

    Examples:

    \n+
      \n+
    • ex_vertex_buffer.c
      • \n+
    \n

    al_draw_pieslice

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

    Source\n Code

    \n

    Draws a pieslice (outlined circular sector).

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

    Since: 5.0.6, 5.1.0

    \n

    See also: al_draw_filled_pieslice

    \n+

    Examples:

    \n+
      \n+
    • ex_prim.c
      • \n+
    \n

    al_draw_filled_pieslice

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

    Source\n Code

    \n

    Draws a filled pieslice (filled circular sector).

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

    Since: 5.0.6, 5.1.0

    \n

    See also: al_draw_pieslice

    \n+

    Examples:

    \n+
      \n+
    • ex_prim.c
      • \n+
    \n

    al_draw_ellipse

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

    Source\n Code

    \n

    Draws an outlined ellipse.

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

    See also: al_draw_filled_ellipse,\n al_draw_circle

    \n+

    Examples:

    \n+
      \n+
    • ex_draw.c
      • \n+
    • ex_prim.c
      • \n+
    \n

    al_draw_filled_ellipse

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

    Source\n Code

    \n

    Draws a filled ellipse.

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

    See also: al_draw_ellipse, al_draw_filled_circle

    \n+

    Examples:

    \n+
      \n+
    • ex_draw.c
      • \n+
    • ex_prim.c
      • \n+
    \n

    al_draw_circle

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

    Source\n Code

    \n

    Draws an outlined circle.

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

    See also: al_draw_filled_circle,\n al_draw_ellipse

    \n+

    Examples:

    \n+
      \n+
    • ex_touch_input.c
      • \n+
    • ex_transform.c
      • \n+
    \n

    al_draw_filled_circle

    \n 
    void al_draw_filled_circle(float cx, float cy, float r, ALLEGRO_COLOR color)
    \n

    Source\n Code

    \n

    Draws a filled circle.

    \n

    Parameters:

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

    See also: al_draw_circle, al_draw_filled_ellipse

    \n+

    Examples:

    \n+
      \n+
    • ex_enet_client.c
      • \n+
    • ex_joystick_hotplugging.c
      • \n+
    • ex_blend2.cpp
      • \n+
    \n

    al_draw_arc

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

    Source\n Code

    \n

    Draws an arc.

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

    See also: al_calculate_arc, al_draw_elliptical_arc

    \n+

    Examples:

    \n+
      \n+
    • ex_prim.c
      • \n+
    \n

    al_draw_elliptical_arc

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

    Source\n Code

    \n

    Draws an elliptical arc.

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

    Since: 5.0.6, 5.1.0

    \n

    See also: al_calculate_arc, al_draw_arc

    \n+

    Examples:

    \n+
      \n+
    • ex_prim.c
      • \n+
    \n

    al_calculate_spline

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

    Source\n Code

    \n

    Calculates a B\u00e9zier spline given 4 control points. If\n@@ -843,14 +962,19 @@\n points\n

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

    See also: al_calculate_spline

    \n+

    Examples:

    \n+
      \n+
    • ex_prim.c
      • \n+
    \n

    al_calculate_ribbon

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

    Source\n Code

    \n

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

    See also: ALLEGRO_VERTEX, ALLEGRO_PRIM_TYPE, ALLEGRO_VERTEX_DECL, al_draw_indexed_prim

    \n+

    Examples:

    \n+
      \n+
    • ex_prim_shader.c
      • \n+
    • ex_vertex_buffer.c
      • \n+
    • ex_prim_wrap.c
      • \n+
    \n

    al_draw_indexed_prim

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

    Source\n Code

    \n

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

    Returns: Number of primitives drawn

    \n

    See also: ALLEGRO_VERTEX, ALLEGRO_PRIM_TYPE, ALLEGRO_VERTEX_DECL, al_draw_prim

    \n+

    Examples:

    \n+
      \n+
    • ex_projection2.c
      • \n+
    • ex_prim.c
      • \n+
    \n

    al_draw_vertex_buffer

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

    Source\n Code

    \n

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

    Returns: Number of primitives drawn

    \n

    Since: 5.1.3

    \n

    See also: ALLEGRO_VERTEX_BUFFER,\n ALLEGRO_PRIM_TYPE

    \n+

    Examples:

    \n+
      \n+
    • ex_vertex_buffer.c
      • \n+
    • ex_prim.c
      • \n+
    \n

    al_draw_indexed_buffer

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

    Source\n Code

    \n@@ -1041,14 +1188,19 @@\n \n

    Returns: Number of primitives drawn

    \n

    Since: 5.1.8

    \n

    See also: ALLEGRO_VERTEX_BUFFER,\n ALLEGRO_INDEX_BUFFER,\n ALLEGRO_PRIM_TYPE

    \n+

    Examples:

    \n+
      \n+
    • ex_prim.c
      • \n+
    \n

    al_draw_soft_triangle

    \n 
    void al_draw_soft_triangle(\n    ALLEGRO_VERTEX* v1, ALLEGRO_VERTEX* v2, ALLEGRO_VERTEX* v3, uintptr_t state,\n    void (*init)(uintptr_t, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*),\n    void (*first)(uintptr_t, int, int, int, int),\n    void (*step)(uintptr_t, int),\n    void (*draw)(uintptr_t, int, int, int))
    \n@@ -1133,14 +1285,21 @@\n \n

    Returns: Newly created vertex declaration.

    \n

    See also: ALLEGRO_VERTEX_ELEMENT,\n ALLEGRO_VERTEX_DECL,\n al_destroy_vertex_decl

    \n+

    Examples:

    \n+
      \n+
    • ex_prim_shader.c
      • \n+
    • ex_prim.c
      • \n+
    \n

    al_destroy_vertex_decl

    \n 
    void al_destroy_vertex_decl(ALLEGRO_VERTEX_DECL* decl)
    \n

    Source\n Code

    \n

    Destroys a vertex declaration.

    \n

    Parameters:

    \n@@ -1148,14 +1307,19 @@\n
  • decl - Vertex declaration to destroy
    • \n \n

    See also: ALLEGRO_VERTEX_ELEMENT,\n ALLEGRO_VERTEX_DECL,\n al_create_vertex_decl

    \n+

    Examples:

    \n+
      \n+
    • ex_prim_shader.c
      • \n+
    \n

    Vertex buffer routines

    \n

    al_create_vertex_buffer

    \n 
    ALLEGRO_VERTEX_BUFFER* al_create_vertex_buffer(ALLEGRO_VERTEX_DECL* decl,\n    const void* initial_data, int num_vertices, int flags)
    \n

    Source\n Code

    \n@@ -1183,25 +1347,39 @@\n as passing ALLEGRO_PRIM_BUFFER_STATIC.\n \n

    Since: 5.1.3

    \n

    See also: ALLEGRO_VERTEX_BUFFER,\n al_destroy_vertex_buffer

    \n+

    Examples:

    \n+
      \n+
    • ex_vertex_buffer.c
      • \n+
    • ex_prim.c
      • \n+
    \n

    al_destroy_vertex_buffer

    \n 
    void al_destroy_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer)
    \n

    Source\n Code

    \n

    Destroys a vertex buffer. Does nothing if passed NULL.

    \n

    Since: 5.1.3

    \n

    See also: ALLEGRO_VERTEX_BUFFER,\n al_create_vertex_buffer

    \n+

    Examples:

    \n+
      \n+
    • ex_vertex_buffer.c
      • \n+
    • ex_prim.c
      • \n+
    \n

    al_lock_vertex_buffer

    \n 
    void* al_lock_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer, int offset,\n    int length, int flags)
    \n

    Source\n Code

    \n

    Locks a vertex buffer so you can access its data. Will return NULL if\n@@ -1216,25 +1394,39 @@\n ALLEGRO_LOCK_READWRITE\n \n

    Since: 5.1.3

    \n

    See also: ALLEGRO_VERTEX_BUFFER,\n al_unlock_vertex_buffer

    \n+

    Examples:

    \n+
      \n+
    • ex_vertex_buffer.c
      • \n+
    • ex_prim.c
      • \n+
    \n

    al_unlock_vertex_buffer

    \n 
    void al_unlock_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer)
    \n

    Source\n Code

    \n

    Unlocks a previously locked vertex buffer.

    \n

    Since: 5.1.3

    \n

    See also: ALLEGRO_VERTEX_BUFFER,\n al_lock_vertex_buffer

    \n+

    Examples:

    \n+
      \n+
    • ex_vertex_buffer.c
      • \n+
    • ex_prim.c
      • \n+
    \n

    al_get_vertex_buffer_size

    \n 
    int al_get_vertex_buffer_size(ALLEGRO_VERTEX_BUFFER* buffer)
    \n

    Source\n Code

    \n

    Returns the size of the vertex buffer

    \n

    Since: 5.1.8

    \n@@ -1269,24 +1461,34 @@\n flags specifying how this buffer will be created. Passing 0 is the same\n as passing ALLEGRO_PRIM_BUFFER_STATIC.\n \n

    Since: 5.1.8

    \n

    See also: ALLEGRO_INDEX_BUFFER, al_destroy_index_buffer

    \n+

    Examples:

    \n+
      \n+
    • ex_prim.c
      • \n+
    \n

    al_destroy_index_buffer

    \n 
    void al_destroy_index_buffer(ALLEGRO_INDEX_BUFFER* buffer)
    \n

    Source\n Code

    \n

    Destroys a index buffer. Does nothing if passed NULL.

    \n

    Since: 5.1.8

    \n

    See also: ALLEGRO_INDEX_BUFFER, al_create_index_buffer

    \n+

    Examples:

    \n+
      \n+
    • ex_prim.c
      • \n+
    \n

    al_lock_index_buffer

    \n 
    void* al_lock_index_buffer(ALLEGRO_INDEX_BUFFER* buffer, int offset,\n     int length, int flags)
    \n

    Source\n Code

    \n

    Locks a index buffer so you can access its data. Will return NULL if\n@@ -1300,24 +1502,34 @@\n

  • flags - ALLEGRO_LOCK_READONLY, ALLEGRO_LOCK_WRITEONLY or\n ALLEGRO_LOCK_READWRITE
    • \n \n

    Since: 5.1.8

    \n

    See also: ALLEGRO_INDEX_BUFFER, al_unlock_index_buffer

    \n+

    Examples:

    \n+
      \n+
    • ex_prim.c
      • \n+
    \n

    al_unlock_index_buffer

    \n 
    void al_unlock_index_buffer(ALLEGRO_INDEX_BUFFER* buffer)
    \n

    Source\n Code

    \n

    Unlocks a previously locked index buffer.

    \n

    Since: 5.1.8

    \n

    See also: ALLEGRO_INDEX_BUFFER, al_lock_index_buffer

    \n+

    Examples:

    \n+
      \n+
    • ex_prim.c
      • \n+
    \n

    al_get_index_buffer_size

    \n 
    int al_get_index_buffer_size(ALLEGRO_INDEX_BUFFER* buffer)
    \n

    Source\n Code

    \n

    Returns the size of the index buffer

    \n

    Since: 5.1.8

    \n@@ -1365,14 +1577,19 @@\n

    The stride may also be negative if the vertices are stored in reverse\n order.

    \n

    Since: 5.1.0

    \n

    See also: al_draw_polygon, ALLEGRO_LINE_JOIN, ALLEGRO_LINE_CAP

    \n+

    Examples:

    \n+
      \n+
    • ex_polygon.c
      • \n+
    \n

    al_draw_polygon

    \n 
    void al_draw_polygon(const float *vertices, int vertex_count,\n    int join_style, ALLEGRO_COLOR color, float thickness, float miter_limit)
    \n

    Source\n Code

    \n

    Draw an unfilled polygon. This is the same as passing\n@@ -1390,14 +1607,19 @@\n

  • miter_limit - Parameter for miter join style
    • \n \n

    Since: 5.1.0

    \n

    See also: al_draw_filled_polygon,\n al_draw_polyline, ALLEGRO_LINE_JOIN

    \n+

    Examples:

    \n+
      \n+
    • ex_polygon.c
      • \n+
    \n

    al_draw_filled_polygon

    \n 
    void al_draw_filled_polygon(const float *vertices, int vertex_count,\n    ALLEGRO_COLOR color)
    \n

    Source\n Code

    \n

    Draw a filled, simple polygon. Simple means it does not have to be\n@@ -1409,14 +1631,19 @@\n \n

    When the y-axis is facing downwards (the usual), the coordinates must\n be ordered anti-clockwise.

    \n

    Since: 5.1.0

    \n

    See also: al_draw_polygon, al_draw_filled_polygon_with_holes

    \n+

    Examples:

    \n+
      \n+
    • ex_polygon.c
      • \n+
    \n al_draw_filled_polygon_with_holes\n 
    void al_draw_filled_polygon_with_holes(const float *vertices,\n    const int *vertex_counts, ALLEGRO_COLOR color)
    \n

    Source\n Code

    \n@@ -1459,14 +1686,19 @@\n

    Since: 5.1.0

    \n

    See also: al_draw_filled_polygon,\n al_draw_filled_polygon_with_holes,\n al_triangulate_polygon

    \n+

    Examples:

    \n+
      \n+
    • ex_polygon.c
      • \n+
    \n

    al_triangulate_polygon

    \n 
    bool al_triangulate_polygon(\n    const float* vertices, size_t vertex_stride, const int* vertex_counts,\n    void (*emit_triangle)(int, int, int, void*), void* userdata)
    \n

    Source\n Code

    \n@@ -1510,28 +1742,44 @@\n
  • x, y, z - Position of the vertex (float)
    • \n
  • u, v - Texture coordinates measured in pixels (float)
    • \n
  • color - ALLEGRO_COLOR\n structure, storing the color of the vertex
    • \n \n

    See also: ALLEGRO_PRIM_ATTR

    \n+

    Examples:

    \n+
      \n+
    • ex_shader.cpp
      • \n+
    • ex_shader_target.c
      • \n+
    • ex_prim_shader.c
      • \n+
    \n

    ALLEGRO_VERTEX_DECL

    \n 
    typedef struct ALLEGRO_VERTEX_DECL ALLEGRO_VERTEX_DECL;
    \n

    Source\n Code

    \n

    A vertex declaration. This opaque structure is responsible for\n describing the format and layout of a user defined custom vertex. It is\n created and destroyed by specialized functions.

    \n

    See also: al_create_vertex_decl,\n al_destroy_vertex_decl,\n ALLEGRO_VERTEX_ELEMENT

    \n+

    Examples:

    \n+
      \n+
    • ex_prim_shader.c
      • \n+
    • ex_prim.c
      • \n+
    \n

    ALLEGRO_VERTEX_ELEMENT

    \n 
    typedef struct ALLEGRO_VERTEX_ELEMENT ALLEGRO_VERTEX_ELEMENT;
    \n

    Source\n Code

    \n

    A small structure describing a certain element of a vertex. E.g. the\n position of the vertex, or its color. These structures are used by the\n@@ -1566,14 +1814,21 @@\n structure. The C function offsetof is very useful here.\n \n

    See also: al_create_vertex_decl,\n ALLEGRO_VERTEX_DECL,\n ALLEGRO_PRIM_ATTR, ALLEGRO_PRIM_STORAGE

    \n+

    Examples:

    \n+
      \n+
    • ex_prim_shader.c
      • \n+
    • ex_prim.c
      • \n+
    \n

    ALLEGRO_PRIM_TYPE

    \n 
    typedef enum ALLEGRO_PRIM_TYPE
    \n

    Source\n Code

    \n

    Enumerates the types of primitives this addon can draw.

    \n
      \n@@ -1748,14 +2003,19 @@\n \n

      See the picture for the difference.

      \n

      The maximum miter length (relative to the line width) can be\n specified as parameter to the polygon functions.

      \n

      Since: 5.1.0

      \n

      See also: al_draw_polygon

      \n+

      Examples:

      \n+
        \n+
      • ex_polygon.c
        • \n+
      \n

      ALLEGRO_LINE_CAP

      \n 
      typedef enum ALLEGRO_LINE_CAP
      \n

      Source\n Code

      \n
        \n
      • ALLEGRO_LINE_CAP_NONE
        • \n@@ -1773,39 +2033,56 @@\n

        ALLEGRO_LINE_CAP_CLOSED is different from the others - it causes the\n polygon to have no caps. (And the ALLEGRO_LINE_JOIN style\n will determine how the vertex looks.)

        \n

        Since: 5.1.0

        \n

        See also: al_draw_polygon

        \n+

        Examples:

        \n+
          \n+
        • ex_polygon.c
          • \n+
        \n

        ALLEGRO_VERTEX_BUFFER

        \n 
        typedef struct ALLEGRO_VERTEX_BUFFER ALLEGRO_VERTEX_BUFFER;
        \n

        Source\n Code

        \n

        A GPU vertex buffer that you can use to store vertices on the GPU\n instead of uploading them afresh during every drawing operation.

        \n

        Since: 5.1.3

        \n

        See also: al_create_vertex_buffer,\n al_destroy_vertex_buffer

        \n+

        Examples:

        \n+
          \n+
        • ex_vertex_buffer.c
          • \n+
        • ex_prim.c
          • \n+
        \n

        ALLEGRO_INDEX_BUFFER

        \n 
        typedef struct ALLEGRO_INDEX_BUFFER ALLEGRO_INDEX_BUFFER;
        \n

        Source\n Code

        \n

        A GPU index buffer that you can use to store indices of vertices in a\n vertex buffer on the GPU instead of uploading them afresh during every\n drawing operation.

        \n

        Since: 5.1.8

        \n

        See also: al_create_index_buffer,\n al_destroy_index_buffer

        \n+

        Examples:

        \n+
          \n+
        • ex_prim.c
          • \n+
        \n

        ALLEGRO_PRIM_BUFFER_FLAGS

        \n 
        typedef enum ALLEGRO_PRIM_BUFFER_FLAGS
        \n

        Source\n Code

        \n

        Flags to specify how to create a vertex or an index buffer.

        \n
          \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -123,14 +123,18 @@\n _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bl_\bl_\be_\bg_\br_\bo_\b__\bv_\be_\br_\bs_\bi_\bo_\bn.\n *\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bni\bit\bt_\b_p\bpr\bri\bim\bmi\bit\bti\biv\bve\bes\bs_\b_a\bad\bdd\bdo\bon\bn *\b**\b**\b**\b**\b*\n bool al_init_primitives_addon(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Initializes the primitives addon.\n R\bRe\bet\btu\bur\brn\bns\bs:\b: True on success, false on failure.\n See also: _\ba_\bl_\b__\bs_\bh_\bu_\bt_\bd_\bo_\bw_\bn_\b__\bp_\br_\bi_\bm_\bi_\bt_\bi_\bv_\be_\bs_\b__\ba_\bd_\bd_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\bt_\bo_\bu_\bc_\bh_\b__\bi_\bn_\bp_\bu_\bt_\b._\bc\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bb_\be_\bn_\bc_\bh_\b._\bc\n+ * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bc_\bl_\bi_\be_\bn_\bt_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_p\bpr\bri\bim\bmi\bit\bti\biv\bve\bes\bs_\b_a\bad\bdd\bdo\bon\bn_\b_i\bin\bni\bit\bti\bia\bal\bli\biz\bze\bed\bd *\b**\b**\b**\b**\b*\n bool al_is_primitives_addon_initialized(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if the primitives addon is initialized, otherwise returns false.\n Since: 5.2.6\n See also: _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bp_\br_\bi_\bm_\bi_\bt_\bi_\bv_\be_\bs_\b__\ba_\bd_\bd_\bo_\bn, _\ba_\bl_\b__\bs_\bh_\bu_\bt_\bd_\bo_\bw_\bn_\b__\bp_\br_\bi_\bm_\bi_\bt_\bi_\bv_\be_\bs_\b__\ba_\bd_\bd_\bo_\bn\n *\b**\b**\b**\b**\b* a\bal\bl_\b_s\bsh\bhu\but\btd\bdo\bow\bwn\bn_\b_p\bpr\bri\bim\bmi\bit\bti\biv\bve\bes\bs_\b_a\bad\bdd\bdo\bon\bn *\b**\b**\b**\b**\b*\n@@ -225,73 +229,97 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a line segment between two points.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * x1, y1, x2, y2 - Start and end points of the line\n * color - Color of the line\n * thickness - Thickness of the line, pass <= 0 to draw hairline lines\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bs_\bo_\bf_\bt_\b__\bl_\bi_\bn_\be\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bj_\bu_\bs_\bt_\bi_\bf_\by_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\br_\be_\bs_\bi_\bz_\be_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bw_\ba_\br_\bp_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_t\btr\bri\bia\ban\bng\bgl\ble\be *\b**\b**\b**\b**\b*\n void al_draw_triangle(float x1, float y1, float x2, float y2,\n float x3, float y3, ALLEGRO_COLOR color, float thickness)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws an outlined triangle.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * x1, y1, x2, y2, x3, y3 - Three points of the triangle\n * color - Color of the triangle\n * thickness - Thickness of the lines, pass <= 0 to draw hairline lines\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bf_\bi_\bl_\bl_\be_\bd_\b__\bt_\br_\bi_\ba_\bn_\bg_\bl_\be, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bs_\bo_\bf_\bt_\b__\bt_\br_\bi_\ba_\bn_\bg_\bl_\be\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_f\bfi\bil\bll\ble\bed\bd_\b_t\btr\bri\bia\ban\bng\bgl\ble\be *\b**\b**\b**\b**\b*\n void al_draw_filled_triangle(float x1, float y1, float x2, float y2,\n float x3, float y3, ALLEGRO_COLOR color)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a filled triangle.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * x1, y1, x2, y2, x3, y3 - Three points of the triangle\n * color - Color of the triangle\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bt_\br_\bi_\ba_\bn_\bg_\bl_\be\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_r\bre\bec\bct\bta\ban\bng\bgl\ble\be *\b**\b**\b**\b**\b*\n void al_draw_rectangle(float x1, float y1, float x2, float y2,\n ALLEGRO_COLOR color, float thickness)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws an outlined rectangle.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * x1, y1, x2, y2 - Upper left and lower right points of the rectangle\n * color - Color of the rectangle\n * thickness - Thickness of the lines, pass <= 0 to draw hairline lines\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bf_\bi_\bl_\bl_\be_\bd_\b__\br_\be_\bc_\bt_\ba_\bn_\bg_\bl_\be, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\br_\bo_\bu_\bn_\bd_\be_\bd_\b__\br_\be_\bc_\bt_\ba_\bn_\bg_\bl_\be\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b._\bc\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bj_\bu_\bs_\bt_\bi_\bf_\by_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bu_\bb_\bb_\bi_\bt_\bm_\ba_\bp_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_f\bfi\bil\bll\ble\bed\bd_\b_r\bre\bec\bct\bta\ban\bng\bgl\ble\be *\b**\b**\b**\b**\b*\n void al_draw_filled_rectangle(float x1, float y1, float x2, float y2,\n ALLEGRO_COLOR color)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a filled rectangle.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * x1, y1, x2, y2 - Upper left and lower right points of the rectangle\n * color - Color of the rectangle\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\br_\be_\bc_\bt_\ba_\bn_\bg_\bl_\be, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bf_\bi_\bl_\bl_\be_\bd_\b__\br_\bo_\bu_\bn_\bd_\be_\bd_\b__\br_\be_\bc_\bt_\ba_\bn_\bg_\bl_\be\n+Examples:\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bw_\bi_\bn_\bd_\bo_\bw_\b__\bm_\ba_\bx_\bi_\bm_\bi_\bz_\be_\bd_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_r\bro\bou\bun\bnd\bde\bed\bd_\b_r\bre\bec\bct\bta\ban\bng\bgl\ble\be *\b**\b**\b**\b**\b*\n void al_draw_rounded_rectangle(float x1, float y1, float x2, float y2,\n float rx, float ry, ALLEGRO_COLOR color, float thickness)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws an outlined rounded rectangle.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * x1, y1, x2, y2 - Upper left and lower right points of the rectangle\n * color - Color of the rectangle\n * rx, ry - The radii of the round\n * thickness - Thickness of the lines, pass <= 0 to draw hairline lines\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bf_\bi_\bl_\bl_\be_\bd_\b__\br_\bo_\bu_\bn_\bd_\be_\bd_\b__\br_\be_\bc_\bt_\ba_\bn_\bg_\bl_\be, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\br_\be_\bc_\bt_\ba_\bn_\bg_\bl_\be\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bc_\bh_\ba_\bi_\bn_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_f\bfi\bil\bll\ble\bed\bd_\b_r\bro\bou\bun\bnd\bde\bed\bd_\b_r\bre\bec\bct\bta\ban\bng\bgl\ble\be *\b**\b**\b**\b**\b*\n void al_draw_filled_rounded_rectangle(float x1, float y1, float x2, float y2,\n float rx, float ry, ALLEGRO_COLOR color)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws an filled rounded rectangle.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * x1, y1, x2, y2 - Upper left and lower right points of the rectangle\n * color - Color of the rectangle\n * rx, ry - The radii of the round\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\br_\bo_\bu_\bn_\bd_\be_\bd_\b__\br_\be_\bc_\bt_\ba_\bn_\bg_\bl_\be, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bf_\bi_\bl_\bl_\be_\bd_\b__\br_\be_\bc_\bt_\ba_\bn_\bg_\bl_\be\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b._\bc\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bca\bal\blc\bcu\bul\bla\bat\bte\be_\b_a\bar\brc\bc *\b**\b**\b**\b**\b*\n void al_calculate_arc(float* dest, int stride, float cx, float cy,\n float rx, float ry, float start_theta, float delta_theta, float thickness,\n int num_points)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n When thickness <= 0 this function computes positions of num_points regularly\n spaced points on an elliptical arc. When thickness > 0 this function computes\n@@ -343,14 +371,16 @@\n * start_theta - The initial angle from which the arc is calculated in\n radians\n * delta_theta - Angular span of the arc in radians (pass a negative number\n to switch direction)\n * thickness - Thickness of the arc\n * num_points - The number of points to calculate\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\ba_\br_\bc, _\ba_\bl_\b__\bc_\ba_\bl_\bc_\bu_\bl_\ba_\bt_\be_\b__\bs_\bp_\bl_\bi_\bn_\be, _\ba_\bl_\b__\bc_\ba_\bl_\bc_\bu_\bl_\ba_\bt_\be_\b__\br_\bi_\bb_\bb_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_p\bpi\bie\bes\bsl\bli\bic\bce\be *\b**\b**\b**\b**\b*\n void al_draw_pieslice(float cx, float cy, float r, float start_theta,\n float delta_theta, ALLEGRO_COLOR color, float thickness)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a pieslice (outlined circular sector).\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * cx, cy - Center of the pieslice\n@@ -359,14 +389,16 @@\n * start_theta - The initial angle from which the pieslice is drawn in\n radians\n * delta_theta - Angular span of the pieslice in radians (pass a negative\n number to switch direction)\n * thickness - Thickness of the circle, pass <= 0 to draw hairline pieslice\n Since: 5.0.6, 5.1.0\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bf_\bi_\bl_\bl_\be_\bd_\b__\bp_\bi_\be_\bs_\bl_\bi_\bc_\be\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_f\bfi\bil\bll\ble\bed\bd_\b_p\bpi\bie\bes\bsl\bli\bic\bce\be *\b**\b**\b**\b**\b*\n void al_draw_filled_pieslice(float cx, float cy, float r, float start_theta,\n float delta_theta, ALLEGRO_COLOR color)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a filled pieslice (filled circular sector).\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * cx, cy - Center of the pieslice\n@@ -374,56 +406,71 @@\n * color - Color of the pieslice\n * start_theta - The initial angle from which the pieslice is drawn in\n radians\n * delta_theta - Angular span of the pieslice in radians (pass a negative\n number to switch direction)\n Since: 5.0.6, 5.1.0\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bp_\bi_\be_\bs_\bl_\bi_\bc_\be\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_e\bel\bll\bli\bip\bps\bse\be *\b**\b**\b**\b**\b*\n void al_draw_ellipse(float cx, float cy, float rx, float ry,\n ALLEGRO_COLOR color, float thickness)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws an outlined ellipse.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * cx, cy - Center of the ellipse\n * rx, ry - Radii of the ellipse\n * color - Color of the ellipse\n * thickness - Thickness of the ellipse, pass <= 0 to draw a hairline\n ellipse\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bf_\bi_\bl_\bl_\be_\bd_\b__\be_\bl_\bl_\bi_\bp_\bs_\be, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bc_\bi_\br_\bc_\bl_\be\n+Examples:\n+ * _\be_\bx_\b__\bd_\br_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_f\bfi\bil\bll\ble\bed\bd_\b_e\bel\bll\bli\bip\bps\bse\be *\b**\b**\b**\b**\b*\n void al_draw_filled_ellipse(float cx, float cy, float rx, float ry,\n ALLEGRO_COLOR color)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a filled ellipse.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * cx, cy - Center of the ellipse\n * rx, ry - Radii of the ellipse\n * color - Color of the ellipse\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\be_\bl_\bl_\bi_\bp_\bs_\be, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bf_\bi_\bl_\bl_\be_\bd_\b__\bc_\bi_\br_\bc_\bl_\be\n+Examples:\n+ * _\be_\bx_\b__\bd_\br_\ba_\bw_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_c\bci\bir\brc\bcl\ble\be *\b**\b**\b**\b**\b*\n void al_draw_circle(float cx, float cy, float r, ALLEGRO_COLOR color,\n float thickness)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws an outlined circle.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * cx, cy - Center of the circle\n * r - Radius of the circle\n * color - Color of the circle\n * thickness - Thickness of the circle, pass <= 0 to draw a hairline circle\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bf_\bi_\bl_\bl_\be_\bd_\b__\bc_\bi_\br_\bc_\bl_\be, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\be_\bl_\bl_\bi_\bp_\bs_\be\n+Examples:\n+ * _\be_\bx_\b__\bt_\bo_\bu_\bc_\bh_\b__\bi_\bn_\bp_\bu_\bt_\b._\bc\n+ * _\be_\bx_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_f\bfi\bil\bll\ble\bed\bd_\b_c\bci\bir\brc\bcl\ble\be *\b**\b**\b**\b**\b*\n void al_draw_filled_circle(float cx, float cy, float r, ALLEGRO_COLOR color)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a filled circle.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * cx, cy - Center of the circle\n * r - Radius of the circle\n * color - Color of the circle\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bc_\bi_\br_\bc_\bl_\be, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bf_\bi_\bl_\bl_\be_\bd_\b__\be_\bl_\bl_\bi_\bp_\bs_\be\n+Examples:\n+ * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bc_\bl_\bi_\be_\bn_\bt_\b._\bc\n+ * _\be_\bx_\b__\bj_\bo_\by_\bs_\bt_\bi_\bc_\bk_\b__\bh_\bo_\bt_\bp_\bl_\bu_\bg_\bg_\bi_\bn_\bg_\b._\bc\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b2_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_a\bar\brc\bc *\b**\b**\b**\b**\b*\n void al_draw_arc(float cx, float cy, float r, float start_theta,\n float delta_theta, ALLEGRO_COLOR color, float thickness)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws an arc.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * cx, cy - Center of the arc\n@@ -431,14 +478,16 @@\n * color - Color of the arc\n * start_theta - The initial angle from which the arc is calculated in\n radians\n * delta_theta - Angular span of the arc in radians (pass a negative number\n to switch direction)\n * thickness - Thickness of the arc, pass <= 0 to draw hairline arc\n See also: _\ba_\bl_\b__\bc_\ba_\bl_\bc_\bu_\bl_\ba_\bt_\be_\b__\ba_\br_\bc, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\be_\bl_\bl_\bi_\bp_\bt_\bi_\bc_\ba_\bl_\b__\ba_\br_\bc\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_e\bel\bll\bli\bip\bpt\bti\bic\bca\bal\bl_\b_a\bar\brc\bc *\b**\b**\b**\b**\b*\n void al_draw_elliptical_arc(float cx, float cy, float rx, float ry, float\n start_theta,\n float delta_theta, ALLEGRO_COLOR color, float thickness)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws an elliptical arc.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n@@ -448,14 +497,16 @@\n * start_theta - The initial angle from which the arc is calculated in\n radians\n * delta_theta - Angular span of the arc in radians (pass a negative number\n to switch direction)\n * thickness - Thickness of the arc, pass <= 0 to draw hairline arc\n Since: 5.0.6, 5.1.0\n See also: _\ba_\bl_\b__\bc_\ba_\bl_\bc_\bu_\bl_\ba_\bt_\be_\b__\ba_\br_\bc, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\ba_\br_\bc\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bca\bal\blc\bcu\bul\bla\bat\bte\be_\b_s\bsp\bpl\bli\bin\bne\be *\b**\b**\b**\b**\b*\n void al_calculate_spline(float* dest, int stride, const float points[8],\n float thickness, int num_segments)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Calculates a B\u00e9zier spline given 4 control points. If thickness <= 0, then\n num_segments of points are required in the destination, otherwise twice as many\n are needed. The destination buffer should consist of regularly spaced (by\n@@ -475,14 +526,16 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a B\u00e9zier spline given 4 control points.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * points - An array of 4 pairs of coordinates of the 4 control points\n * color - Color of the spline\n * thickness - Thickness of the spline, pass <= 0 to draw a hairline spline\n See also: _\ba_\bl_\b__\bc_\ba_\bl_\bc_\bu_\bl_\ba_\bt_\be_\b__\bs_\bp_\bl_\bi_\bn_\be\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bca\bal\blc\bcu\bul\bla\bat\bte\be_\b_r\bri\bib\bbb\bbo\bon\bn *\b**\b**\b**\b**\b*\n void al_calculate_ribbon(float* dest, int dest_stride, const float *points,\n int points_stride, float thickness, int num_segments)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Calculates a ribbon given an array of points. The ribbon will go through all of\n the passed points. If thickness <= 0, then num_segments of points are required\n in the destination buffer, otherwise twice as many are needed. The destination\n@@ -556,14 +609,18 @@\n ALLEGRO_VERTEX v[] = {\n {.x = 128, .y = 0, .z = 0, .color = white, .u = 128, .v = 0},\n {.x = 0, .y = 256, .z = 0, .color = white, .u = 0, .v = 256},\n {.x = 256, .y = 256, .z = 0, .color = white, .u = 256, .v = 256}};\n al_draw_prim(v, NULL, texture, 0, 3, ALLEGRO_PRIM_TRIANGLE_LIST);\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bR_\bI_\bM_\b__\bT_\bY_\bP_\bE, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bD_\bE_\bC_\bL,\n _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bi_\bn_\bd_\be_\bx_\be_\bd_\b__\bp_\br_\bi_\bm\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bw_\br_\ba_\bp_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_i\bin\bnd\bde\bex\bxe\bed\bd_\b_p\bpr\bri\bim\bm *\b**\b**\b**\b**\b*\n int al_draw_indexed_prim(const void* vtxs, const ALLEGRO_VERTEX_DECL* decl,\n ALLEGRO_BITMAP* texture, const int* indices, int num_vtx, int type)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a subset of the passed vertex array. This function uses an index array to\n specify which vertices to use.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n@@ -573,14 +630,17 @@\n assumed to be of the ALLEGRO_VERTEX type\n * indices - An array of indices into the vertex array\n * num_vtx - Number of indices from the indices array you want to draw\n * type - A member of the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bR_\bI_\bM_\b__\bT_\bY_\bP_\bE enumeration, specifying what\n kind of primitive to draw\n R\bRe\bet\btu\bur\brn\bns\bs:\b: Number of primitives drawn\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bR_\bI_\bM_\b__\bT_\bY_\bP_\bE, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bD_\bE_\bC_\bL, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bp_\br_\bi_\bm\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b2_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_v\bve\ber\brt\bte\bex\bx_\b_b\bbu\buf\bff\bfe\ber\br *\b**\b**\b**\b**\b*\n int al_draw_vertex_buffer(ALLEGRO_VERTEX_BUFFER* vertex_buffer,\n ALLEGRO_BITMAP* texture, int start, int end, int type)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a subset of the passed vertex buffer. The vertex buffer must not be\n locked. Additionally, to draw onto memory bitmaps or with memory bitmap\n textures the vertex buffer must support reading (i.e. it must be created with\n@@ -591,14 +651,17 @@\n * start - Start index of the subset of the vertex buffer to draw\n * end - One past the last index of the subset of the vertex buffer to draw\n * type - A member of the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bR_\bI_\bM_\b__\bT_\bY_\bP_\bE enumeration, specifying what\n kind of primitive to draw\n R\bRe\bet\btu\bur\brn\bns\bs:\b: Number of primitives drawn\n Since: 5.1.3\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bB_\bU_\bF_\bF_\bE_\bR, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bR_\bI_\bM_\b__\bT_\bY_\bP_\bE\n+Examples:\n+ * _\be_\bx_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_i\bin\bnd\bde\bex\bxe\bed\bd_\b_b\bbu\buf\bff\bfe\ber\br *\b**\b**\b**\b**\b*\n int al_draw_indexed_buffer(ALLEGRO_VERTEX_BUFFER* vertex_buffer,\n ALLEGRO_BITMAP* texture, ALLEGRO_INDEX_BUFFER* index_buffer,\n int start, int end, int type)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a subset of the passed vertex buffer. This function uses an index buffer\n to specify which vertices to use. Both buffers must not be locked.\n@@ -613,14 +676,16 @@\n * end - One past the last index of the subset of the index buffer to draw\n * type - A member of the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bR_\bI_\bM_\b__\bT_\bY_\bP_\bE enumeration, specifying what\n kind of primitive to draw. Note that ALLEGRO_PRIM_LINE_LOOP and\n ALLEGRO_PRIM_POINT_LIST are not supported.\n R\bRe\bet\btu\bur\brn\bns\bs:\b: Number of primitives drawn\n Since: 5.1.8\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bB_\bU_\bF_\bF_\bE_\bR, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bI_\bN_\bD_\bE_\bX_\b__\bB_\bU_\bF_\bF_\bE_\bR, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bR_\bI_\bM_\b__\bT_\bY_\bP_\bE\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_s\bso\bof\bft\bt_\b_t\btr\bri\bia\ban\bng\bgl\ble\be *\b**\b**\b**\b**\b*\n void al_draw_soft_triangle(\n ALLEGRO_VERTEX* v1, ALLEGRO_VERTEX* v2, ALLEGRO_VERTEX* v3, uintptr_t state,\n void (*init)(uintptr_t, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*),\n void (*first)(uintptr_t, int, int, int, int),\n void (*step)(uintptr_t, int),\n void (*draw)(uintptr_t, int, int, int))\n@@ -684,21 +749,26 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Creates a vertex declaration, which describes a custom vertex format.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * elements - An array of _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bE_\bL_\bE_\bM_\bE_\bN_\bT structures.\n * stride - Size of the custom vertex structure\n R\bRe\bet\btu\bur\brn\bns\bs:\b: Newly created vertex declaration.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bE_\bL_\bE_\bM_\bE_\bN_\bT, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bD_\bE_\bC_\bL, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bd_\be_\bc_\bl\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_v\bve\ber\brt\bte\bex\bx_\b_d\bde\bec\bcl\bl *\b**\b**\b**\b**\b*\n void al_destroy_vertex_decl(ALLEGRO_VERTEX_DECL* decl)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Destroys a vertex declaration.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * decl - Vertex declaration to destroy\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bE_\bL_\bE_\bM_\bE_\bN_\bT, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bD_\bE_\bC_\bL, _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bd_\be_\bc_\bl\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* V\bVe\ber\brt\bte\bex\bx b\bbu\buf\bff\bfe\ber\br r\bro\bou\but\bti\bin\bne\bes\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_v\bve\ber\brt\bte\bex\bx_\b_b\bbu\buf\bff\bfe\ber\br *\b**\b**\b**\b**\b*\n ALLEGRO_VERTEX_BUFFER* al_create_vertex_buffer(ALLEGRO_VERTEX_DECL* decl,\n const void* initial_data, int num_vertices, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Creates a vertex buffer. Can return NULL if the buffer could not be created\n (e.g.\u00a0the system only supports write-only buffers).\n@@ -714,20 +784,26 @@\n buffer. Can be NULL, in which case the buffer is uninitialized.\n * num_vertices - Number of vertices the buffer will hold\n * flags - A combination of the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bR_\bI_\bM_\b__\bB_\bU_\bF_\bF_\bE_\bR_\b__\bF_\bL_\bA_\bG_\bS flags specifying\n how this buffer will be created. Passing 0 is the same as passing\n ALLEGRO_PRIM_BUFFER_STATIC.\n Since: 5.1.3\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bB_\bU_\bF_\bF_\bE_\bR, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_v\bve\ber\brt\bte\bex\bx_\b_b\bbu\buf\bff\bfe\ber\br *\b**\b**\b**\b**\b*\n void al_destroy_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Destroys a vertex buffer. Does nothing if passed NULL.\n Since: 5.1.3\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bB_\bU_\bF_\bF_\bE_\bR, _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boc\bck\bk_\b_v\bve\ber\brt\bte\bex\bx_\b_b\bbu\buf\bff\bfe\ber\br *\b**\b**\b**\b**\b*\n void* al_lock_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer, int offset,\n int length, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Locks a vertex buffer so you can access its data. Will return NULL if the\n parameters are invalid, if reading is requested from a write only buffer, or if\n the buffer is already locked.\n@@ -735,20 +811,26 @@\n * buffer - Vertex buffer to lock\n * offset - Vertex index of the start of the locked range\n * length - How many vertices to lock\n * flags - ALLEGRO_LOCK_READONLY, ALLEGRO_LOCK_WRITEONLY or\n ALLEGRO_LOCK_READWRITE\n Since: 5.1.3\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bB_\bU_\bF_\bF_\bE_\bR, _\ba_\bl_\b__\bu_\bn_\bl_\bo_\bc_\bk_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bnl\blo\boc\bck\bk_\b_v\bve\ber\brt\bte\bex\bx_\b_b\bbu\buf\bff\bfe\ber\br *\b**\b**\b**\b**\b*\n void al_unlock_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Unlocks a previously locked vertex buffer.\n Since: 5.1.3\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bB_\bU_\bF_\bF_\bE_\bR, _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_v\bve\ber\brt\bte\bex\bx_\b_b\bbu\buf\bff\bfe\ber\br_\b_s\bsi\biz\bze\be *\b**\b**\b**\b**\b*\n int al_get_vertex_buffer_size(ALLEGRO_VERTEX_BUFFER* buffer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the size of the vertex buffer\n Since: 5.1.8\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bB_\bU_\bF_\bF_\bE_\bR\n *\b**\b**\b**\b**\b**\b* I\bIn\bnd\bde\bex\bx b\bbu\buf\bff\bfe\ber\br r\bro\bou\but\bti\bin\bne\bes\bs *\b**\b**\b**\b**\b**\b*\n@@ -770,20 +852,24 @@\n Can be NULL, in which case the buffer is uninitialized.\n * num_indices - Number of indices the buffer will hold\n * flags - A combination of the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bR_\bI_\bM_\b__\bB_\bU_\bF_\bF_\bE_\bR_\b__\bF_\bL_\bA_\bG_\bS flags specifying\n how this buffer will be created. Passing 0 is the same as passing\n ALLEGRO_PRIM_BUFFER_STATIC.\n Since: 5.1.8\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bI_\bN_\bD_\bE_\bX_\b__\bB_\bU_\bF_\bF_\bE_\bR, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bi_\bn_\bd_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_i\bin\bnd\bde\bex\bx_\b_b\bbu\buf\bff\bfe\ber\br *\b**\b**\b**\b**\b*\n void al_destroy_index_buffer(ALLEGRO_INDEX_BUFFER* buffer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Destroys a index buffer. Does nothing if passed NULL.\n Since: 5.1.8\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bI_\bN_\bD_\bE_\bX_\b__\bB_\bU_\bF_\bF_\bE_\bR, _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bi_\bn_\bd_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_l\blo\boc\bck\bk_\b_i\bin\bnd\bde\bex\bx_\b_b\bbu\buf\bff\bfe\ber\br *\b**\b**\b**\b**\b*\n void* al_lock_index_buffer(ALLEGRO_INDEX_BUFFER* buffer, int offset,\n int length, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Locks a index buffer so you can access its data. Will return NULL if the\n parameters are invalid, if reading is requested from a write only buffer and if\n the buffer is already locked.\n@@ -791,20 +877,24 @@\n * buffer - Index buffer to lock\n * offset - Element index of the start of the locked range\n * length - How many indices to lock\n * flags - ALLEGRO_LOCK_READONLY, ALLEGRO_LOCK_WRITEONLY or\n ALLEGRO_LOCK_READWRITE\n Since: 5.1.8\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bI_\bN_\bD_\bE_\bX_\b__\bB_\bU_\bF_\bF_\bE_\bR, _\ba_\bl_\b__\bu_\bn_\bl_\bo_\bc_\bk_\b__\bi_\bn_\bd_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bnl\blo\boc\bck\bk_\b_i\bin\bnd\bde\bex\bx_\b_b\bbu\buf\bff\bfe\ber\br *\b**\b**\b**\b**\b*\n void al_unlock_index_buffer(ALLEGRO_INDEX_BUFFER* buffer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Unlocks a previously locked index buffer.\n Since: 5.1.8\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bI_\bN_\bD_\bE_\bX_\b__\bB_\bU_\bF_\bF_\bE_\bR, _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bi_\bn_\bd_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_i\bin\bnd\bde\bex\bx_\b_b\bbu\buf\bff\bfe\ber\br_\b_s\bsi\biz\bze\be *\b**\b**\b**\b**\b*\n int al_get_index_buffer_size(ALLEGRO_INDEX_BUFFER* buffer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the size of the index buffer\n Since: 5.1.8\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bI_\bN_\bD_\bE_\bX_\b__\bB_\bU_\bF_\bF_\bE_\bR\n *\b**\b**\b**\b**\b**\b* P\bPo\bol\bly\byg\bgo\bon\bn r\bro\bou\but\bti\bin\bne\bes\bs *\b**\b**\b**\b**\b**\b*\n@@ -837,14 +927,16 @@\n {\n al_draw_polyline((float *)verts, sizeof(VertexInfo), vertex_count,\n ALLEGRO_LINE_JOIN_NONE, ALLEGRO_LINE_CAP_NONE, c, 1.0, 1.0);\n }\n The stride may also be negative if the vertices are stored in reverse order.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bL_\bI_\bN_\bE_\b__\bJ_\bO_\bI_\bN, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bL_\bI_\bN_\bE_\b__\bC_\bA_\bP\n+Examples:\n+ * _\be_\bx_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_p\bpo\bol\bly\byg\bgo\bon\bn *\b**\b**\b**\b**\b*\n void al_draw_polygon(const float *vertices, int vertex_count,\n int join_style, ALLEGRO_COLOR color, float thickness, float miter_limit)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draw an unfilled polygon. This is the same as passing ALLEGRO_LINE_CAP_CLOSED\n to _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bp_\bo_\bl_\by_\bl_\bi_\bn_\be.\n * vertex - Interleaved array of (x, y) vertex coordinates\n@@ -852,27 +944,31 @@\n * join_style - Member of _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bL_\bI_\bN_\bE_\b__\bJ_\bO_\bI_\bN specifying how to render the\n joins between line segments\n * color - Color of the line\n * thickness - Thickness of the line, pass <= 0 to draw hairline lines\n * miter_limit - Parameter for miter join style\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bf_\bi_\bl_\bl_\be_\bd_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bp_\bo_\bl_\by_\bl_\bi_\bn_\be, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bL_\bI_\bN_\bE_\b__\bJ_\bO_\bI_\bN\n+Examples:\n+ * _\be_\bx_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_f\bfi\bil\bll\ble\bed\bd_\b_p\bpo\bol\bly\byg\bgo\bon\bn *\b**\b**\b**\b**\b*\n void al_draw_filled_polygon(const float *vertices, int vertex_count,\n ALLEGRO_COLOR color)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draw a filled, simple polygon. Simple means it does not have to be convex but\n must not be self-overlapping.\n * vertices - Interleaved array of (x, y) vertex coordinates\n * vertex_count - Number of vertices in the array\n * color - Color of the filled polygon\n When the y-axis is facing downwards (the usual), the coordinates must be\n ordered anti-clockwise.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bf_\bi_\bl_\bl_\be_\bd_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn_\b__\bw_\bi_\bt_\bh_\b__\bh_\bo_\bl_\be_\bs\n+Examples:\n+ * _\be_\bx_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_d\bdr\bra\baw\bw_\b_f\bfi\bil\bll\ble\bed\bd_\b_p\bpo\bol\bly\byg\bgo\bon\bn_\b_w\bwi\bit\bth\bh_\b_h\bho\bol\ble\bes\bs *\b**\b**\b**\b**\b*\n void al_draw_filled_polygon_with_holes(const float *vertices,\n const int *vertex_counts, ALLEGRO_COLOR color)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Draws a filled simple polygon with zero or more other simple polygons\n subtracted from it - the holes. The holes cannot touch or intersect with the\n outline of the filled polygon.\n@@ -905,14 +1001,16 @@\n There are 7 vertices: four for an outer square from (0, 0) to (100, 100) in\n anti-clockwise order, and three more for an inner triangle in clockwise order.\n The outer main polygon uses vertices 0 to 3 (inclusive) and the hole uses\n vertices 4 to 6 (inclusive).\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bf_\bi_\bl_\bl_\be_\bd_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn, _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bf_\bi_\bl_\bl_\be_\bd_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn_\b__\bw_\bi_\bt_\bh_\b__\bh_\bo_\bl_\be_\bs,\n _\ba_\bl_\b__\bt_\br_\bi_\ba_\bn_\bg_\bu_\bl_\ba_\bt_\be_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_t\btr\bri\bia\ban\bng\bgu\bul\bla\bat\bte\be_\b_p\bpo\bol\bly\byg\bgo\bon\bn *\b**\b**\b**\b**\b*\n bool al_triangulate_polygon(\n const float* vertices, size_t vertex_stride, const int* vertex_counts,\n void (*emit_triangle)(int, int, int, void*), void* userdata)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Divides a simple polygon into triangles, with zero or more other simple\n polygons subtracted from it - the holes. The holes cannot touch or intersect\n@@ -944,21 +1042,28 @@\n you\u2019re using it. One exception to this rule are the u and v variables which can\n be left uninitialized when you are not using textures.\n F\bFi\bie\bel\bld\bds\bs:\b:\n * x, y, z - Position of the vertex (float)\n * u, v - Texture coordinates measured in pixels (float)\n * color - _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bC_\bO_\bL_\bO_\bR structure, storing the color of the vertex\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bR_\bI_\bM_\b__\bA_\bT_\bT_\bR\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_V\bVE\bER\bRT\bTE\bEX\bX_\b_D\bDE\bEC\bCL\bL *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_VERTEX_DECL ALLEGRO_VERTEX_DECL;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n A vertex declaration. This opaque structure is responsible for describing the\n format and layout of a user defined custom vertex. It is created and destroyed\n by specialized functions.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bd_\be_\bc_\bl, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bd_\be_\bc_\bl, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bE_\bL_\bE_\bM_\bE_\bN_\bT\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_V\bVE\bER\bRT\bTE\bEX\bX_\b_E\bEL\bLE\bEM\bME\bEN\bNT\bT *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_VERTEX_ELEMENT ALLEGRO_VERTEX_ELEMENT;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n A small structure describing a certain element of a vertex. E.g. the position\n of the vertex, or its color. These structures are used by the\n _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bd_\be_\bc_\bl function to create the vertex declaration. For that they\n generally occur in an array. The last element of such an array should have the\n@@ -983,14 +1088,17 @@\n what this attribute signifies\n * storage - A member of the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bR_\bI_\bM_\b__\bS_\bT_\bO_\bR_\bA_\bG_\bE enumeration, specifying\n how this attribute is stored\n * offset - Offset in bytes from the beginning of the custom vertex\n structure. The C function offsetof is very useful here.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bd_\be_\bc_\bl, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bE_\bR_\bT_\bE_\bX_\b__\bD_\bE_\bC_\bL, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bR_\bI_\bM_\b__\bA_\bT_\bT_\bR,\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bR_\bI_\bM_\b__\bS_\bT_\bO_\bR_\bA_\bG_\bE\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_P\bPR\bRI\bIM\bM_\b_T\bTY\bYP\bPE\bE *\b**\b**\b**\b**\b*\n typedef enum ALLEGRO_PRIM_TYPE\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Enumerates the types of primitives this addon can draw.\n * ALLEGRO_PRIM_POINT_LIST - A list of points, each vertex defines a point\n * ALLEGRO_PRIM_LINE_LIST - A list of lines, sequential pairs of vertices\n define disjointed lines\n@@ -1124,14 +1232,16 @@\n * ALLEGRO_LINE_JOIN_MITER\n [ALLEGRO_LINE_JOIN styles]A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_L\bLI\bIN\bNE\bE_\b_J\bJO\bOI\bIN\bN s\bst\bty\byl\ble\bes\bs\n See the picture for the difference.\n The maximum miter length (relative to the line width) can be specified as\n parameter to the polygon functions.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_L\bLI\bIN\bNE\bE_\b_C\bCA\bAP\bP *\b**\b**\b**\b**\b*\n typedef enum ALLEGRO_LINE_CAP\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n * ALLEGRO_LINE_CAP_NONE\n * ALLEGRO_LINE_CAP_SQUARE\n * ALLEGRO_LINE_CAP_ROUND\n * ALLEGRO_LINE_CAP_TRIANGLE\n@@ -1139,29 +1249,36 @@\n [ALLEGRO_LINE_CAP styles]A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_L\bLI\bIN\bNE\bE_\b_C\bCA\bAP\bP s\bst\bty\byl\ble\bes\bs\n See the picture for the difference.\n ALLEGRO_LINE_CAP_CLOSED is different from the others - it causes the polygon to\n have no caps. (And the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bL_\bI_\bN_\bE_\b__\bJ_\bO_\bI_\bN style will determine how the vertex\n looks.)\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bd_\br_\ba_\bw_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn\n+Examples:\n+ * _\be_\bx_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_V\bVE\bER\bRT\bTE\bEX\bX_\b_B\bBU\bUF\bFF\bFE\bER\bR *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_VERTEX_BUFFER ALLEGRO_VERTEX_BUFFER;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n A GPU vertex buffer that you can use to store vertices on the GPU instead of\n uploading them afresh during every drawing operation.\n Since: 5.1.3\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bv_\be_\br_\bt_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_I\bIN\bND\bDE\bEX\bX_\b_B\bBU\bUF\bFF\bFE\bER\bR *\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_INDEX_BUFFER ALLEGRO_INDEX_BUFFER;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n A GPU index buffer that you can use to store indices of vertices in a vertex\n buffer on the GPU instead of uploading them afresh during every drawing\n operation.\n Since: 5.1.8\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bi_\bn_\bd_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bi_\bn_\bd_\be_\bx_\b__\bb_\bu_\bf_\bf_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_P\bPR\bRI\bIM\bM_\b_B\bBU\bUF\bFF\bFE\bER\bR_\b_F\bFL\bLA\bAG\bGS\bS *\b**\b**\b**\b**\b*\n typedef enum ALLEGRO_PRIM_BUFFER_FLAGS\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Flags to specify how to create a vertex or an index buffer.\n * ALLEGRO_PRIM_BUFFER_STREAM - Hints to the driver that the buffer is\n written to often, but used only a few times per frame\n * ALLEGRO_PRIM_BUFFER_STATIC - Hints to the driver that the buffer is\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/shader.html", "source2": "./usr/share/doc/allegro5-doc/refman/shader.html", "unified_diff": "@@ -229,14 +229,23 @@\n program which has one or more shaders attached. This\n can be confusing.)

          \n

          The source code for the underlying vertex or pixel shader can be\n provided either as GLSL or HLSL, depending on the value of ALLEGRO_SHADER_PLATFORM\n used when creating it.

          \n

          Since: 5.1.0

          \n+

          Examples:

          \n+
            \n+
          • ex_shader.cpp
            • \n+
          • ex_shader_target.c
            • \n+
          • ex_prim_shader.c
            • \n+
          \n

          ALLEGRO_SHADER_TYPE

          \n 
          typedef enum ALLEGRO_SHADER_TYPE ALLEGRO_SHADER_TYPE;
          \n

          Source\n Code

          \n

          Used with al_attach_shader_source\n@@ -284,14 +293,21 @@\n more minimal implementation that may not support alpha testing.\n

        • ALLEGRO_SHADER_GLSL_MINIMAL - Minimal GLSL shader.
          • \n
        • ALLEGRO_SHADER_HLSL_MINIMAL - Minimal HLSL shader.
          • \n
        • ALLEGRO_SHADER_HLSL_SM_3_0 - HLSL shader using shader model\n 3_0.
          • \n
        \n

        Since: 5.1.0

        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        • ex_shader_target.c
          • \n+
        \n

        al_create_shader

        \n 
        ALLEGRO_SHADER *al_create_shader(ALLEGRO_SHADER_PLATFORM platform)
        \n

        Source\n Code

        \n

        Create a shader object.

        \n

        The platform argument is one of the al_attach_shader_source,\n al_attach_shader_source_file,\n al_build_shader, al_use_shader, al_destroy_shader, al_get_shader_platform

        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        • ex_shader_target.c
          • \n+
        • ex_prim_shader.c
          • \n+
        \n

        al_attach_shader_source

        \n 
        bool al_attach_shader_source(ALLEGRO_SHADER *shader, ALLEGRO_SHADER_TYPE type,\n     const char *source)
        \n

        Source\n Code

        \n

        Attaches the shader\u2019s source code to the shader object and compiles\n@@ -457,14 +482,23 @@\n

        Since: 5.1.0

        \n

        See also: al_attach_shader_source_file,\n al_build_shader, al_get_default_shader_source,\n al_get_shader_log, ALLEGRO_PRIM_ATTR

        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        • ex_shader_target.c
          • \n+
        • ex_prim_shader.c
          • \n+
        \n

        al_attach_shader_source_file

        \n 
        bool al_attach_shader_source_file(ALLEGRO_SHADER *shader,\n    ALLEGRO_SHADER_TYPE type, const char *filename)
        \n

        Source\n Code

        \n

        Like al_get_shader_log.

        \n

        Since: 5.1.0

        \n

        See also: al_attach_shader_source,\n al_build_shader, al_get_shader_log

        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        • ex_shader_target.c
          • \n+
        • ex_prim_shader.c
          • \n+
        \n

        al_build_shader

        \n 
        bool al_build_shader(ALLEGRO_SHADER *shader)
        \n

        Source\n Code

        \n

        This is required before the shader can be used with al_use_shader. It should be called\n@@ -496,14 +539,23 @@\n

        Note: If you are using the ALLEGRO_PROGRAMMABLE_PIPELINE\n flag, then you must specify both a pixel and a vertex shader sources for\n anything to be rendered.

        \n \n

        Since: 5.1.6

        \n

        See also: al_use_shader, al_get_shader_log

        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        • ex_shader_target.c
          • \n+
        • ex_prim_shader.c
          • \n+
        \n

        al_get_shader_log

        \n 
        const char *al_get_shader_log(ALLEGRO_SHADER *shader)
        \n

        Source\n Code

        \n

        Return a read-only string containing the information log for a shader\n program. The log is updated by certain functions, such as This function never returns NULL.

        \n

        Since: 5.1.0

        \n

        See also: al_attach_shader_source,\n al_attach_shader_source_file,\n al_build_shader

        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        • ex_shader_target.c
          • \n+
        • ex_prim_shader.c
          • \n+
        \n

        al_get_shader_platform

        \n 
        ALLEGRO_SHADER_PLATFORM al_get_shader_platform(ALLEGRO_SHADER *shader)
        \n

        Source\n Code

        \n

        Returns the platform the shader was created with (either\n ALLEGRO_SHADER_HLSL or ALLEGRO_SHADER_GLSL).

        \n

        Since: 5.1.6

        \n

        See also: al_create_shader

        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        • ex_shader_target.c
          • \n+
        • ex_prim_shader.c
          • \n+
        \n

        al_use_shader

        \n 
        bool al_use_shader(ALLEGRO_SHADER *shader)
        \n

        Source\n Code

        \n

        Uses the shader for subsequent drawing operations on the current\n target bitmap. Pass NULL to stop using any shader on the current target\n@@ -546,14 +616,23 @@\n href=\"shader.html#al_set_shader_float\">al_set_shader_float, al_set_shader_bool, al_set_shader_int_vector,\n al_set_shader_float_vector,\n al_get_current_shader

        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        • ex_shader_target.c
          • \n+
        • ex_prim_shader.c
          • \n+
        \n

        al_get_current_shader

        \n 
        ALLEGRO_SHADER *al_get_current_shader()
        \n

        Source\n Code

        \n

        Return the shader of the target bitmap, or NULL if one isn\u2019t being\n used.

        \n@@ -571,14 +650,23 @@\n

        As a convenience, if the target bitmap of the calling thread is using\n the shader then the shader is implicitly unused before being\n destroyed.

        \n

        This function does nothing if the shader argument is NULL.

        \n

        Since: 5.1.0

        \n

        See also: al_create_shader

        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        • ex_shader_target.c
          • \n+
        • ex_prim_shader.c
          • \n+
        \n

        al_set_shader_sampler

        \n 
        bool al_set_shader_sampler(const char *name,\n    ALLEGRO_BITMAP *bitmap, int unit)
        \n

        Source\n Code

        \n

        Sets a texture sampler uniform and texture unit of the current target\n@@ -592,14 +680,23 @@\n drawing functions. In this case, you may set a sampler to use the 0th\n unit and thus not use al_tex (the al_use_tex\n variable will be set to false).

        \n

        Returns true on success. Otherwise returns false, e.g.\u00a0if the uniform\n by that name does not exist in the shader.

        \n

        Since: 5.1.0

        \n

        See also: al_use_shader

        \n+

        Examples:

        \n+
          \n+
        • ex_shader_multitex.c
          • \n+
        • ex_palette.c
          • \n+
        • ex_prim_wrap.c
          • \n+
        \n

        al_set_shader_matrix

        \n 
        bool al_set_shader_matrix(const char *name,\n    const ALLEGRO_TRANSFORM *matrix)
        \n

        Source\n Code

        \n

        Sets a matrix uniform of the current target bitmap\u2019s shader.

        \n@@ -623,14 +720,23 @@\n href=\"https://github.com/liballeg/allegro5/blob/master/src/shader.c#L332\">Source\n Code

        \n

        Sets a float uniform of the target bitmap\u2019s shader.

        \n

        Returns true on success. Otherwise returns false, e.g.\u00a0if the uniform\n by that name does not exist in the shader.

        \n

        Since: 5.1.0

        \n

        See also: al_use_shader

        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        • ex_shader_target.c
          • \n+
        • ex_prim_shader.c
          • \n+
        \n

        al_set_shader_bool

        \n 
        bool al_set_shader_bool(const char *name, bool b)
        \n

        Source\n Code

        \n

        Sets a boolean uniform of the target bitmap\u2019s shader.

        \n

        Returns true on success. Otherwise returns false, e.g.\u00a0if the uniform\n@@ -676,14 +782,23 @@\n

        Same as al_set_shader_int_vector\n except all values are float instead of int.

        \n

        Since: 5.1.0

        \n

        See also: al_set_shader_int_vector,\n al_use_shader

        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        • ex_shader_target.c
          • \n+
        • ex_prim_shader.c
          • \n+
        \n

        al_get_default_shader_source

        \n 
        char const *al_get_default_shader_source(ALLEGRO_SHADER_PLATFORM platform,\n    ALLEGRO_SHADER_TYPE type)
        \n

        Source\n Code

        \n

        Returns a string containing the source code to Allegro\u2019s default\n@@ -692,11 +807,23 @@\n otherwise HLSL. ALLEGRO_SHADER_AUTO requires that there is a current\n display set on the calling thread. This function can return NULL if\n Allegro was built without support for shaders of the selected\n platform.

        \n

        Since: 5.1.6

        \n

        See also: al_attach_shader_source

        \n-\n+

        Examples:

        \n+
          \n+
        • ex_shader_multitex.c
          • \n+
        • ex_palette.c
          • \n+
        • ex_prim_wrap.c
          • \n+
        \n+

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

        \n \n \n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -71,14 +71,18 @@\n An _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bH_\bA_\bD_\bE_\bR is a program that runs on the GPU. It combines both a vertex\n and a pixel shader. (In OpenGL terms, an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bH_\bA_\bD_\bE_\bR is actually a p\bpr\bro\bog\bgr\bra\bam\bm\n which has one or more s\bsh\bha\bad\bde\ber\brs\bs attached. This can be confusing.)\n The source code for the underlying vertex or pixel shader can be provided\n either as GLSL or HLSL, depending on the value of _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bH_\bA_\bD_\bE_\bR_\b__\bP_\bL_\bA_\bT_\bF_\bO_\bR_\bM used\n when creating it.\n Since: 5.1.0\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_S\bSH\bHA\bAD\bDE\bER\bR_\b_T\bTY\bYP\bPE\bE *\b**\b**\b**\b**\b**\b*\n typedef enum ALLEGRO_SHADER_TYPE ALLEGRO_SHADER_TYPE;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Used with _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be and _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be_\b__\bf_\bi_\bl_\be to specify\n how to interpret the attached source.\n ALLEGRO_VERTEX_SHADER\n A vertex shader is executed for each vertex it is used with. The program\n@@ -109,14 +113,17 @@\n * ALLEGRO_SHADER_HLSL - High Level Shader Language (for Direct3D)\n * ALLEGRO_SHADER_AUTO_MINIMAL - Like ALLEGRO_SHADER_AUTO, but pick a more\n minimal implementation that may not support alpha testing.\n * ALLEGRO_SHADER_GLSL_MINIMAL - Minimal GLSL shader.\n * ALLEGRO_SHADER_HLSL_MINIMAL - Minimal HLSL shader.\n * ALLEGRO_SHADER_HLSL_SM_3_0 - HLSL shader using shader model 3_0.\n Since: 5.1.0\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_s\bsh\bha\bad\bde\ber\br *\b**\b**\b**\b**\b**\b*\n ALLEGRO_SHADER *al_create_shader(ALLEGRO_SHADER_PLATFORM platform)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a shader object.\n The platform argument is one of the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bH_\bA_\bD_\bE_\bR_\b__\bP_\bL_\bA_\bT_\bF_\bO_\bR_\bM values, and\n specifies the type of shader object to create, and which language is used to\n program the shader.\n@@ -127,14 +134,18 @@\n for the display currently targeted by the calling thread; there must be such a\n display. It will create a GLSL shader for an OpenGL display, and a HLSL shader\n for a Direct3D display.\n Returns the shader object on success. Otherwise, returns NULL.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be, _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be_\b__\bf_\bi_\bl_\be,\n _\ba_\bl_\b__\bb_\bu_\bi_\bl_\bd_\b__\bs_\bh_\ba_\bd_\be_\br, _\ba_\bl_\b__\bu_\bs_\be_\b__\bs_\bh_\ba_\bd_\be_\br, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bs_\bh_\ba_\bd_\be_\br, _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bp_\bl_\ba_\bt_\bf_\bo_\br_\bm\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_a\bat\btt\bta\bac\bch\bh_\b_s\bsh\bha\bad\bde\ber\br_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b**\b*\n bool al_attach_shader_source(ALLEGRO_SHADER *shader, ALLEGRO_SHADER_TYPE type,\n const char *source)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Attaches the shader\u2019s source code to the shader object and compiles it. Passing\n NULL deletes the underlying (OpenGL or DirectX) shader. See also\n _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be_\b__\bf_\bi_\bl_\be if you prefer to obtain your shader source from an\n@@ -213,65 +224,89 @@\n Examine the output of _\ba_\bl_\b__\bg_\be_\bt_\b__\bd_\be_\bf_\ba_\bu_\bl_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be for an example of how to use\n the above uniforms and attributes.\n Returns true on success and false on error, in which case the error log is\n updated. The error log can be retrieved with _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bl_\bo_\bg.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be_\b__\bf_\bi_\bl_\be, _\ba_\bl_\b__\bb_\bu_\bi_\bl_\bd_\b__\bs_\bh_\ba_\bd_\be_\br,\n _\ba_\bl_\b__\bg_\be_\bt_\b__\bd_\be_\bf_\ba_\bu_\bl_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be, _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bl_\bo_\bg, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bP_\bR_\bI_\bM_\b__\bA_\bT_\bT_\bR\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_a\bat\btt\bta\bac\bch\bh_\b_s\bsh\bha\bad\bde\ber\br_\b_s\bso\bou\bur\brc\bce\be_\b_f\bfi\bil\ble\be *\b**\b**\b**\b**\b**\b*\n bool al_attach_shader_source_file(ALLEGRO_SHADER *shader,\n ALLEGRO_SHADER_TYPE type, const char *filename)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be but reads the source code for the shader from the\n named file.\n Returns true on success and false on error, in which case the error log is\n updated. The error log can be retrieved with _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bl_\bo_\bg.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be, _\ba_\bl_\b__\bb_\bu_\bi_\bl_\bd_\b__\bs_\bh_\ba_\bd_\be_\br, _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bl_\bo_\bg\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_b\bbu\bui\bil\bld\bd_\b_s\bsh\bha\bad\bde\ber\br *\b**\b**\b**\b**\b**\b*\n bool al_build_shader(ALLEGRO_SHADER *shader)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This is required before the shader can be used with _\ba_\bl_\b__\bu_\bs_\be_\b__\bs_\bh_\ba_\bd_\be_\br. It should be\n called after successfully attaching the pixel and/or vertex shaders with\n _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be or _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be_\b__\bf_\bi_\bl_\be.\n Returns true on success and false on error, in which case the error log is\n updated. The error log can be retrieved with _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bl_\bo_\bg.\n N\bNo\bot\bte\be:\b: If you are using the ALLEGRO_PROGRAMMABLE_PIPELINE flag, then\n you must specify both a pixel and a vertex shader sources for\n anything to be rendered.\n Since: 5.1.6\n See also: _\ba_\bl_\b__\bu_\bs_\be_\b__\bs_\bh_\ba_\bd_\be_\br, _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bl_\bo_\bg\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsh\bha\bad\bde\ber\br_\b_l\blo\bog\bg *\b**\b**\b**\b**\b**\b*\n const char *al_get_shader_log(ALLEGRO_SHADER *shader)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return a read-only string containing the information log for a shader program.\n The log is updated by certain functions, such as _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be or\n _\ba_\bl_\b__\bb_\bu_\bi_\bl_\bd_\b__\bs_\bh_\ba_\bd_\be_\br when there is an error.\n This function never returns NULL.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be, _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be_\b__\bf_\bi_\bl_\be,\n _\ba_\bl_\b__\bb_\bu_\bi_\bl_\bd_\b__\bs_\bh_\ba_\bd_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsh\bha\bad\bde\ber\br_\b_p\bpl\bla\bat\btf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n ALLEGRO_SHADER_PLATFORM al_get_shader_platform(ALLEGRO_SHADER *shader)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the platform the shader was created with (either ALLEGRO_SHADER_HLSL or\n ALLEGRO_SHADER_GLSL).\n Since: 5.1.6\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bs_\bh_\ba_\bd_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bse\be_\b_s\bsh\bha\bad\bde\ber\br *\b**\b**\b**\b**\b**\b*\n bool al_use_shader(ALLEGRO_SHADER *shader)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Uses the shader for subsequent drawing operations on the current target bitmap.\n Pass NULL to stop using any shader on the current target bitmap.\n Returns true on success. Otherwise returns false, e.g.\u00a0because the shader is\n incompatible with the target bitmap.\n Since: 5.1.6\n See also: _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bs_\bh_\ba_\bd_\be_\br, _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\ba_\bm_\bp_\bl_\be_\br, _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bm_\ba_\bt_\br_\bi_\bx,\n _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bi_\bn_\bt, _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bf_\bl_\bo_\ba_\bt, _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bb_\bo_\bo_\bl,\n _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bi_\bn_\bt_\b__\bv_\be_\bc_\bt_\bo_\br, _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bf_\bl_\bo_\ba_\bt_\b__\bv_\be_\bc_\bt_\bo_\br, _\ba_\bl_\b__\bg_\be_\bt_\b__\bc_\bu_\br_\br_\be_\bn_\bt_\b__\bs_\bh_\ba_\bd_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_c\bcu\bur\brr\bre\ben\bnt\bt_\b_s\bsh\bha\bad\bde\ber\br *\b**\b**\b**\b**\b**\b*\n ALLEGRO_SHADER *al_get_current_shader()\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the shader of the target bitmap, or NULL if one isn\u2019t being used.\n Since: 5.2.9\n See also: _\ba_\bl_\b__\bu_\bs_\be_\b__\bs_\bh_\ba_\bd_\be_\br\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_s\bsh\bha\bad\bde\ber\br *\b**\b**\b**\b**\b**\b*\n@@ -281,14 +316,18 @@\n stop using the shader. In multi-threaded programs, be careful that no such\n bitmaps are being accessed by other threads at the time.\n As a convenience, if the target bitmap of the calling thread is using the\n shader then the shader is implicitly unused before being destroyed.\n This function does nothing if the shader argument is NULL.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bs_\bh_\ba_\bd_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bsh\bha\bad\bde\ber\br_\b_s\bsa\bam\bmp\bpl\ble\ber\br *\b**\b**\b**\b**\b**\b*\n bool al_set_shader_sampler(const char *name,\n ALLEGRO_BITMAP *bitmap, int unit)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets a texture sampler uniform and texture unit of the current target bitmap\u2019s\n shader. The given bitmap must be a video bitmap.\n Different samplers should use different units. The bitmap passed to Allegro\u2019s\n@@ -298,14 +337,18 @@\n free up the 0th unit by passing NULL as the texture argument to the relevant\n drawing functions. In this case, you may set a sampler to use the 0th unit and\n thus not use al_tex (the al_use_tex variable will be set to false).\n Returns true on success. Otherwise returns false, e.g.\u00a0if the uniform by that\n name does not exist in the shader.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bu_\bs_\be_\b__\bs_\bh_\ba_\bd_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bm_\bu_\bl_\bt_\bi_\bt_\be_\bx_\b._\bc\n+ * _\be_\bx_\b__\bp_\ba_\bl_\be_\bt_\bt_\be_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bw_\br_\ba_\bp_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bsh\bha\bad\bde\ber\br_\b_m\bma\bat\btr\bri\bix\bx *\b**\b**\b**\b**\b**\b*\n bool al_set_shader_matrix(const char *name,\n const ALLEGRO_TRANSFORM *matrix)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets a matrix uniform of the current target bitmap\u2019s shader.\n Returns true on success. Otherwise returns false, e.g.\u00a0if the uniform by that\n name does not exist in the shader.\n@@ -323,14 +366,18 @@\n bool al_set_shader_float(const char *name, float f)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets a float uniform of the target bitmap\u2019s shader.\n Returns true on success. Otherwise returns false, e.g.\u00a0if the uniform by that\n name does not exist in the shader.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bu_\bs_\be_\b__\bs_\bh_\ba_\bd_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bsh\bha\bad\bde\ber\br_\b_b\bbo\boo\bol\bl *\b**\b**\b**\b**\b**\b*\n bool al_set_shader_bool(const char *name, bool b)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets a boolean uniform of the target bitmap\u2019s shader.\n Returns true on success. Otherwise returns false, e.g.\u00a0if the uniform by that\n name does not exist in the shader.\n Since: 5.1.6\n@@ -362,19 +409,28 @@\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_s\bsh\bha\bad\bde\ber\br_\b_f\bfl\blo\boa\bat\bt_\b_v\bve\bec\bct\bto\bor\br *\b**\b**\b**\b**\b**\b*\n bool al_set_shader_float_vector(const char *name,\n int num_components, const float *f, int num_elems)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Same as _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bi_\bn_\bt_\b__\bv_\be_\bc_\bt_\bo_\br except all values are float instead of int.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bi_\bn_\bt_\b__\bv_\be_\bc_\bt_\bo_\br, _\ba_\bl_\b__\bu_\bs_\be_\b__\bs_\bh_\ba_\bd_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_d\bde\bef\bfa\bau\bul\blt\bt_\b_s\bsh\bha\bad\bde\ber\br_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b**\b*\n char const *al_get_default_shader_source(ALLEGRO_SHADER_PLATFORM platform,\n ALLEGRO_SHADER_TYPE type)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns a string containing the source code to Allegro\u2019s default vertex or\n pixel shader appropriate for the passed platform. The ALLEGRO_SHADER_AUTO value\n means GLSL is used if OpenGL is being used otherwise HLSL. ALLEGRO_SHADER_AUTO\n requires that there is a current display set on the calling thread. This\n function can return NULL if Allegro was built without support for shaders of\n the selected platform.\n Since: 5.1.6\n See also: _\ba_\bl_\b__\ba_\bt_\bt_\ba_\bc_\bh_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bs_\bo_\bu_\br_\bc_\be\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bm_\bu_\bl_\bt_\bi_\bt_\be_\bx_\b._\bc\n+ * _\be_\bx_\b__\bp_\ba_\bl_\be_\bt_\bt_\be_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bw_\br_\ba_\bp_\b._\bc\n+Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/state.html", "source2": "./usr/share/doc/allegro5-doc/refman/state.html", "unified_diff": "@@ -184,15 +184,18 @@\n
      • al_get_errno
        • \n
      • al_set_errno
        • \n
      \n \n

      These functions are declared in the main Allegro header file:

      \n 
       #include <allegro5/allegro.h>
      \n

      ALLEGRO_STATE

      \n-

      Source Code

      \n+
      typedef struct ALLEGRO_STATE ALLEGRO_STATE;
      \n+

      Source\n+Code

      \n

      Opaque type which is passed to al_store_state/al_restore_state.

      \n

      The various state kept internally by Allegro can be displayed like\n this:

      \n 
        global\n       active system driver\n@@ -215,32 +218,53 @@\n All other global state is per-thread, so if your application has\n multiple separate threads they never will interfere with each other.\n (Except if there are objects accessed by multiple threads of course.\n Usually you want to minimize that though and for the remaining cases use\n synchronization primitives described in the threads section or events\n described in the events section to control inter-thread\n communication.)
      \n+
      Examples:
      \n+
        \n+
      • ex_blend_bench.c
        • \n+
      • ex_blend2.cpp
        • \n+
      • nihgui.cpp
        • \n+
      \n 
      ALLEGRO_STATE_FLAGS
      \n-
      Source Code
      \n+
      typedef enum ALLEGRO_STATE_FLAGS
      \n+
      Source\n+Code
      \n 
      Flags which can be passed to al_store_state/al_restore_state as bit\n combinations. See al_store_state\n for the list of flags.
      \n 
      al_restore_state
      \n-
      void al_restore_state(ALLEGRO_STATE const *state)
      \n+
      void al_restore_state(ALLEGRO_STATE const *state)
      \n 
      Source\n Code
      \n 
      Restores part of the state of the current thread from the given ALLEGRO_STATE object.
      \n 
      See also: al_store_state, ALLEGRO_STATE_FLAGS
      \n+
      Examples:
      \n+
        \n+
      • ex_blend_bench.c
        • \n+
      • ex_blend2.cpp
        • \n+
      • nihgui.cpp
        • \n+
      \n 
      al_store_state
      \n-
      void al_store_state(ALLEGRO_STATE *state, int flags)
      \n+
      void al_store_state(ALLEGRO_STATE *state, int flags)
      \n 
      Source\n Code
      \n 
      Stores part of the state of the current thread in the given ALLEGRO_STATE object. The flags\n parameter can take any bit-combination of these flags:
      \n 
        \n@@ -257,30 +281,51 @@\n 
      • ALLEGRO_STATE_NEW_FILE_INTERFACE - new_file_interface
        • \n 
      • ALLEGRO_STATE_BITMAP - same as ALLEGRO_STATE_NEW_BITMAP_PARAMETERS\n and ALLEGRO_STATE_TARGET_BITMAP
        • \n 
      • ALLEGRO_STATE_ALL - all of the above
        • \n 
      \n 
      See also: al_restore_state,\n ALLEGRO_STATE
      \n+
      Examples:
      \n+
        \n+
      • ex_blend_bench.c
        • \n+
      • ex_blend2.cpp
        • \n+
      • nihgui.cpp
        • \n+
      \n 
      al_get_errno
      \n-
      int al_get_errno(void)\n-GETTER(allegro_errno, 0)
      \n+
      int al_get_errno(void)\n+GETTER(allegro_errno, 0)
      \n 
      Source\n Code
      \n 
      Some Allegro functions will set an error number as well as returning\n an error code. Call this function to retrieve the last error number set\n for the calling thread.
      \n+
      Examples:
      \n+
        \n+
      • ex_utf8.c
        • \n+
      \n 
      al_set_errno
      \n-
      void al_set_errno(int errnum)\n-SETTER(allegro_errno, errnum)
      \n+
      void al_set_errno(int errnum)\n+SETTER(allegro_errno, errnum)
      \n 
      Source\n Code
      \n 
      Set the error number for the calling thread.
      \n+
      Examples:
      \n+
        \n+
      • ex_curl.c
        • \n+
      • ex_utf8.c
        • \n+
      \n 
      \n Allegro version 5.2.10\n  - Last updated: 2025-01-09 13:52:42 UTC\n 
      \n \n \n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -48,15 +48,16 @@\n     * _\ba_\bl_\b__\br_\be_\bs_\bt_\bo_\br_\be_\b__\bs_\bt_\ba_\bt_\be\n     * _\ba_\bl_\b__\bs_\bt_\bo_\br_\be_\b__\bs_\bt_\ba_\bt_\be\n     * _\ba_\bl_\b__\bg_\be_\bt_\b__\be_\br_\br_\bn_\bo\n     * _\ba_\bl_\b__\bs_\be_\bt_\b__\be_\br_\br_\bn_\bo\n These functions are declared in the main Allegro header file:\n  #include \n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_S\bST\bTA\bAT\bTE\bE *\b**\b**\b**\b**\b**\b*\n-Source Code\n+typedef struct ALLEGRO_STATE ALLEGRO_STATE;\n+_\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Opaque type which is passed to _\ba_\bl_\b__\bs_\bt_\bo_\br_\be_\b__\bs_\bt_\ba_\bt_\be/_\ba_\bl_\b__\br_\be_\bs_\bt_\bo_\br_\be_\b__\bs_\bt_\ba_\bt_\be.\n The various state kept internally by Allegro can be displayed like this:\n   global\n       active system driver\n           current config\n   per thread\n       new bitmap params\n@@ -75,24 +76,33 @@\n In general, the only real global state is the active system driver. All other\n global state is per-thread, so if your application has multiple separate\n threads they never will interfere with each other. (Except if there are objects\n accessed by multiple threads of course. Usually you want to minimize that\n though and for the remaining cases use synchronization primitives described in\n the threads section or events described in the events section to control inter-\n thread communication.)\n+Examples:\n+    * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bb_\be_\bn_\bc_\bh_\b._\bc\n+    * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b2_\b._\bc_\bp_\bp\n+    * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_S\bST\bTA\bAT\bTE\bE_\b_F\bFL\bLA\bAG\bGS\bS *\b**\b**\b**\b**\b**\b*\n-Source Code\n+typedef enum ALLEGRO_STATE_FLAGS\n+_\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Flags which can be passed to _\ba_\bl_\b__\bs_\bt_\bo_\br_\be_\b__\bs_\bt_\ba_\bt_\be/_\ba_\bl_\b__\br_\be_\bs_\bt_\bo_\br_\be_\b__\bs_\bt_\ba_\bt_\be as bit\n combinations. See _\ba_\bl_\b__\bs_\bt_\bo_\br_\be_\b__\bs_\bt_\ba_\bt_\be for the list of flags.\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bes\bst\bto\bor\bre\be_\b_s\bst\bta\bat\bte\be *\b**\b**\b**\b**\b**\b*\n void al_restore_state(ALLEGRO_STATE const *state)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Restores part of the state of the current thread from the given _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bT_\bA_\bT_\bE\n object.\n See also: _\ba_\bl_\b__\bs_\bt_\bo_\br_\be_\b__\bs_\bt_\ba_\bt_\be, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bT_\bA_\bT_\bE_\b__\bF_\bL_\bA_\bG_\bS\n+Examples:\n+    * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bb_\be_\bn_\bc_\bh_\b._\bc\n+    * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b2_\b._\bc_\bp_\bp\n+    * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bst\bto\bor\bre\be_\b_s\bst\bta\bat\bte\be *\b**\b**\b**\b**\b**\b*\n void al_store_state(ALLEGRO_STATE *state, int flags)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Stores part of the state of the current thread in the given _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bT_\bA_\bT_\bE\n object. The flags parameter can take any bit-combination of these flags:\n     * ALLEGRO_STATE_NEW_DISPLAY_PARAMETERS - new_display_format,\n       new_display_refresh_rate, new_display_flags\n@@ -103,20 +113,29 @@\n     * ALLEGRO_STATE_TRANSFORM - current_transformation\n     * ALLEGRO_STATE_PROJECTION_TRANSFORM - current_projection_transformation\n     * ALLEGRO_STATE_NEW_FILE_INTERFACE - new_file_interface\n     * ALLEGRO_STATE_BITMAP - same as ALLEGRO_STATE_NEW_BITMAP_PARAMETERS and\n       ALLEGRO_STATE_TARGET_BITMAP\n     * ALLEGRO_STATE_ALL - all of the above\n See also: _\ba_\bl_\b__\br_\be_\bs_\bt_\bo_\br_\be_\b__\bs_\bt_\ba_\bt_\be, _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bT_\bA_\bT_\bE\n+Examples:\n+    * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b__\bb_\be_\bn_\bc_\bh_\b._\bc\n+    * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b2_\b._\bc_\bp_\bp\n+    * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_e\ber\brr\brn\bno\bo *\b**\b**\b**\b**\b**\b*\n int al_get_errno(void)\n GETTER(allegro_errno, 0)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Some Allegro functions will set an error number as well as returning an error\n code. Call this function to retrieve the last error number set for the calling\n thread.\n+Examples:\n+    * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_e\ber\brr\brn\bno\bo *\b**\b**\b**\b**\b**\b*\n void al_set_errno(int errnum)\n SETTER(allegro_errno, errnum)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the error number for the calling thread.\n+Examples:\n+    * _\be_\bx_\b__\bc_\bu_\br_\bl_\b._\bc\n+    * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/system.html", "source2": "./usr/share/doc/allegro5-doc/refman/system.html", "unified_diff": "@@ -232,64 +232,90 @@\n be the version of Allegro you compiled with, and B = xb.yb.zb.* be the\n version of Allegro found in the system shared library.
      \n 
      If you defined ALLEGRO_UNSTABLE before including Allegro\n headers, then version A is compatible with B only if xa.ya.za =\n xb.yb.zb. Otherwise, A is compatible with B only if xa.ya = xb.yb.
      \n 
      See also: al_init
      \n 
      al_init
      \n-
      Source Code
      \n+
      #define al_init()    (al_install_system(ALLEGRO_VERSION_INT, atexit))
      \n+
      Source\n+Code
      \n 
      Like al_install_system,\n but automatically passes in the version and uses the atexit function\n visible in the current binary.
      \n 
      \n 
      Note: It is typically wrong to call al_init anywhere except the final\n game binary. In particular, do not call it inside a shared library\n unless you know what you\u2019re doing. In those cases, it is better to call\n al_install_system either with a NULL atexit_ptr, or with a\n pointer to atexit provided by the user of this shared library.
      \n 
      \n 
      See also: al_install_system
      \n+
      Examples:
      \n+
        \n+
      • ex_audio_devices.c
        • \n+
      • ex_get_path.c
        • \n+
      • ex_monitorinfo.c
        • \n+
      \n 
      al_uninstall_system
      \n-
      void al_uninstall_system(void)
      \n+
      void al_uninstall_system(void)
      \n 
      Source\n Code
      \n 
      Closes down the Allegro system.
      \n 
      \n 
      Note: al_uninstall_system() can be called without a corresponding al_install_system call,\n e.g.\u00a0from atexit().
      \n 
      \n+
      Examples:
      \n+
        \n+
      • ex_opengl_pixel_shader.c
        • \n+
      • ex_icon2.c
        • \n+
      • ex_icon.c
        • \n+
      \n 
      al_is_system_installed
      \n-
      bool al_is_system_installed(void)
      \n+
      bool al_is_system_installed(void)
      \n 
      Source\n Code
      \n 
      Returns true if Allegro is initialized, otherwise returns false.
      \n+
      Examples:
      \n+
        \n+
      • common.c
        • \n+
      \n 
      al_get_allegro_version
      \n-
      uint32_t al_get_allegro_version(void)
      \n+
      uint32_t al_get_allegro_version(void)
      \n 
      Source\n Code
      \n 
      Returns the (compiled) version of the Allegro library, packed into a\n single integer as groups of 8 bits in the form\n (major << 24) | (minor << 16) | (revision << 8) | release.
      \n 
      You can use code like this to extract them:
      \n-
      uint32_t version = al_get_allegro_version();\n-int major = version >> 24;\n-int minor = (version >> 16) & 255;\n-int revision = (version >> 8) & 255;\n-int release = version & 255;
      \n+
      uint32_t version = al_get_allegro_version();\n+int major = version >> 24;\n+int minor = (version >> 16) & 255;\n+int revision = (version >> 8) & 255;\n+int release = version & 255;
      \n 
      The release number is 0 for an unofficial version and 1\n or greater for an official release. For example \u201c5.0.2[1]\u201d would be the\n (first) official 5.0.2 release while \u201c5.0.2[0]\u201d would be a compile of a\n version from the \u201c5.0.2\u201d branch before the official release.
      \n 
      al_get_standard_path
      \n-
      ALLEGRO_PATH *al_get_standard_path(int id)
      \n+
      ALLEGRO_PATH *al_get_standard_path(int id)
      \n 
      Source\n Code
      \n 
      Gets a system path, depending on the id parameter. Some\n of these paths may be affected by the organization and application name,\n so be sure to set those before calling this function.
      \n 
      The paths are not guaranteed to be unique (e.g., SETTINGS and DATA\n@@ -355,75 +381,99 @@\n \n 
      Returns NULL on failure. The returned path should be freed with al_destroy_path.
      \n 
      See also: al_set_app_name,\n al_set_org_name, al_destroy_path, al_set_exe_name
      \n+
      Examples:
      \n+
        \n+
      • ex_get_path.c
        • \n+
      • ex_physfs.c
        • \n+
      • ex_android.c
        • \n+
      \n 
      al_set_exe_name
      \n-
      void al_set_exe_name(char const *path)
      \n+
      void al_set_exe_name(char const *path)
      \n 
      Source\n Code
      \n 
      This override the executable name used by al_get_standard_path for\n ALLEGRO_EXENAME_PATH and ALLEGRO_RESOURCES_PATH.
      \n 
      One possibility where changing this can be useful is if you use the\n Python wrapper. Allegro would then by default think that the system\u2019s\n Python executable is the current executable - but you can set it to the\n .py file being executed instead.
      \n 
      Since: 5.0.6, 5.1.0
      \n 
      See also: al_get_standard_path
      \n+
      Examples:
      \n+
        \n+
      • ex_get_path.c
        • \n+
      \n 
      al_set_app_name
      \n-
      void al_set_app_name(const char *app_name)
      \n+
      void al_set_app_name(const char *app_name)
      \n 
      Source\n Code
      \n 
      Sets the global application name.
      \n 
      The application name is used by al_get_standard_path to\n build the full path to an application\u2019s files.
      \n 
      This function may be called before al_init or al_install_system.
      \n 
      See also: al_get_app_name,\n al_set_org_name
      \n+
      Examples:
      \n+
        \n+
      • ex_get_path.c
        • \n+
      \n 
      al_set_org_name
      \n-
      void al_set_org_name(const char *org_name)
      \n+
      void al_set_org_name(const char *org_name)
      \n 
      Source\n Code
      \n 
      Sets the global organization name.
      \n 
      The organization name is used by al_get_standard_path to\n build the full path to an application\u2019s files.
      \n 
      This function may be called before al_init or al_install_system.
      \n 
      See also: al_get_org_name,\n al_set_app_name
      \n+
      Examples:
      \n+
        \n+
      • ex_get_path.c
        • \n+
      \n 
      al_get_app_name
      \n-
      const char *al_get_app_name(void)
      \n+
      const char *al_get_app_name(void)
      \n 
      Source\n Code
      \n 
      Returns the global application name string.
      \n 
      See also: al_set_app_name
      \n 
      al_get_org_name
      \n-
      const char *al_get_org_name(void)
      \n+
      const char *al_get_org_name(void)
      \n 
      Source\n Code
      \n 
      Returns the global organization name string.
      \n 
      See also: al_set_org_name
      \n 
      al_get_system_config
      \n-
      ALLEGRO_CONFIG *al_get_system_config(void)
      \n+
      ALLEGRO_CONFIG *al_get_system_config(void)
      \n 
      Source\n Code
      \n 
      Returns the system configuration structure. The returned\n configuration should not be destroyed with al_destroy_config. This is\n mainly used for configuring Allegro and its addons. You may populate\n@@ -440,311 +490,318 @@\n 
      If multiple copies are found, then they are merged using al_merge_config_into.
      \n 
      The contents of this file are documented inside a prototypical\n allegro5.cfg that you can find in the root directory of the\n source distributions of Allegro. They are also reproduced below.
      \n 
      Note that Allegro will not look into that file unless you make a copy\n of it and place it next to your executable!
      \n-
      #\n-#  Configuration file for the Allegro 5 library.\n-#\n-#  This file should be either in the same directory as your program.\n-#\n-#  On Unix, this file may also be stored as ~/.allegro5rc or /etc/allegro5rc.\n-#  If multiple files exist, they will be merged, with values from more specific\n-#  files overriding the less specific files.\n-\n-[graphics]\n-\n-# Graphics driver.\n-# Can be 'default', 'opengl' or 'direct3d' (Windows only).\n-driver=default\n-\n-# Display configuration selection mode.\n-#\n-# Under Linux, it can be used to force the old GLX 1.2 way of choosing\n-# display settings or the new FBConfig method introduced with GLX 1.3.\n-#\n-# Under Windows, when using the OpenGL driver, setting it to old will\n-# use DescribePixelFormat and new will use wglGetPixelFormatAttribivARB\n-# (provided by WGL_ARB_pixel_format extension).\n-#\n-# Can be 'old' and 'new'. Default is 'new'.\n-config_selection=new\n-\n-# What method to use to detect legacy cards for the Direct3D backend of the\n-# primitives addon. Can be 'default', which means it'll check that the pixel\n-# shader version supported is below some value. 'force_legacy' will force it to\n-# detect as a legacy card. 'force_modern' will force it to detect is as a modern\n-# card.\n-prim_d3d_legacy_detection=default\n-\n-# For compatibility reasons, video bitmaps smaller than this size are\n-# backed by textures with this size. This is often no longer necessary\n-# on more modern systems, and should be set to < 16 if you're creating\n-# bitmaps smaller than this size. Note that on Android, this is ignored\n-# if smaller than 32.\n-min_bitmap_size=16\n-\n-[audio]\n-\n-# Driver can be 'default', 'openal', 'alsa', 'oss', 'pulseaudio' or 'directsound'\n-# depending on platform.\n-driver=default\n-\n-# Mixer quality can be 'linear' (default), 'cubic' (best), or 'point' (bad).\n-# default_mixer_quality=linear\n-\n-# The frequency to use for the default voice/mixer. Default: 44100.\n-# primary_voice_frequency=44100\n-# primary_mixer_frequency=44100\n-\n-# Can be 'int16', otherwise defaults to float32.\n-# primary_voice_depth=float32\n-# primary_mixer_depth=float32\n-\n-[oss]\n-\n-# You can skip probing for OSS4 driver by setting this option to 'yes'.\n-# Default is 'no'.\n-force_ver3=no\n-\n-# When OSS3 is used, you can choose a sound device here.\n-# Default is '/dev/dsp'.\n-device=/dev/dsp\n-\n-[alsa]\n-\n-# Set the ALSA sound device.\n-# Default is 'default'.\n-device=default\n-\n-# Set the ALSA capture device, e.g. hw:0,0\n-# Default is 'default'.\n-capture_device=default\n-\n-# Set the period size (in samples)\n-# Note that this is erroneously called 'buffer_size' for backwards\n-# compatibility.\n-buffer_size=32\n-\n-# Set the buffer size (in samples)\n-buffer_size2=2048\n-\n-[pulseaudio]\n-\n-# Set the buffer size (in samples)\n-buffer_size=1024\n-\n-[directsound]\n-\n-# Set the DirectSound buffer size (in samples)\n-buffer_size = 8192\n-\n-# Which window to attach the device to. Can be 'desktop', or 'foreground'. Try\n-# flipping this if there are issues initializing audio.\n-window = desktop\n-\n-[opengl]\n-\n-# If you want to support old OpenGL versions, you can make Allegro\n-# believe an older version than what you actually have is used with\n-# this key. This is only for testing/debugging purposes.\n-\n-# force_opengl_version = 1.2\n-\n-[opengl_disabled_extensions]\n-\n-# Any OpenGL extensions can be listed here to make Allegro report them\n-# as not available. The extensions used by Allegro itself if available\n-# are shown below - uncommenting them would disable them:\n-\n-# GL_ARB_texture_non_power_of_two=0\n-# GL_EXT_framebuffer_object=0\n-\n-[image]\n-\n-# Gamma handling of PNG files.\n-# A value of 0.0 means: Don't do any gamma correction.\n-# A value of -1.0 means: Use the value from the environment variable\n-# SCREEN_GAMMA (if available), otherwise fallback to a value of 2.2\n-# (a good guess for PC monitors, and the value for sRGB colourspace).\n-# Otherwise, the value is taken as-is.\n-png_screen_gamma = -1.0\n-\n-# Compression level for PNG files. Possible values: 0-9, "best", "fastest",\n-# "none" or "default" (a sane compromise between size and speed).\n-png_compression_level = default\n-\n-# Quality level for JPEG files. Possible values: 0-100\n-jpeg_quality_level = 75\n-\n-# Quality level for WebP files. Possible values: 0-100 or "lossless"\n-webp_quality_level = lossless\n-\n-[joystick]\n-\n-# Linux: Allegro normally searches for joystick device N at /dev/input/jsN.\n-# You can override the device file path on a per-device basis, like this.\n-\n-# device0=/dev/input/by-id/usb-blahblah-joystick\n-\n-# Windows: You can choose between the XINPUT or DIRECTINPUT driver for\n-# joysticks and force feedback joysticks. Xinput is the more modern\n-# system, but DirectInput has more force feedback capabilities for older\n-# joysticks.\n-driver=XINPUT\n-\n-# Windows: Use this to force an XInput DLL version, example "3" forces\n-# xinput1_3.dll. By default, the latest version is used.\n-\n-# force_xinput_version = 3\n-\n-[keyboard]\n-\n-# You can trap/untrap the mouse cursor within a window with a key combination\n-# of your choice, e.g. "Ctrl-G", "Shift-Ctrl-G", "Ctrl-LShift", "RWin".\n-# This feature currently only works on X11 and Windows.\n-\n-# toggle_mouse_grab_key = ScrollLock\n-\n-# By default, you can press Ctrl-Alt-Delete or Ctrl-Alt-End to quit Allegro\n-# programs. Set this to false to disable this feature. This only works on\n-# Linux.\n-\n-# enable_three_finger_exit = true\n-\n-# By default, pressing the LED toggling keys (e.g. CapsLock) will also toggle\n-# the LED on the keyboard. Setting this to false disable that connection.\n-# This can only be controled on non-X11 Linux.\n-\n-# enable_key_led_toggle = true\n-\n-\n-[trace]\n-# Comma-separated list of channels to log. Default is "all" which\n-# disables channel filtering. Some possible channels are:\n-# system,display,keyboard,opengl\n-# Channel names can be prefixed with - to exclude only those channels.\n-# Each addon and source-file can define additional channels though so\n-# there are more.\n-channels=all\n-\n-# Log-level. Can be one of debug, info, warn, error, none or empty.\n-# In debug builds if it is empty or unset, then the level is set to debug.\n-# In release builds if it is empty or unset, then the level is set to none.\n-# If not none, Allegro will write out the logs to an allegro.log file next to\n-# the binary. Use ALLEGRO_TRACE environment variable to control that file\n-# location. A special filename of - (dash) means logging to stdout.\n-# You can override this value via the ALLEGRO_TRACE_LEVEL environment variable.\n-level=\n-\n-# Set to 0 to disable line numbers in log files.\n-lines=1\n-\n-# Set to 0 to disable timestamps in log files.\n-timestamps=1\n-\n-# Set to 0 to disable function names in log files.\n-functions=1\n-\n-[x11]\n-# Can be fullscreen_only, always, never\n-bypass_compositor = fullscreen_only\n-\n-[xkeymap]\n-# Override X11 keycode. The below example maps X11 code 52 (Y) to Allegro\n-# code 26 (Z) and X11 code 29 (Z) to Allegro code 25 (Y).\n-# 52=26\n-# 29=25\n-\n-\n-[shader]\n-# If you want to support override version of the d3dx9_xx.dll library\n-# define this value.\n-# By default, latest installed version is used.\n-\n-# force_d3dx9_version = 36\n-\n-[ttf]\n-\n-# Set these to something other than 0 to override the default page sizes for TTF\n-# glyphs.\n-min_page_size = 0\n-max_page_size = 0\n-\n-# This entry contains characters that will be pre-catched during font loading.\n-# cache_text = a bcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ\n-\n-# Uncomment if you want only the characters in the cache_text entry to ever be drawn\n-# skip_cache_misses = true\n-\n-[osx]\n-\n-# If set to false, then Allegro will send ALLEGRO_EVENT_DISPLAY_HALT_DRAWING\n-# and ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING events when the user resizes a\n-# window. Drawing while resizing ("live resizing") has historically been buggy,\n-# so setting this to false allows you to opt out of this behavior and detect\n-# when the resize happens.\n-allow_live_resize = true\n-\n-[compatibility]\n-\n-# Prior to 5.2.4 on Windows you had to manually resize the display when\n-# showing the menu using the dialog addon. After 5.2.4 this is done\n-# automatically, but may break old code that handled this eventuality.\n-# Set this to false for such code.\n-automatic_menu_display_resize = true\n-\n-# On OSX outside an app bundle, on system init allegro manually promotes the process\n-# to a graphical application. This may be undesirable for console applications. Set\n-# this to false to disable this behavior.\n-osx_tell_dock_outside_bundle = true\n-\n-# To restore behavior of older code versions, specify this value to the\n-# Allegro version that had the desired old behavior.\n-# joystick_version = 5.2.9\n-# keyboard_version = 5.2.9\n-\n-# Prefer using DUMB rather than OpenMPT to decode module files.\n-acodec_prefer_dumb = false
      \n+
      #\n+# Configuration file for the Allegro 5 library.\n+#\n+# This file should be either in the same directory as your program.\n+#\n+# On Unix, this file may also be stored as ~/.allegro5rc or /etc/allegro5rc.\n+# If multiple files exist, they will be merged, with values from more specific\n+# files overriding the less specific files.\n+\n+[graphics]\n+\n+# Graphics driver.\n+# Can be 'default', 'opengl' or 'direct3d' (Windows only).\n+driver=default\n+\n+# Display configuration selection mode.\n+#\n+# Under Linux, it can be used to force the old GLX 1.2 way of choosing\n+# display settings or the new FBConfig method introduced with GLX 1.3.\n+#\n+# Under Windows, when using the OpenGL driver, setting it to old will\n+# use DescribePixelFormat and new will use wglGetPixelFormatAttribivARB\n+# (provided by WGL_ARB_pixel_format extension).\n+#\n+# Can be 'old' and 'new'. Default is 'new'.\n+config_selection=new\n+\n+# What method to use to detect legacy cards for the Direct3D backend of the\n+# primitives addon. Can be 'default', which means it'll check that the pixel\n+# shader version supported is below some value. 'force_legacy' will force it to\n+# detect as a legacy card. 'force_modern' will force it to detect is as a modern\n+# card.\n+prim_d3d_legacy_detection=default\n+\n+# For compatibility reasons, video bitmaps smaller than this size are\n+# backed by textures with this size. This is often no longer necessary\n+# on more modern systems, and should be set to < 16 if you're creating\n+# bitmaps smaller than this size. Note that on Android, this is ignored\n+# if smaller than 32.\n+min_bitmap_size=16\n+\n+[audio]\n+\n+# Driver can be 'default', 'openal', 'alsa', 'oss', 'pulseaudio' or 'directsound'\n+# depending on platform.\n+driver=default\n+\n+# Mixer quality can be 'linear' (default), 'cubic' (best), or 'point' (bad).\n+# default_mixer_quality=linear\n+\n+# The frequency to use for the default voice/mixer. Default: 44100.\n+# primary_voice_frequency=44100\n+# primary_mixer_frequency=44100\n+\n+# Can be 'int16', otherwise defaults to float32.\n+# primary_voice_depth=float32\n+# primary_mixer_depth=float32\n+\n+[oss]\n+\n+# You can skip probing for OSS4 driver by setting this option to 'yes'.\n+# Default is 'no'.\n+force_ver3=no\n+\n+# When OSS3 is used, you can choose a sound device here.\n+# Default is '/dev/dsp'.\n+device=/dev/dsp\n+\n+[alsa]\n+\n+# Set the ALSA sound device.\n+# Default is 'default'.\n+device=default\n+\n+# Set the ALSA capture device, e.g. hw:0,0\n+# Default is 'default'.\n+capture_device=default\n+\n+# Set the period size (in samples)\n+# Note that this is erroneously called 'buffer_size' for backwards\n+# compatibility.\n+buffer_size=32\n+\n+# Set the buffer size (in samples)\n+buffer_size2=2048\n+\n+[pulseaudio]\n+\n+# Set the buffer size (in samples)\n+buffer_size=1024\n+\n+[directsound]\n+\n+# Set the DirectSound buffer size (in samples)\n+buffer_size = 8192\n+\n+# Which window to attach the device to. Can be 'desktop', or 'foreground'. Try\n+# flipping this if there are issues initializing audio.\n+window = desktop\n+\n+[opengl]\n+\n+# If you want to support old OpenGL versions, you can make Allegro\n+# believe an older version than what you actually have is used with\n+# this key. This is only for testing/debugging purposes.\n+\n+# force_opengl_version = 1.2\n+\n+[opengl_disabled_extensions]\n+\n+# Any OpenGL extensions can be listed here to make Allegro report them\n+# as not available. The extensions used by Allegro itself if available\n+# are shown below - uncommenting them would disable them:\n+\n+# GL_ARB_texture_non_power_of_two=0\n+# GL_EXT_framebuffer_object=0\n+\n+[image]\n+\n+# Gamma handling of PNG files.\n+# A value of 0.0 means: Don't do any gamma correction.\n+# A value of -1.0 means: Use the value from the environment variable\n+# SCREEN_GAMMA (if available), otherwise fallback to a value of 2.2\n+# (a good guess for PC monitors, and the value for sRGB colourspace).\n+# Otherwise, the value is taken as-is.\n+png_screen_gamma = -1.0\n+\n+# Compression level for PNG files. Possible values: 0-9, "best", "fastest",\n+# "none" or "default" (a sane compromise between size and speed).\n+png_compression_level = default\n+\n+# Quality level for JPEG files. Possible values: 0-100\n+jpeg_quality_level = 75\n+\n+# Quality level for WebP files. Possible values: 0-100 or "lossless"\n+webp_quality_level = lossless\n+\n+[joystick]\n+\n+# Linux: Allegro normally searches for joystick device N at /dev/input/jsN.\n+# You can override the device file path on a per-device basis, like this.\n+\n+# device0=/dev/input/by-id/usb-blahblah-joystick\n+\n+# Windows: You can choose between the XINPUT or DIRECTINPUT driver for\n+# joysticks and force feedback joysticks. Xinput is the more modern\n+# system, but DirectInput has more force feedback capabilities for older\n+# joysticks.\n+driver=XINPUT\n+\n+# Windows: Use this to force an XInput DLL version, example "3" forces\n+# xinput1_3.dll. By default, the latest version is used.\n+\n+# force_xinput_version = 3\n+\n+[keyboard]\n+\n+# You can trap/untrap the mouse cursor within a window with a key combination\n+# of your choice, e.g. "Ctrl-G", "Shift-Ctrl-G", "Ctrl-LShift", "RWin".\n+# This feature currently only works on X11 and Windows.\n+\n+# toggle_mouse_grab_key = ScrollLock\n+\n+# By default, you can press Ctrl-Alt-Delete or Ctrl-Alt-End to quit Allegro\n+# programs. Set this to false to disable this feature. This only works on\n+# Linux.\n+\n+# enable_three_finger_exit = true\n+\n+# By default, pressing the LED toggling keys (e.g. CapsLock) will also toggle\n+# the LED on the keyboard. Setting this to false disable that connection.\n+# This can only be controled on non-X11 Linux.\n+\n+# enable_key_led_toggle = true\n+\n+\n+[trace]\n+# Comma-separated list of channels to log. Default is "all" which\n+# disables channel filtering. Some possible channels are:\n+# system,display,keyboard,opengl\n+# Channel names can be prefixed with - to exclude only those channels.\n+# Each addon and source-file can define additional channels though so\n+# there are more.\n+channels=all\n+\n+# Log-level. Can be one of debug, info, warn, error, none or empty.\n+# In debug builds if it is empty or unset, then the level is set to debug.\n+# In release builds if it is empty or unset, then the level is set to none.\n+# If not none, Allegro will write out the logs to an allegro.log file next to\n+# the binary. Use ALLEGRO_TRACE environment variable to control that file\n+# location. A special filename of - (dash) means logging to stdout.\n+# You can override this value via the ALLEGRO_TRACE_LEVEL environment variable.\n+level=\n+\n+# Set to 0 to disable line numbers in log files.\n+lines=1\n+\n+# Set to 0 to disable timestamps in log files.\n+timestamps=1\n+\n+# Set to 0 to disable function names in log files.\n+functions=1\n+\n+[x11]\n+# Can be fullscreen_only, always, never\n+bypass_compositor = fullscreen_only\n+\n+[xkeymap]\n+# Override X11 keycode. The below example maps X11 code 52 (Y) to Allegro\n+# code 26 (Z) and X11 code 29 (Z) to Allegro code 25 (Y).\n+# 52=26\n+# 29=25\n+\n+\n+[shader]\n+# If you want to support override version of the d3dx9_xx.dll library\n+# define this value.\n+# By default, latest installed version is used.\n+\n+# force_d3dx9_version = 36\n+\n+[ttf]\n+\n+# Set these to something other than 0 to override the default page sizes for TTF\n+# glyphs.\n+min_page_size = 0\n+max_page_size = 0\n+\n+# This entry contains characters that will be pre-catched during font loading.\n+# cache_text = a bcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ\n+\n+# Uncomment if you want only the characters in the cache_text entry to ever be drawn\n+# skip_cache_misses = true\n+\n+[osx]\n+\n+# If set to false, then Allegro will send ALLEGRO_EVENT_DISPLAY_HALT_DRAWING\n+# and ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING events when the user resizes a\n+# window. Drawing while resizing ("live resizing") has historically been buggy,\n+# so setting this to false allows you to opt out of this behavior and detect\n+# when the resize happens.\n+allow_live_resize = true\n+\n+[compatibility]\n+\n+# Prior to 5.2.4 on Windows you had to manually resize the display when\n+# showing the menu using the dialog addon. After 5.2.4 this is done\n+# automatically, but may break old code that handled this eventuality.\n+# Set this to false for such code.\n+automatic_menu_display_resize = true\n+\n+# On OSX outside an app bundle, on system init allegro manually promotes the process\n+# to a graphical application. This may be undesirable for console applications. Set\n+# this to false to disable this behavior.\n+osx_tell_dock_outside_bundle = true\n+\n+# To restore behavior of older code versions, specify this value to the\n+# Allegro version that had the desired old behavior.\n+# joystick_version = 5.2.9\n+# keyboard_version = 5.2.9\n+\n+# Prefer using DUMB rather than OpenMPT to decode module files.\n+acodec_prefer_dumb = false
      \n+

      Examples:

      \n+
        \n+
      • ex_resize2.c
        • \n+
      • ex_camera.c
        • \n+
      \n

      al_get_system_id

      \n-
      ALLEGRO_SYSTEM_ID al_get_system_id(void)
      \n+
      ALLEGRO_SYSTEM_ID al_get_system_id(void)
      \n

      Source\n Code

      \n

      Returns the platform that Allegro is running on.

      \n

      Since: 5.2.5

      \n

      See also: ALLEGRO_SYSTEM_ID

      \n

      al_register_assert_handler

      \n-
      void al_register_assert_handler(void (*handler)(char const *expr,\n-   char const *file, int line, char const *func))
      \n+
      void al_register_assert_handler(void (*handler)(char const *expr,\n+   char const *file, int line, char const *func))
      \n

      Source\n Code

      \n

      Register a function to be called when an internal Allegro assertion\n fails. Pass NULL to reset to the default behaviour, which is to do\n whatever the standard assert() macro does.

      \n

      Since: 5.0.6, 5.1.0

      \n

      al_register_trace_handler

      \n-
      void al_register_trace_handler(void (*handler)(char const *))
      \n+
      void al_register_trace_handler(void (*handler)(char const *))
      \n

      Source\n Code

      \n

      Register a callback which is called whenever Allegro writes something\n to its log files. The default logging to allegro.log is disabled while\n this callback is active. Pass NULL to revert to the default logging.

      \n

      This function may be called prior to al_install_system.

      \n

      See the example allegro5.cfg for documentation on how to configure\n the used debug channels, logging levels and trace format.

      \n

      Since: 5.1.5

      \n

      al_get_cpu_count

      \n-
      int al_get_cpu_count(void)
      \n+
      int al_get_cpu_count(void)
      \n

      Source\n Code

      \n

      Returns the number of CPU cores that the system Allegro is running on\n has and which could be detected, or a negative number if detection\n failed. Even if a positive number is returned, it might be that it is\n not correct. For example, Allegro running on a virtual machine will\n@@ -763,15 +820,15 @@\n

      Since: 5.1.12

      \n

      Examples:

      \n
        \n
      • ex_cpu.c
        • \n
      \n

      al_get_ram_size

      \n-
      int al_get_ram_size(void)
      \n+
      int al_get_ram_size(void)
      \n

      Source\n Code

      \n

      Returns the size in MB of the random access memory that the system\n Allegro is running on has and which could be detected, or a negative\n number if detection failed. Even if a positive number is returned, it\n might be that it is not correct. For example, Allegro running on a\n@@ -791,15 +848,18 @@\n

      Since: 5.1.12

      \n

      Examples:

      \n
        \n
      • ex_cpu.c
        • \n
      \n

      ALLEGRO_SYSTEM_ID

      \n-

      Source Code

      \n+
      enum ALLEGRO_SYSTEM_ID {
      \n+

      Source\n+Code

      \n

      The system Allegro is running on.

      \n
        \n
      • ALLEGRO_SYSTEM_ID_UNKNOWN - Unknown system.
        • \n
      • ALLEGRO_SYSTEM_ID_XGLX - Xglx
        • \n
      • ALLEGRO_SYSTEM_ID_WINDOWS - Windows
        • \n
      • ALLEGRO_SYSTEM_ID_MACOSX - macOS
        • \n
      • ALLEGRO_SYSTEM_ID_ANDROID - Android
        • \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -80,33 +80,44 @@\n version of Allegro you compiled with, and B = xb.yb.zb.* be the version of\n Allegro found in the system shared library.\n If you defined ALLEGRO_UNSTABLE before including Allegro headers, then version\n A is compatible with B only if xa.ya.za = xb.yb.zb. Otherwise, A is compatible\n with B only if xa.ya = xb.yb.\n See also: _\ba_\bl_\b__\bi_\bn_\bi_\bt\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bni\bit\bt *\b**\b**\b**\b**\b**\b*\n-Source Code\n+#define al_init() (al_install_system(ALLEGRO_VERSION_INT, atexit))\n+_\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bs_\by_\bs_\bt_\be_\bm, but automatically passes in the version and uses the\n atexit function visible in the current binary.\n Note: It is typically wrong to call al_init anywhere except the final\n game binary. In particular, do not call it inside a shared library\n unless you know what you\u2019re doing. In those cases, it is better to\n call al_install_system either with a NULL atexit_ptr, or with a\n pointer to atexit provided by the user of this shared library.\n See also: _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bs_\by_\bs_\bt_\be_\bm\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bd_\be_\bv_\bi_\bc_\be_\bs_\b._\bc\n+ * _\be_\bx_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bn_\bi_\bt_\bo_\br_\bi_\bn_\bf_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bni\bin\bns\bst\bta\bal\bll\bl_\b_s\bsy\bys\bst\bte\bem\bm *\b**\b**\b**\b**\b**\b*\n void al_uninstall_system(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Closes down the Allegro system.\n Note: al_uninstall_system() can be called without a corresponding\n _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bs_\by_\bs_\bt_\be_\bm call, e.g.\u00a0from atexit().\n+Examples:\n+ * _\be_\bx_\b__\bo_\bp_\be_\bn_\bg_\bl_\b__\bp_\bi_\bx_\be_\bl_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bi_\bc_\bo_\bn_\b2_\b._\bc\n+ * _\be_\bx_\b__\bi_\bc_\bo_\bn_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_s\bsy\bys\bst\bte\bem\bm_\b_i\bin\bns\bst\bta\bal\bll\ble\bed\bd *\b**\b**\b**\b**\b**\b*\n bool al_is_system_installed(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if Allegro is initialized, otherwise returns false.\n+Examples:\n+ * _\bc_\bo_\bm_\bm_\bo_\bn_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bal\bll\ble\beg\bgr\bro\bo_\b_v\bve\ber\brs\bsi\bio\bon\bn *\b**\b**\b**\b**\b**\b*\n uint32_t al_get_allegro_version(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the (compiled) version of the Allegro library, packed into a single\n integer as groups of 8 bits in the form (major << 24) | (minor << 16) |\n (revision << 8) | release.\n You can use code like this to extract them:\n@@ -167,41 +178,51 @@\n path will usually not be present on the file system, so make sure to\n create it before writing to it.\n ALLEGRO_EXENAME_PATH\n The full path to the executable.\n Returns NULL on failure. The returned path should be freed with\n _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bp_\ba_\bt_\bh.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\ba_\bp_\bp_\b__\bn_\ba_\bm_\be, _\ba_\bl_\b__\bs_\be_\bt_\b__\bo_\br_\bg_\b__\bn_\ba_\bm_\be, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bp_\ba_\bt_\bh, _\ba_\bl_\b__\bs_\be_\bt_\b__\be_\bx_\be_\b__\bn_\ba_\bm_\be\n+Examples:\n+ * _\be_\bx_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b._\bc\n+ * _\be_\bx_\b__\bp_\bh_\by_\bs_\bf_\bs_\b._\bc\n+ * _\be_\bx_\b__\ba_\bn_\bd_\br_\bo_\bi_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_e\bex\bxe\be_\b_n\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n void al_set_exe_name(char const *path)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This override the executable name used by _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd_\b__\bp_\ba_\bt_\bh for\n ALLEGRO_EXENAME_PATH and ALLEGRO_RESOURCES_PATH.\n One possibility where changing this can be useful is if you use the Python\n wrapper. Allegro would then by default think that the system\u2019s Python\n executable is the current executable - but you can set it to the .py file being\n executed instead.\n Since: 5.0.6, 5.1.0\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd_\b__\bp_\ba_\bt_\bh\n+Examples:\n+ * _\be_\bx_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_a\bap\bpp\bp_\b_n\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n void al_set_app_name(const char *app_name)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets the global application name.\n The application name is used by _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd_\b__\bp_\ba_\bt_\bh to build the full path to\n an application\u2019s files.\n This function may be called before _\ba_\bl_\b__\bi_\bn_\bi_\bt or _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bs_\by_\bs_\bt_\be_\bm.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\ba_\bp_\bp_\b__\bn_\ba_\bm_\be, _\ba_\bl_\b__\bs_\be_\bt_\b__\bo_\br_\bg_\b__\bn_\ba_\bm_\be\n+Examples:\n+ * _\be_\bx_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_o\bor\brg\bg_\b_n\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n void al_set_org_name(const char *org_name)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets the global organization name.\n The organization name is used by _\ba_\bl_\b__\bg_\be_\bt_\b__\bs_\bt_\ba_\bn_\bd_\ba_\br_\bd_\b__\bp_\ba_\bt_\bh to build the full path to\n an application\u2019s files.\n This function may be called before _\ba_\bl_\b__\bi_\bn_\bi_\bt or _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bs_\by_\bs_\bt_\be_\bm.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bo_\br_\bg_\b__\bn_\ba_\bm_\be, _\ba_\bl_\b__\bs_\be_\bt_\b__\ba_\bp_\bp_\b__\bn_\ba_\bm_\be\n+Examples:\n+ * _\be_\bx_\b__\bg_\be_\bt_\b__\bp_\ba_\bt_\bh_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_a\bap\bpp\bp_\b_n\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n const char *al_get_app_name(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the global application name string.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\ba_\bp_\bp_\b__\bn_\ba_\bm_\be\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_o\bor\brg\bg_\b_n\bna\bam\bme\be *\b**\b**\b**\b**\b**\b*\n const char *al_get_org_name(void)\n@@ -492,14 +513,17 @@\n # To restore behavior of older code versions, specify this value to the\n # Allegro version that had the desired old behavior.\n # joystick_version = 5.2.9\n # keyboard_version = 5.2.9\n \n # Prefer using DUMB rather than OpenMPT to decode module files.\n acodec_prefer_dumb = false\n+Examples:\n+ * _\be_\bx_\b__\br_\be_\bs_\bi_\bz_\be_\b2_\b._\bc\n+ * _\be_\bx_\b__\bc_\ba_\bm_\be_\br_\ba_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_s\bsy\bys\bst\bte\bem\bm_\b_i\bid\bd *\b**\b**\b**\b**\b**\b*\n ALLEGRO_SYSTEM_ID al_get_system_id(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the platform that Allegro is running on.\n Since: 5.2.5\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bS_\bY_\bS_\bT_\bE_\bM_\b__\bI_\bD\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\beg\bgi\bis\bst\bte\ber\br_\b_a\bas\bss\bse\ber\brt\bt_\b_h\bha\ban\bnd\bdl\ble\ber\br *\b**\b**\b**\b**\b**\b*\n@@ -556,15 +580,16 @@\n bad idea to make your program exclusive to systems for which this function\n returns a certain \u201cdesirable\u201d number.\n This function may be called prior to _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bs_\by_\bs_\bt_\be_\bm or _\ba_\bl_\b__\bi_\bn_\bi_\bt.\n Since: 5.1.12\n Examples:\n * _\be_\bx_\b__\bc_\bp_\bu_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_S\bSY\bYS\bST\bTE\bEM\bM_\b_I\bID\bD *\b**\b**\b**\b**\b**\b*\n-Source Code\n+enum ALLEGRO_SYSTEM_ID {\n+_\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n The system Allegro is running on.\n * ALLEGRO_SYSTEM_ID_UNKNOWN - Unknown system.\n * ALLEGRO_SYSTEM_ID_XGLX - Xglx\n * ALLEGRO_SYSTEM_ID_WINDOWS - Windows\n * ALLEGRO_SYSTEM_ID_MACOSX - macOS\n * ALLEGRO_SYSTEM_ID_ANDROID - Android\n * ALLEGRO_SYSTEM_ID_IPHONE - iOS\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/threads.html", "source2": "./usr/share/doc/allegro5-doc/refman/threads.html", "unified_diff": "@@ -228,39 +228,69 @@\n 
         #include <allegro5/allegro.h>
        \n

        ALLEGRO_THREAD

        \n 
        typedef struct ALLEGRO_THREAD ALLEGRO_THREAD;
        \n

        Source\n Code

        \n

        An opaque structure representing a thread.

        \n+

        Examples:

        \n+
          \n+
        • ex_threads.c
          • \n+
        • ex_threads2.c
          • \n+
        • ex_loading_thread.c
          • \n+
        \n

        ALLEGRO_MUTEX

        \n 
        typedef struct ALLEGRO_MUTEX ALLEGRO_MUTEX;
        \n

        Source\n Code

        \n

        An opaque structure representing a mutex.

        \n+

        Examples:

        \n+
          \n+
        • ex_threads2.c
          • \n+
        • ex_loading_thread.c
          • \n+
        \n

        ALLEGRO_COND

        \n 
        typedef struct ALLEGRO_COND ALLEGRO_COND;
        \n

        Source\n Code

        \n

        An opaque structure representing a condition variable.

        \n+

        Examples:

        \n+
          \n+
        • ex_threads2.c
          • \n+
        \n

        al_create_thread

        \n 
        ALLEGRO_THREAD *al_create_thread(\n    void *(*proc)(ALLEGRO_THREAD *thread, void *arg), void *arg)
        \n

        Source\n Code

        \n

        Spawn a new thread which begins executing proc. The new\n thread is passed its own thread handle and the value\n arg.

        \n

        Returns a pointer to the thread on success. Otherwise, returns NULL\n if there was an error.

        \n

        See also: al_start_thread,\n al_join_thread.

        \n+

        Examples:

        \n+
          \n+
        • ex_threads.c
          • \n+
        • ex_threads2.c
          • \n+
        • ex_loading_thread.c
          • \n+
        \n al_create_thread_with_stacksize\n 
        ALLEGRO_THREAD *al_create_thread_with_stacksize(\n    void *(*proc)(ALLEGRO_THREAD *thread, void *arg), void *arg, size_t stacksize)
        \n

        Source\n Code

        \n@@ -284,14 +314,23 @@\n Code

        \n

        When a thread is created, it is initially in a suspended state.\n Calling al_start_thread will\n start its actual execution.

        \n

        Starting a thread which has already been started does nothing.

        \n

        See also: al_create_thread.

        \n+

        Examples:

        \n+
          \n+
        • ex_threads.c
          • \n+
        • ex_threads2.c
          • \n+
        • ex_loading_thread.c
          • \n+
        \n

        al_join_thread

        \n 
        void al_join_thread(ALLEGRO_THREAD *thread, void **ret_value)
        \n

        Source\n Code

        \n

        Wait for the thread to finish executing. This implicitly calls al_set_thread_should_stop\n@@ -300,24 +339,38 @@\n returned by the thread function will be stored at the location pointed\n to by ret_value.

        \n

        See also: al_set_thread_should_stop,\n al_get_thread_should_stop,\n al_destroy_thread.

        \n+

        Examples:

        \n+
          \n+
        • ex_threads.c
          • \n+
        • ex_threads2.c
          • \n+
        • ex_loading_thread.c
          • \n+
        \n

        al_set_thread_should_stop

        \n 
        void al_set_thread_should_stop(ALLEGRO_THREAD *thread)
        \n

        Source\n Code

        \n

        Set the flag to indicate thread should stop. Returns\n immediately.

        \n

        See also: al_join_thread,\n al_get_thread_should_stop.

        \n+

        Examples:

        \n+
          \n+
        • ex_threads2.c
          • \n+
        \n

        al_get_thread_should_stop

        \n 
        bool al_get_thread_should_stop(ALLEGRO_THREAD *thread)
        \n

        Source\n Code

        \n

        Check if another thread is waiting for thread to stop.\n Threads which run in a loop should check this periodically and act on it\n@@ -328,25 +381,41 @@\n on this thread.

        \n

        See also: al_join_thread,\n al_set_thread_should_stop.

        \n
        \n

        Note: We don\u2019t support forceful killing of threads.

        \n
        \n+

        Examples:

        \n+
          \n+
        • ex_threads2.c
          • \n+
        • ex_loading_thread.c
          • \n+
        \n

        al_destroy_thread

        \n 
        void al_destroy_thread(ALLEGRO_THREAD *thread)
        \n

        Source\n Code

        \n

        Free the resources used by a thread. Implicitly performs al_join_thread on the thread if\n it hasn\u2019t been done already.

        \n

        Does nothing if thread is NULL.

        \n

        See also: al_join_thread.

        \n+

        Examples:

        \n+
          \n+
        • ex_threads.c
          • \n+
        • ex_threads2.c
          • \n+
        • ex_native_filechooser.c
          • \n+
        \n

        al_run_detached_thread

        \n 
        void al_run_detached_thread(void *(*proc)(void *arg), void *arg)
        \n

        Source\n Code

        \n

        Runs the passed function in its own thread, with arg\n passed to it as only parameter. This is similar to calling Source\n Code

        \n

        Create the mutex object (a mutual exclusion device). The mutex may or\n may not support \u201crecursive\u201d locking.

        \n

        Returns the mutex on success or NULL on error.

        \n

        See also: al_create_mutex_recursive.

        \n+

        Examples:

        \n+
          \n+
        • ex_threads2.c
          • \n+
        • ex_loading_thread.c
          • \n+
        \n

        al_create_mutex_recursive

        \n 
        ALLEGRO_MUTEX *al_create_mutex_recursive(void)
        \n

        Source\n Code

        \n

        Create the mutex object (a mutual exclusion device), with support for\n \u201crecursive\u201d locking. That is, the mutex will count the number of times\n@@ -394,40 +470,64 @@\n href=\"threads.html#al_create_mutex_recursive\">al_create_mutex_recursive.\n In the former case, the behaviour is undefined; the most likely\n behaviour is deadlock. In the latter case, the count in the mutex will\n be incremented and the call will return immediately.

        \n

        See also: al_unlock_mutex.

        \n

        We don\u2019t yet have al_mutex_trylock.

        \n+

        Examples:

        \n+
          \n+
        • ex_threads2.c
          • \n+
        • ex_loading_thread.c
          • \n+
        \n

        al_unlock_mutex

        \n 
        void al_unlock_mutex(ALLEGRO_MUTEX *mutex)
        \n

        Source\n Code

        \n

        Release the lock on mutex if the calling thread holds\n the lock on it.

        \n

        If the calling thread doesn\u2019t hold the lock, or if the mutex is not\n locked, undefined behaviour results.

        \n

        See also: al_lock_mutex.

        \n+

        Examples:

        \n+
          \n+
        • ex_threads2.c
          • \n+
        • ex_loading_thread.c
          • \n+
        \n

        al_destroy_mutex

        \n 
        void al_destroy_mutex(ALLEGRO_MUTEX *mutex)
        \n

        Source\n Code

        \n

        Free the resources used by the mutex. The mutex should be unlocked.\n Destroying a locked mutex results in undefined behaviour.

        \n

        Does nothing if mutex is NULL.

        \n+

        Examples:

        \n+
          \n+
        • ex_loading_thread.c
          • \n+
        \n

        al_create_cond

        \n 
        ALLEGRO_COND *al_create_cond(void)
        \n

        Source\n Code

        \n

        Create a condition variable.

        \n

        Returns the condition value on success or NULL on\n error.

        \n+

        Examples:

        \n+
          \n+
        • ex_threads2.c
          • \n+
        \n

        al_destroy_cond

        \n 
        void al_destroy_cond(ALLEGRO_COND *cond)
        \n

        Source\n Code

        \n

        Destroy a condition variable.

        \n

        Destroying a condition variable which has threads block on it results\n@@ -457,14 +557,19 @@\n signalled). If multiple threads are blocked on the condition variable,\n the condition may no longer be true by the time the second and later\n threads are unblocked. Remember not to unlock the mutex prematurely.

        \n

        See also: al_wait_cond_until, al_broadcast_cond, al_signal_cond.

        \n+

        Examples:

        \n+
          \n+
        • ex_threads2.c
          • \n+
        \n

        al_wait_cond_until

        \n 
        int al_wait_cond_until(ALLEGRO_COND *cond, ALLEGRO_MUTEX *mutex,\n    const ALLEGRO_TIMEOUT *timeout)
        \n

        Source\n Code

        \n

        Like al_wait_cond but the\n@@ -483,14 +588,19 @@\n

        See also: al_signal_cond.

        \n
        \n

        Note: The pthreads spec says to lock the mutex associated\n with cond before signalling for predictable scheduling\n behaviour.

        \n
        \n+

        Examples:

        \n+
          \n+
        • ex_threads2.c
          • \n+
        \n

        al_signal_cond

        \n 
        void al_signal_cond(ALLEGRO_COND *cond)
        \n

        Source\n Code

        \n

        Unblock at least one thread waiting on a condition variable.

        \n

        Generally you should use \n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_T\bTH\bHR\bRE\bEA\bAD\bD *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_THREAD ALLEGRO_THREAD;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An opaque structure representing a thread.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b._\bc\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_M\bMU\bUT\bTE\bEX\bX *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_MUTEX ALLEGRO_MUTEX;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An opaque structure representing a mutex.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_C\bCO\bON\bND\bD *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_COND ALLEGRO_COND;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An opaque structure representing a condition variable.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_t\bth\bhr\bre\bea\bad\bd *\b**\b**\b**\b**\b**\b*\n ALLEGRO_THREAD *al_create_thread(\n void *(*proc)(ALLEGRO_THREAD *thread, void *arg), void *arg)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Spawn a new thread which begins executing proc. The new thread is passed its\n own thread handle and the value arg.\n Returns a pointer to the thread on success. Otherwise, returns NULL if there\n was an error.\n See also: _\ba_\bl_\b__\bs_\bt_\ba_\br_\bt_\b__\bt_\bh_\br_\be_\ba_\bd, _\ba_\bl_\b__\bj_\bo_\bi_\bn_\b__\bt_\bh_\br_\be_\ba_\bd.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b._\bc\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_t\bth\bhr\bre\bea\bad\bd_\b_w\bwi\bit\bth\bh_\b_s\bst\bta\bac\bck\bks\bsi\biz\bze\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_THREAD *al_create_thread_with_stacksize(\n void *(*proc)(ALLEGRO_THREAD *thread, void *arg), void *arg, size_t\n stacksize)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Spawn a new thread with the give stacksize in bytes which begins executing\n proc. The new thread is passed its own thread handle and the value arg.\n@@ -111,58 +124,78 @@\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bst\bta\bar\brt\bt_\b_t\bth\bhr\bre\bea\bad\bd *\b**\b**\b**\b**\b**\b*\n void al_start_thread(ALLEGRO_THREAD *thread)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n When a thread is created, it is initially in a suspended state. Calling\n _\ba_\bl_\b__\bs_\bt_\ba_\br_\bt_\b__\bt_\bh_\br_\be_\ba_\bd will start its actual execution.\n Starting a thread which has already been started does nothing.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bt_\bh_\br_\be_\ba_\bd.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b._\bc\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_j\bjo\boi\bin\bn_\b_t\bth\bhr\bre\bea\bad\bd *\b**\b**\b**\b**\b**\b*\n void al_join_thread(ALLEGRO_THREAD *thread, void **ret_value)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Wait for the thread to finish executing. This implicitly calls\n _\ba_\bl_\b__\bs_\be_\bt_\b__\bt_\bh_\br_\be_\ba_\bd_\b__\bs_\bh_\bo_\bu_\bl_\bd_\b__\bs_\bt_\bo_\bp first.\n If ret_value is non-NULL, the value returned by the thread function will be\n stored at the location pointed to by ret_value.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bt_\bh_\br_\be_\ba_\bd_\b__\bs_\bh_\bo_\bu_\bl_\bd_\b__\bs_\bt_\bo_\bp, _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\bh_\br_\be_\ba_\bd_\b__\bs_\bh_\bo_\bu_\bl_\bd_\b__\bs_\bt_\bo_\bp,\n _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bt_\bh_\br_\be_\ba_\bd.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b._\bc\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_t\bth\bhr\bre\bea\bad\bd_\b_s\bsh\bho\bou\bul\bld\bd_\b_s\bst\bto\bop\bp *\b**\b**\b**\b**\b**\b*\n void al_set_thread_should_stop(ALLEGRO_THREAD *thread)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the flag to indicate thread should stop. Returns immediately.\n See also: _\ba_\bl_\b__\bj_\bo_\bi_\bn_\b__\bt_\bh_\br_\be_\ba_\bd, _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\bh_\br_\be_\ba_\bd_\b__\bs_\bh_\bo_\bu_\bl_\bd_\b__\bs_\bt_\bo_\bp.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_t\bth\bhr\bre\bea\bad\bd_\b_s\bsh\bho\bou\bul\bld\bd_\b_s\bst\bto\bop\bp *\b**\b**\b**\b**\b**\b*\n bool al_get_thread_should_stop(ALLEGRO_THREAD *thread)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Check if another thread is waiting for thread to stop. Threads which run in a\n loop should check this periodically and act on it when convenient.\n Returns true if another thread has called _\ba_\bl_\b__\bj_\bo_\bi_\bn_\b__\bt_\bh_\br_\be_\ba_\bd or\n _\ba_\bl_\b__\bs_\be_\bt_\b__\bt_\bh_\br_\be_\ba_\bd_\b__\bs_\bh_\bo_\bu_\bl_\bd_\b__\bs_\bt_\bo_\bp on this thread.\n See also: _\ba_\bl_\b__\bj_\bo_\bi_\bn_\b__\bt_\bh_\br_\be_\ba_\bd, _\ba_\bl_\b__\bs_\be_\bt_\b__\bt_\bh_\br_\be_\ba_\bd_\b__\bs_\bh_\bo_\bu_\bl_\bd_\b__\bs_\bt_\bo_\bp.\n N\bNo\bot\bte\be:\b: We don\u2019t support forceful killing of threads.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_t\bth\bhr\bre\bea\bad\bd *\b**\b**\b**\b**\b**\b*\n void al_destroy_thread(ALLEGRO_THREAD *thread)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Free the resources used by a thread. Implicitly performs _\ba_\bl_\b__\bj_\bo_\bi_\bn_\b__\bt_\bh_\br_\be_\ba_\bd on the\n thread if it hasn\u2019t been done already.\n Does nothing if thread is NULL.\n See also: _\ba_\bl_\b__\bj_\bo_\bi_\bn_\b__\bt_\bh_\br_\be_\ba_\bd.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b._\bc\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n+ * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bru\bun\bn_\b_d\bde\bet\bta\bac\bch\bhe\bed\bd_\b_t\bth\bhr\bre\bea\bad\bd *\b**\b**\b**\b**\b**\b*\n void al_run_detached_thread(void *(*proc)(void *arg), void *arg)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Runs the passed function in its own thread, with arg passed to it as only\n parameter. This is similar to calling _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bt_\bh_\br_\be_\ba_\bd, _\ba_\bl_\b__\bs_\bt_\ba_\br_\bt_\b__\bt_\bh_\br_\be_\ba_\bd and\n (after the thread has finished) _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bt_\bh_\br_\be_\ba_\bd - but you don\u2019t have the\n possibility of ever calling _\ba_\bl_\b__\bj_\bo_\bi_\bn_\b__\bt_\bh_\br_\be_\ba_\bd on the thread.\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_m\bmu\but\bte\bex\bx *\b**\b**\b**\b**\b**\b*\n ALLEGRO_MUTEX *al_create_mutex(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create the mutex object (a mutual exclusion device). The mutex may or may not\n support \u201crecursive\u201d locking.\n Returns the mutex on success or NULL on error.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bm_\bu_\bt_\be_\bx_\b__\br_\be_\bc_\bu_\br_\bs_\bi_\bv_\be.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_m\bmu\but\bte\bex\bx_\b_r\bre\bec\bcu\bur\brs\bsi\biv\bve\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_MUTEX *al_create_mutex_recursive(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create the mutex object (a mutual exclusion device), with support for\n \u201crecursive\u201d locking. That is, the mutex will count the number of times it has\n been locked by the same thread. If the caller tries to acquire a lock on the\n mutex when it already holds the lock then the count is incremented. The mutex\n@@ -177,32 +210,42 @@\n If the mutex is already locked by the calling thread, then the behaviour\n depends on whether the mutex was created with _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bm_\bu_\bt_\be_\bx or\n _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bm_\bu_\bt_\be_\bx_\b__\br_\be_\bc_\bu_\br_\bs_\bi_\bv_\be. In the former case, the behaviour is undefined; the\n most likely behaviour is deadlock. In the latter case, the count in the mutex\n will be incremented and the call will return immediately.\n See also: _\ba_\bl_\b__\bu_\bn_\bl_\bo_\bc_\bk_\b__\bm_\bu_\bt_\be_\bx.\n W\bWe\be d\bdo\bon\bn?\b\u2019t\bt y\bye\bet\bt h\bha\bav\bve\be a\bal\bl_\b_m\bmu\but\bte\bex\bx_\b_t\btr\bry\byl\blo\boc\bck\bk.\b.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bnl\blo\boc\bck\bk_\b_m\bmu\but\bte\bex\bx *\b**\b**\b**\b**\b**\b*\n void al_unlock_mutex(ALLEGRO_MUTEX *mutex)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Release the lock on mutex if the calling thread holds the lock on it.\n If the calling thread doesn\u2019t hold the lock, or if the mutex is not locked,\n undefined behaviour results.\n See also: _\ba_\bl_\b__\bl_\bo_\bc_\bk_\b__\bm_\bu_\bt_\be_\bx.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_m\bmu\but\bte\bex\bx *\b**\b**\b**\b**\b**\b*\n void al_destroy_mutex(ALLEGRO_MUTEX *mutex)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Free the resources used by the mutex. The mutex should be unlocked. Destroying\n a locked mutex results in undefined behaviour.\n Does nothing if mutex is NULL.\n+Examples:\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_c\bco\bon\bnd\bd *\b**\b**\b**\b**\b**\b*\n ALLEGRO_COND *al_create_cond(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a condition variable.\n Returns the condition value on success or NULL on error.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_c\bco\bon\bnd\bd *\b**\b**\b**\b**\b**\b*\n void al_destroy_cond(ALLEGRO_COND *cond)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Destroy a condition variable.\n Destroying a condition variable which has threads block on it results in\n undefined behaviour.\n Does nothing if cond is NULL.\n@@ -223,14 +266,16 @@\n The mutex should be locked before checking the condition, and should be\n rechecked _\ba_\bl_\b__\bw_\ba_\bi_\bt_\b__\bc_\bo_\bn_\bd returns. _\ba_\bl_\b__\bw_\ba_\bi_\bt_\b__\bc_\bo_\bn_\bd can return for other reasons than\n the condition becoming true (e.g.\u00a0the process was signalled). If multiple\n threads are blocked on the condition variable, the condition may no longer be\n true by the time the second and later threads are unblocked. Remember not to\n unlock the mutex prematurely.\n See also: _\ba_\bl_\b__\bw_\ba_\bi_\bt_\b__\bc_\bo_\bn_\bd_\b__\bu_\bn_\bt_\bi_\bl, _\ba_\bl_\b__\bb_\br_\bo_\ba_\bd_\bc_\ba_\bs_\bt_\b__\bc_\bo_\bn_\bd, _\ba_\bl_\b__\bs_\bi_\bg_\bn_\ba_\bl_\b__\bc_\bo_\bn_\bd.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_w\bwa\bai\bit\bt_\b_c\bco\bon\bnd\bd_\b_u\bun\bnt\bti\bil\bl *\b**\b**\b**\b**\b**\b*\n int al_wait_cond_until(ALLEGRO_COND *cond, ALLEGRO_MUTEX *mutex,\n const ALLEGRO_TIMEOUT *timeout)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bw_\ba_\bi_\bt_\b__\bc_\bo_\bn_\bd but the call can return if the absolute time passes timeout\n before the condition is signalled.\n Returns zero on success, non-zero if the call timed out.\n@@ -240,14 +285,16 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Unblock all threads currently waiting on a condition variable. That is,\n broadcast that some condition which those threads were waiting for has become\n true.\n See also: _\ba_\bl_\b__\bs_\bi_\bg_\bn_\ba_\bl_\b__\bc_\bo_\bn_\bd.\n N\bNo\bot\bte\be:\b: The pthreads spec says to lock the mutex associated with cond\n before signalling for predictable scheduling behaviour.\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b2_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bsi\big\bgn\bna\bal\bl_\b_c\bco\bon\bnd\bd *\b**\b**\b**\b**\b**\b*\n void al_signal_cond(ALLEGRO_COND *cond)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Unblock at least one thread waiting on a condition variable.\n Generally you should use _\ba_\bl_\b__\bb_\br_\bo_\ba_\bd_\bc_\ba_\bs_\bt_\b__\bc_\bo_\bn_\bd but _\ba_\bl_\b__\bs_\bi_\bg_\bn_\ba_\bl_\b__\bc_\bo_\bn_\bd may be more\n efficient when it\u2019s applicable.\n See also: _\ba_\bl_\b__\bb_\br_\bo_\ba_\bd_\bc_\ba_\bs_\bt_\b__\bc_\bo_\bn_\bd.\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/time.html", "source2": "./usr/share/doc/allegro5-doc/refman/time.html", "unified_diff": "@@ -187,47 +187,75 @@\n 

        typedef struct ALLEGRO_TIMEOUT ALLEGRO_TIMEOUT;
        \n

        Source\n Code

        \n

        Represent a timeout value. The size of the structure is known so it\n can be statically allocated. The contents are private.

        \n

        See also: al_init_timeout

        \n+

        Examples:

        \n+
          \n+
        • ex_timedwait.c
          • \n+
        \n

        al_get_time

        \n 
        double al_get_time(void)
        \n

        Source\n Code

        \n

        Return the number of seconds since the Allegro library was\n initialised. The return value is undefined if Allegro is uninitialised.\n The resolution depends on the used driver, but typically can be in the\n order of microseconds.

        \n+

        Examples:

        \n+
          \n+
        • ex_convert.c
          • \n+
        • ex_d3d.cpp
          • \n+
        • ex_enet_server.c
          • \n+
        \n

        al_init_timeout

        \n 
        void al_init_timeout(ALLEGRO_TIMEOUT *timeout, double seconds)
        \n

        Source\n Code

        \n

        Set timeout value of some number of seconds after the function\n call.

        \n

        For compatibility with all platforms, seconds must be\n 2,147,483.647 seconds or less.

        \n

        See also: ALLEGRO_TIMEOUT, al_wait_for_event_until

        \n+

        Examples:

        \n+
          \n+
        • ex_timedwait.c
          • \n+
        \n

        al_rest

        \n 
        void al_rest(double seconds)
        \n

        Source\n Code

        \n

        Waits for the specified number of seconds. This tells the system to\n pause the current thread for the given amount of time. With some\n operating systems, the accuracy can be in the order of 10ms. That is,\n even

        \n 
        al_rest(0.000001)
        \n

        might pause for something like 10ms. Also see the section on Timer\n routines for easier ways to time your program without using up all\n CPU.

        \n+

        Examples:

        \n+
          \n+
        • ex_keyboard_focus.c
          • \n+
        • ex_timer_pause.c
          • \n+
        • ex_mouse_focus.c
          • \n+
        \n

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

        \n \n \n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -51,30 +51,42 @@\n #include \n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_T\bTI\bIM\bME\bEO\bOU\bUT\bT *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_TIMEOUT ALLEGRO_TIMEOUT;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Represent a timeout value. The size of the structure is known so it can be\n statically allocated. The contents are private.\n See also: _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bt_\bi_\bm_\be_\bo_\bu_\bt\n+Examples:\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\bd_\bw_\ba_\bi_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_t\bti\bim\bme\be *\b**\b**\b**\b**\b**\b*\n double al_get_time(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the number of seconds since the Allegro library was initialised. The\n return value is undefined if Allegro is uninitialised. The resolution depends\n on the used driver, but typically can be in the order of microseconds.\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bn_\bv_\be_\br_\bt_\b._\bc\n+ * _\be_\bx_\b__\bd_\b3_\bd_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bs_\be_\br_\bv_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bni\bit\bt_\b_t\bti\bim\bme\beo\bou\but\bt *\b**\b**\b**\b**\b**\b*\n void al_init_timeout(ALLEGRO_TIMEOUT *timeout, double seconds)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set timeout value of some number of seconds after the function call.\n For compatibility with all platforms, seconds must be 2,147,483.647 seconds or\n less.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bT_\bI_\bM_\bE_\bO_\bU_\bT, _\ba_\bl_\b__\bw_\ba_\bi_\bt_\b__\bf_\bo_\br_\b__\be_\bv_\be_\bn_\bt_\b__\bu_\bn_\bt_\bi_\bl\n+Examples:\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\bd_\bw_\ba_\bi_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bes\bst\bt *\b**\b**\b**\b**\b**\b*\n void al_rest(double seconds)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Waits for the specified number of seconds. This tells the system to pause the\n current thread for the given amount of time. With some operating systems, the\n accuracy can be in the order of 10ms. That is, even\n al_rest(0.000001)\n might pause for something like 10ms. Also see the section on Timer routines for\n easier ways to time your program without using up all CPU.\n+Examples:\n+ * _\be_\bx_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b__\bp_\ba_\bu_\bs_\be_\b._\bc\n+ * _\be_\bx_\b__\bm_\bo_\bu_\bs_\be_\b__\bf_\bo_\bc_\bu_\bs_\b._\bc\n Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/timer.html", "source2": "./usr/share/doc/allegro5-doc/refman/timer.html", "unified_diff": "@@ -213,14 +213,23 @@\n 
         #include <allegro5/allegro.h>
        \n

        ALLEGRO_TIMER

        \n 
        typedef struct ALLEGRO_TIMER ALLEGRO_TIMER;
        \n

        Source\n Code

        \n

        This is an abstract data type representing a timer object.

        \n+

        Examples:

        \n+
          \n+
        • ex_enet_server.c
          • \n+
        • ex_timer_pause.c
          • \n+
        • ex_user_events.c
          • \n+
        \n

        ALLEGRO_USECS_TO_SECS

        \n 
        #define ALLEGRO_USECS_TO_SECS(x)      ((x) / 1000000.0)
        \n

        Source\n Code

        \n

        Convert microseconds to seconds.

        \n

        ALLEGRO_MSECS_TO_SECS

        \n@@ -231,14 +240,19 @@\n

        Convert milliseconds to seconds.

        \n

        ALLEGRO_BPS_TO_SECS

        \n 
        #define ALLEGRO_BPS_TO_SECS(x)        (1.0 / (x))
        \n

        Source\n Code

        \n

        Convert beats per second to seconds.

        \n+

        Examples:

        \n+
          \n+
        • ex_prim.c
          • \n+
        \n

        ALLEGRO_BPM_TO_SECS

        \n 
        #define ALLEGRO_BPM_TO_SECS(x)        (60.0 / (x))
        \n

        Source\n Code

        \n

        Convert beats per minute to seconds.

        \n

        al_create_timer

        \n@@ -253,51 +267,85 @@\n href=\"timer.html#al_start_timer\">al_start_timer before ALLEGRO_EVENT_TIMER events\n are sent.

        \n

        Usage note: typical granularity is on the order of microseconds, but\n with some drivers might only be milliseconds.

        \n

        See also: al_start_timer, al_destroy_timer

        \n+

        Examples:

        \n+
          \n+
        • ex_enet_server.c
          • \n+
        • ex_timer_pause.c
          • \n+
        • ex_user_events.c
          • \n+
        \n

        al_start_timer

        \n 
        void al_start_timer(ALLEGRO_TIMER *timer)
        \n

        Source\n Code

        \n

        Start the timer specified. From then, the timer\u2019s counter will\n increment at a constant rate, and it will begin generating events.\n Starting a timer that is already started does nothing. Starting a timer\n that was stopped will reset the timer\u2019s counter, effectively restarting\n the timer from the beginning.

        \n

        See also: al_stop_timer, al_get_timer_started, al_resume_timer

        \n+

        Examples:

        \n+
          \n+
        • ex_enet_server.c
          • \n+
        • ex_timer_pause.c
          • \n+
        • ex_user_events.c
          • \n+
        \n

        al_resume_timer

        \n 
        void al_resume_timer(ALLEGRO_TIMER *timer)
        \n

        Source\n Code

        \n

        Resume the timer specified. From then, the timer\u2019s counter will\n increment at a constant rate, and it will begin generating events.\n Resuming a timer that is already started does nothing. Resuming a\n stopped timer will not reset the timer\u2019s counter (unlike al_start_timer).

        \n

        See also: al_start_timer, al_stop_timer, al_get_timer_started

        \n+

        Examples:

        \n+
          \n+
        • ex_timer_pause.c
          • \n+
        • ex_native_filechooser.c
          • \n+
        \n

        al_stop_timer

        \n 
        void al_stop_timer(ALLEGRO_TIMER *timer)
        \n

        Source\n Code

        \n

        Stop the timer specified. The timer\u2019s counter will stop incrementing\n and it will stop generating events. Stopping a timer that is already\n stopped does nothing.

        \n

        See also: al_start_timer, al_get_timer_started, al_resume_timer

        \n+

        Examples:

        \n+
          \n+
        • ex_timer_pause.c
          • \n+
        • ex_android.c
          • \n+
        • ex_projection2.c
          • \n+
        \n

        al_get_timer_started

        \n 
        bool al_get_timer_started(const ALLEGRO_TIMER *timer)
        \n

        Source\n Code

        \n

        Return true if the timer specified is currently started.

        \n

        al_destroy_timer

        \n@@ -307,34 +355,53 @@\n Code

        \n

        Uninstall the timer specified. If the timer is started, it will\n automatically be stopped before uninstallation. It will also\n automatically unregister the timer with any event queues.

        \n

        Does nothing if passed the NULL pointer.

        \n

        See also: al_create_timer

        \n+

        Examples:

        \n+
          \n+
        • ex_timer_pause.c
          • \n+
        • ex_user_events.c
          • \n+
        • ex_noframe.c
          • \n+
        \n

        al_get_timer_count

        \n 
        int64_t al_get_timer_count(const ALLEGRO_TIMER *timer)
        \n

        Source\n Code

        \n

        Return the timer\u2019s counter value. The timer can be started or\n stopped.

        \n

        See also: al_set_timer_count

        \n+

        Examples:

        \n+
          \n+
        • ex_menu.c
          • \n+
        \n

        al_set_timer_count

        \n 
        void al_set_timer_count(ALLEGRO_TIMER *timer, int64_t new_count)
        \n

        Source\n Code

        \n

        Set the timer\u2019s counter value. The timer can be started or stopped.\n The count value may be positive or negative, but will always be\n incremented by +1 at each tick.

        \n

        See also: al_get_timer_count, al_add_timer_count

        \n+

        Examples:

        \n+
          \n+
        • ex_audio_timer.c
          • \n+
        \n

        al_add_timer_count

        \n 
        void al_add_timer_count(ALLEGRO_TIMER *timer, int64_t diff)
        \n

        Source\n Code

        \n

        Add diff to the timer\u2019s counter value. This is similar to\n writing:

        \n@@ -362,22 +429,36 @@\n incremented when it is started. This can be done when the timer is\n started or stopped. If the timer is currently running, it is made to\n look as though the speed change occurred precisely at the last tick.

        \n

        speed_secs has exactly the same meaning as with al_create_timer.

        \n

        See also: al_get_timer_speed

        \n+

        Examples:

        \n+
          \n+
        • ex_audio_timer.c
          • \n+
        \n

        al_get_timer_event_source

        \n 
        ALLEGRO_EVENT_SOURCE *al_get_timer_event_source(ALLEGRO_TIMER *timer)
        \n

        Source\n Code

        \n

        Retrieve the associated event source. Timers will generate events of\n type ALLEGRO_EVENT_TIMER.

        \n+

        Examples:

        \n+
          \n+
        • ex_enet_server.c
          • \n+
        • ex_timer_pause.c
          • \n+
        • ex_user_events.c
          • \n+
        \n

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

        \n \n \n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -62,87 +62,116 @@\n * _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\bi_\bm_\be_\br_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be\n These functions are declared in the main Allegro header file:\n #include \n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_T\bTI\bIM\bME\bER\bR *\b**\b**\b**\b**\b**\b*\n typedef struct ALLEGRO_TIMER ALLEGRO_TIMER;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This is an abstract data type representing a timer object.\n+Examples:\n+ * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bs_\be_\br_\bv_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b__\bp_\ba_\bu_\bs_\be_\b._\bc\n+ * _\be_\bx_\b__\bu_\bs_\be_\br_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_U\bUS\bSE\bEC\bCS\bS_\b_T\bTO\bO_\b_S\bSE\bEC\bCS\bS *\b**\b**\b**\b**\b**\b*\n #define ALLEGRO_USECS_TO_SECS(x) ((x) / 1000000.0)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert microseconds to seconds.\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_M\bMS\bSE\bEC\bCS\bS_\b_T\bTO\bO_\b_S\bSE\bEC\bCS\bS *\b**\b**\b**\b**\b**\b*\n #define ALLEGRO_MSECS_TO_SECS(x) ((x) / 1000.0)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert milliseconds to seconds.\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_B\bBP\bPS\bS_\b_T\bTO\bO_\b_S\bSE\bEC\bCS\bS *\b**\b**\b**\b**\b**\b*\n #define ALLEGRO_BPS_TO_SECS(x) (1.0 / (x))\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert beats per second to seconds.\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_B\bBP\bPM\bM_\b_T\bTO\bO_\b_S\bSE\bEC\bCS\bS *\b**\b**\b**\b**\b**\b*\n #define ALLEGRO_BPM_TO_SECS(x) (60.0 / (x))\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Convert beats per minute to seconds.\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcr\bre\bea\bat\bte\be_\b_t\bti\bim\bme\ber\br *\b**\b**\b**\b**\b**\b*\n ALLEGRO_TIMER *al_create_timer(double speed_secs)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Allocates and initializes a timer. If successful, a pointer to a new timer\n object is returned, otherwise NULL is returned. s\bsp\bpe\bee\bed\bd_\b_s\bse\bec\bcs\bs is in seconds per\n \u201ctick\u201d, and must be positive. The new timer is initially stopped and needs to\n be started with _\ba_\bl_\b__\bs_\bt_\ba_\br_\bt_\b__\bt_\bi_\bm_\be_\br before _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bT_\bI_\bM_\bE_\bR events are sent.\n Usage note: typical granularity is on the order of microseconds, but with some\n drivers might only be milliseconds.\n See also: _\ba_\bl_\b__\bs_\bt_\ba_\br_\bt_\b__\bt_\bi_\bm_\be_\br, _\ba_\bl_\b__\bd_\be_\bs_\bt_\br_\bo_\by_\b__\bt_\bi_\bm_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bs_\be_\br_\bv_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b__\bp_\ba_\bu_\bs_\be_\b._\bc\n+ * _\be_\bx_\b__\bu_\bs_\be_\br_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bst\bta\bar\brt\bt_\b_t\bti\bim\bme\ber\br *\b**\b**\b**\b**\b**\b*\n void al_start_timer(ALLEGRO_TIMER *timer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Start the timer specified. From then, the timer\u2019s counter will increment at a\n constant rate, and it will begin generating events. Starting a timer that is\n already started does nothing. Starting a timer that was stopped will reset the\n timer\u2019s counter, effectively restarting the timer from the beginning.\n See also: _\ba_\bl_\b__\bs_\bt_\bo_\bp_\b__\bt_\bi_\bm_\be_\br, _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\bi_\bm_\be_\br_\b__\bs_\bt_\ba_\br_\bt_\be_\bd, _\ba_\bl_\b__\br_\be_\bs_\bu_\bm_\be_\b__\bt_\bi_\bm_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bs_\be_\br_\bv_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b__\bp_\ba_\bu_\bs_\be_\b._\bc\n+ * _\be_\bx_\b__\bu_\bs_\be_\br_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bes\bsu\bum\bme\be_\b_t\bti\bim\bme\ber\br *\b**\b**\b**\b**\b**\b*\n void al_resume_timer(ALLEGRO_TIMER *timer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Resume the timer specified. From then, the timer\u2019s counter will increment at a\n constant rate, and it will begin generating events. Resuming a timer that is\n already started does nothing. Resuming a stopped timer will not reset the\n timer\u2019s counter (unlike _\ba_\bl_\b__\bs_\bt_\ba_\br_\bt_\b__\bt_\bi_\bm_\be_\br).\n See also: _\ba_\bl_\b__\bs_\bt_\ba_\br_\bt_\b__\bt_\bi_\bm_\be_\br, _\ba_\bl_\b__\bs_\bt_\bo_\bp_\b__\bt_\bi_\bm_\be_\br, _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\bi_\bm_\be_\br_\b__\bs_\bt_\ba_\br_\bt_\be_\bd\n+Examples:\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b__\bp_\ba_\bu_\bs_\be_\b._\bc\n+ * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bst\bto\bop\bp_\b_t\bti\bim\bme\ber\br *\b**\b**\b**\b**\b**\b*\n void al_stop_timer(ALLEGRO_TIMER *timer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Stop the timer specified. The timer\u2019s counter will stop incrementing and it\n will stop generating events. Stopping a timer that is already stopped does\n nothing.\n See also: _\ba_\bl_\b__\bs_\bt_\ba_\br_\bt_\b__\bt_\bi_\bm_\be_\br, _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\bi_\bm_\be_\br_\b__\bs_\bt_\ba_\br_\bt_\be_\bd, _\ba_\bl_\b__\br_\be_\bs_\bu_\bm_\be_\b__\bt_\bi_\bm_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b__\bp_\ba_\bu_\bs_\be_\b._\bc\n+ * _\be_\bx_\b__\ba_\bn_\bd_\br_\bo_\bi_\bd_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b2_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_t\bti\bim\bme\ber\br_\b_s\bst\bta\bar\brt\bte\bed\bd *\b**\b**\b**\b**\b**\b*\n bool al_get_timer_started(const ALLEGRO_TIMER *timer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return true if the timer specified is currently started.\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_d\bde\bes\bst\btr\bro\boy\by_\b_t\bti\bim\bme\ber\br *\b**\b**\b**\b**\b**\b*\n void al_destroy_timer(ALLEGRO_TIMER *timer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Uninstall the timer specified. If the timer is started, it will automatically\n be stopped before uninstallation. It will also automatically unregister the\n timer with any event queues.\n Does nothing if passed the NULL pointer.\n See also: _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bt_\bi_\bm_\be_\br\n+Examples:\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b__\bp_\ba_\bu_\bs_\be_\b._\bc\n+ * _\be_\bx_\b__\bu_\bs_\be_\br_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n+ * _\be_\bx_\b__\bn_\bo_\bf_\br_\ba_\bm_\be_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_t\bti\bim\bme\ber\br_\b_c\bco\bou\bun\bnt\bt *\b**\b**\b**\b**\b**\b*\n int64_t al_get_timer_count(const ALLEGRO_TIMER *timer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the timer\u2019s counter value. The timer can be started or stopped.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bt_\bi_\bm_\be_\br_\b__\bc_\bo_\bu_\bn_\bt\n+Examples:\n+ * _\be_\bx_\b__\bm_\be_\bn_\bu_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_t\bti\bim\bme\ber\br_\b_c\bco\bou\bun\bnt\bt *\b**\b**\b**\b**\b**\b*\n void al_set_timer_count(ALLEGRO_TIMER *timer, int64_t new_count)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the timer\u2019s counter value. The timer can be started or stopped. The count\n value may be positive or negative, but will always be incremented by +1 at each\n tick.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\bi_\bm_\be_\br_\b__\bc_\bo_\bu_\bn_\bt, _\ba_\bl_\b__\ba_\bd_\bd_\b__\bt_\bi_\bm_\be_\br_\b__\bc_\bo_\bu_\bn_\bt\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bt_\bi_\bm_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_a\bad\bdd\bd_\b_t\bti\bim\bme\ber\br_\b_c\bco\bou\bun\bnt\bt *\b**\b**\b**\b**\b**\b*\n void al_add_timer_count(ALLEGRO_TIMER *timer, int64_t diff)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Add d\bdi\bif\bff\bf to the timer\u2019s counter value. This is similar to writing:\n al_set_timer_count(timer, al_get_timer_count(timer) + diff);\n except that the addition is performed atomically, so no ticks will be lost.\n See also: _\ba_\bl_\b__\bs_\be_\bt_\b__\bt_\bi_\bm_\be_\br_\b__\bc_\bo_\bu_\bn_\bt\n@@ -157,13 +186,19 @@\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Set the timer\u2019s speed, i.e.\u00a0the rate at which its counter will be incremented\n when it is started. This can be done when the timer is started or stopped. If\n the timer is currently running, it is made to look as though the speed change\n occurred precisely at the last tick.\n s\bsp\bpe\bee\bed\bd_\b_s\bse\bec\bcs\bs has exactly the same meaning as with _\ba_\bl_\b__\bc_\br_\be_\ba_\bt_\be_\b__\bt_\bi_\bm_\be_\br.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bt_\bi_\bm_\be_\br_\b__\bs_\bp_\be_\be_\bd\n+Examples:\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bt_\bi_\bm_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_t\bti\bim\bme\ber\br_\b_e\bev\bve\ben\bnt\bt_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_EVENT_SOURCE *al_get_timer_event_source(ALLEGRO_TIMER *timer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Retrieve the associated event source. Timers will generate events of type\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bT_\bI_\bM_\bE_\bR.\n+Examples:\n+ * _\be_\bx_\b__\be_\bn_\be_\bt_\b__\bs_\be_\br_\bv_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bt_\bi_\bm_\be_\br_\b__\bp_\ba_\bu_\bs_\be_\b._\bc\n+ * _\be_\bx_\b__\bu_\bs_\be_\br_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/touch.html", "source2": "./usr/share/doc/allegro5-doc/refman/touch.html", "unified_diff": "@@ -294,14 +294,23 @@\n href=\"https://github.com/liballeg/allegro5/blob/master/src/touch_input.c#L43\">Source\n Code

        \n

        Install a touch input driver, returning true if successful. If a\n touch input driver was already installed, returns true immediately.

        \n

        Since: 5.1.0

        \n

        See also: al_uninstall_touch_input

        \n+

        Examples:

        \n+
          \n+
        • common.c
          • \n+
        • ex_touch_input.c
          • \n+
        • ex_lockbitmap.c
          • \n+
        \n

        al_uninstall_touch_input

        \n 
        void al_uninstall_touch_input(void)
        \n

        Source\n Code

        \n

        Uninstalls the active touch input driver. If no touch input driver\n was active, this function does nothing.

        \n@@ -314,14 +323,23 @@\n

        Source\n Code

        \n

        Returns true if al_install_touch_input was\n called successfully.

        \n

        Since: 5.1.0

        \n+

        Examples:

        \n+
          \n+
        • ex_lockbitmap.c
          • \n+
        • ex_haiku.c
          • \n+
        • ex_prim_shader.c
          • \n+
        \n

        al_get_touch_input_state

        \n 
        void al_get_touch_input_state(ALLEGRO_TOUCH_INPUT_STATE *ret_state)
        \n

        Source\n Code

        \n

        Gets the current touch input state. The touch information is copied\n into the : Seems of limited value, as touch input tends to have\n different semantics compared to mouse input.

        \n \n

        See also: ALLEGRO_MOUSE_EMULATION_MODE,\n al_get_mouse_emulation_mode.

        \n+

        Examples:

        \n+
          \n+
        • ex_native_filechooser.c
          • \n+
        \n

        al_get_mouse_emulation_mode

        \n 
        int al_get_mouse_emulation_mode(void)
        \n

        Source\n Code

        \n

        Returns the kind of mouse emulation which the touch input subsystem\n is set to perform.

        \n@@ -371,14 +394,23 @@\n

        Returns the global touch input event source. This event source\n generates touch input\n events.

        \n

        Since: 5.1.0

        \n

        See also: ALLEGRO_EVENT_SOURCE, al_register_event_source

        \n+

        Examples:

        \n+
          \n+
        • ex_touch_input.c
          • \n+
        • ex_android.c
          • \n+
        • ex_polygon.c
          • \n+
        \n al_get_touch_input_mouse_emulation_event_source\n 
        ALLEGRO_EVENT_SOURCE *al_get_touch_input_mouse_emulation_event_source(void)
        \n

        Source\n Code

        \n

        Returns the global touch input event source for emulated mouse\n@@ -390,14 +422,23 @@\n href=\"events.html#al_register_event_source\">al_register_event_source

        \n

        Since: 5.1.0

        \n
        \n

        Unstable\n API: Seems of limited value, as touch input tends to have\n different semantics compared to mouse input.

        \n
        \n+

        Examples:

        \n+
          \n+
        • ex_lockbitmap.c
          • \n+
        • ex_haiku.c
          • \n+
        • ex_prim_shader.c
          • \n+
        \n

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

        \n \n \n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -110,41 +110,51 @@\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bns\bst\bta\bal\bll\bl_\b_t\bto\bou\buc\bch\bh_\b_i\bin\bnp\bpu\but\bt *\b**\b**\b**\b**\b**\b*\n bool al_install_touch_input(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Install a touch input driver, returning true if successful. If a touch input\n driver was already installed, returns true immediately.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bu_\bn_\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bt_\bo_\bu_\bc_\bh_\b__\bi_\bn_\bp_\bu_\bt\n+Examples:\n+ * _\bc_\bo_\bm_\bm_\bo_\bn_\b._\bc\n+ * _\be_\bx_\b__\bt_\bo_\bu_\bc_\bh_\b__\bi_\bn_\bp_\bu_\bt_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\bc_\bk_\bb_\bi_\bt_\bm_\ba_\bp_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_u\bun\bni\bin\bns\bst\bta\bal\bll\bl_\b_t\bto\bou\buc\bch\bh_\b_i\bin\bnp\bpu\but\bt *\b**\b**\b**\b**\b**\b*\n void al_uninstall_touch_input(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Uninstalls the active touch input driver. If no touch input driver was active,\n this function does nothing.\n This function is automatically called when Allegro is shut down.\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bt_\bo_\bu_\bc_\bh_\b__\bi_\bn_\bp_\bu_\bt\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_t\bto\bou\buc\bch\bh_\b_i\bin\bnp\bpu\but\bt_\b_i\bin\bns\bst\bta\bal\bll\ble\bed\bd *\b**\b**\b**\b**\b**\b*\n bool al_is_touch_input_installed(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if _\ba_\bl_\b__\bi_\bn_\bs_\bt_\ba_\bl_\bl_\b__\bt_\bo_\bu_\bc_\bh_\b__\bi_\bn_\bp_\bu_\bt was called successfully.\n Since: 5.1.0\n+Examples:\n+ * _\be_\bx_\b__\bl_\bo_\bc_\bk_\bb_\bi_\bt_\bm_\ba_\bp_\b._\bc\n+ * _\be_\bx_\b__\bh_\ba_\bi_\bk_\bu_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_t\bto\bou\buc\bch\bh_\b_i\bin\bnp\bpu\but\bt_\b_s\bst\bta\bat\bte\be *\b**\b**\b**\b**\b**\b*\n void al_get_touch_input_state(ALLEGRO_TOUCH_INPUT_STATE *ret_state)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Gets the current touch input state. The touch information is copied into the\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bT_\bO_\bU_\bC_\bH_\b__\bI_\bN_\bP_\bU_\bT_\b__\bS_\bT_\bA_\bT_\bE you provide to this function.\n Since: 5.1.0\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_e\bem\bmu\bul\bla\bat\bti\bio\bon\bn_\b_m\bmo\bod\bde\be *\b**\b**\b**\b**\b**\b*\n void al_set_mouse_emulation_mode(int mode)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets the kind of mouse emulation for the touch input subsystem to perform.\n Since: 5.1.0\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: Seems of limited value, as touch input tends to have\n different semantics compared to mouse input.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bM_\bO_\bU_\bS_\bE_\b__\bE_\bM_\bU_\bL_\bA_\bT_\bI_\bO_\bN_\b__\bM_\bO_\bD_\bE, _\ba_\bl_\b__\bg_\be_\bt_\b__\bm_\bo_\bu_\bs_\be_\b__\be_\bm_\bu_\bl_\ba_\bt_\bi_\bo_\bn_\b__\bm_\bo_\bd_\be.\n+Examples:\n+ * _\be_\bx_\b__\bn_\ba_\bt_\bi_\bv_\be_\b__\bf_\bi_\bl_\be_\bc_\bh_\bo_\bo_\bs_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_m\bmo\bou\bus\bse\be_\b_e\bem\bmu\bul\bla\bat\bti\bio\bon\bn_\b_m\bmo\bod\bde\be *\b**\b**\b**\b**\b**\b*\n int al_get_mouse_emulation_mode(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the kind of mouse emulation which the touch input subsystem is set to\n perform.\n Since: 5.1.0\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: Seems of limited value, as touch input tends to have\n@@ -153,17 +163,25 @@\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_t\bto\bou\buc\bch\bh_\b_i\bin\bnp\bpu\but\bt_\b_e\bev\bve\ben\bnt\bt_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_EVENT_SOURCE *al_get_touch_input_event_source(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the global touch input event source. This event source generates _\bt_\bo_\bu_\bc_\bh\n _\bi_\bn_\bp_\bu_\bt_\b _\be_\bv_\be_\bn_\bt_\bs.\n Since: 5.1.0\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bS_\bO_\bU_\bR_\bC_\bE, _\ba_\bl_\b__\br_\be_\bg_\bi_\bs_\bt_\be_\br_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be\n+Examples:\n+ * _\be_\bx_\b__\bt_\bo_\bu_\bc_\bh_\b__\bi_\bn_\bp_\bu_\bt_\b._\bc\n+ * _\be_\bx_\b__\ba_\bn_\bd_\br_\bo_\bi_\bd_\b._\bc\n+ * _\be_\bx_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_t\bto\bou\buc\bch\bh_\b_i\bin\bnp\bpu\but\bt_\b_m\bmo\bou\bus\bse\be_\b_e\bem\bmu\bul\bla\bat\bti\bio\bon\bn_\b_e\bev\bve\ben\bnt\bt_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_EVENT_SOURCE *al_get_touch_input_mouse_emulation_event_source(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the global touch input event source for emulated mouse events. This\n event source generates _\be_\bm_\bu_\bl_\ba_\bt_\be_\bd_\b _\bm_\bo_\bu_\bs_\be_\b _\be_\bv_\be_\bn_\bt_\bs that are based on touch events.\n See also: _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bS_\bO_\bU_\bR_\bC_\bE, _\ba_\bl_\b__\br_\be_\bg_\bi_\bs_\bt_\be_\br_\b__\be_\bv_\be_\bn_\bt_\b__\bs_\bo_\bu_\br_\bc_\be\n Since: 5.1.0\n _\bU\bU_\bn\bn_\bs\bs_\bt\bt_\ba\ba_\bb\bb_\bl\bl_\be\be_\b _\bA\bA_\bP\bP_\bI\bI:\b: Seems of limited value, as touch input tends to have\n different semantics compared to mouse input.\n+Examples:\n+ * _\be_\bx_\b__\bl_\bo_\bc_\bk_\bb_\bi_\bt_\bm_\ba_\bp_\b._\bc\n+ * _\be_\bx_\b__\bh_\ba_\bi_\bk_\bu_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc\n Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/transformations.html", "source2": "./usr/share/doc/allegro5-doc/refman/transformations.html", "unified_diff": "@@ -312,25 +312,39 @@\n

        Defines the generic transformation type, a 4x4 matrix. 2D transforms\n use only a small subsection of this matrix, namely the top left 2x2\n matrix, and the right most 2x1 matrix, for a total of 6 values.

        \n

        Fields:

        \n
          \n
        • m - A 4x4 float matrix
          • \n
        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        • ex_shader_target.c
          • \n+
        • ex_audio_timer.c
          • \n+
        \n

        al_copy_transform

        \n 
        void al_copy_transform(ALLEGRO_TRANSFORM *dest, const ALLEGRO_TRANSFORM *src)
        \n

        Source\n Code

        \n

        Makes a copy of a transformation.

        \n

        Parameters:

        \n
          \n
        • dest - Source transformation
          • \n
        • src - Destination transformation
          • \n
        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        \n

        al_use_transform

        \n 
        void al_use_transform(const ALLEGRO_TRANSFORM *trans)
        \n

        Source\n Code

        \n

        Sets the transformation to be used for the the drawing operations on\n the target bitmap (each bitmap maintains its own transformation). Every\n@@ -351,25 +365,41 @@\n

          \n
        • trans - Transformation to use
          • \n
        \n

        See also: al_get_current_transform,\n al_transform_coordinates

        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        • ex_shader_target.c
          • \n+
        • ex_audio_timer.c
          • \n+
        \n

        al_get_current_transform

        \n 
        const ALLEGRO_TRANSFORM *al_get_current_transform(void)
        \n

        Source\n Code

        \n

        Returns the transformation of the current target bitmap, as set by al_use_transform. If\n there is no target bitmap, this function returns NULL.

        \n

        Returns: A pointer to the current transformation.

        \n

        See also: al_get_current_projection_transform

        \n+

        Examples:

        \n+
          \n+
        • ex_shader.cpp
          • \n+
        • ex_color_gradient.c
          • \n+
        \n

        al_use_projection_transform

        \n 
        void al_use_projection_transform(const ALLEGRO_TRANSFORM *trans)
        \n

        Source\n Code

        \n

        Sets the projection transformation to be used for the drawing\n operations on the target bitmap (each bitmap maintains its own\n@@ -401,25 +431,39 @@\n

        Since: 5.1.9

        \n

        See also: al_get_current_projection_transform,\n al_perspective_transform,\n al_orthographic_transform

        \n+

        Examples:

        \n+
          \n+
        • ex_projection.c
          • \n+
        • ex_depth_target.c
          • \n+
        • ex_projection2.c
          • \n+
        \n al_get_current_projection_transform\n 
        const ALLEGRO_TRANSFORM *al_get_current_projection_transform(void)
        \n

        Source\n Code

        \n

        If there is no target bitmap, this function returns NULL.

        \n

        Returns: A pointer to the current transformation.

        \n

        Since: 5.1.9

        \n

        See also: al_use_projection_transform

        \n+

        Examples:

        \n+
          \n+
        • ex_camera.c
          • \n+
        \n al_get_current_inverse_transform\n 
        const ALLEGRO_TRANSFORM *al_get_current_inverse_transform(void)
        \n

        Source\n Code

        \n

        Returns the inverse of the current transformation of the target\n@@ -520,14 +564,23 @@\n

      \n

      See also: al_translate_transform,\n al_rotate_transform,\n al_scale_transform

      \n+

      Examples:

      \n+
        \n+
      • ex_shader.cpp
        • \n+
      • ex_shader_target.c
        • \n+
      • ex_audio_timer.c
        • \n+
      \n

      al_build_transform

      \n 
      void al_build_transform(ALLEGRO_TRANSFORM *trans, float x, float y,\n    float sx, float sy, float theta)
      \n

      Source\n Code

      \n

      Builds a transformation given some parameters. This call is\n@@ -550,14 +603,23 @@\n href=\"transformations.html#al_translate_transform\">al_translate_transform,\n al_rotate_transform,\n al_scale_transform,\n al_compose_transform

      \n+

      Examples:

      \n+
        \n+
      • ex_threads.c
        • \n+
      • ex_color_gradient.c
        • \n+
      • ex_prim.c
        • \n+
      \n

      al_build_camera_transform

      \n 
      void al_build_camera_transform(ALLEGRO_TRANSFORM *trans,\n    float position_x, float position_y, float position_z,\n    float look_x, float look_y, float look_z,\n    float up_x, float up_y, float up_z)
      \n

      Source\n@@ -598,14 +660,19 @@\n al_rotate_transform_3d,\n al_scale_transform_3d,\n al_compose_transform,\n al_use_transform

      \n+

      Examples:

      \n+
        \n+
      • ex_camera.c
        • \n+
      \n

      al_translate_transform

      \n 
      void al_translate_transform(ALLEGRO_TRANSFORM *trans, float x, float y)
      \n

      Source\n Code

      \n

      Apply a translation to a transformation.

      \n

      Parameters:

      \n@@ -615,14 +682,23 @@\n
    \n

    See also: al_rotate_transform,\n al_scale_transform,\n al_build_transform

    \n+

    Examples:

    \n+
      \n+
    • ex_shader.cpp
      • \n+
    • ex_shader_target.c
      • \n+
    • ex_polygon.c
      • \n+
    \n

    al_rotate_transform

    \n 
    void al_rotate_transform(ALLEGRO_TRANSFORM *trans, float theta)
    \n

    Source\n Code

    \n

    Apply a rotation to a transformation.

    \n

    Parameters:

    \n@@ -632,14 +708,23 @@\n \n

    See also: al_translate_transform,\n al_scale_transform,\n al_build_transform

    \n+

    Examples:

    \n+
      \n+
    • ex_depth_mask.c
      • \n+
    • ex_projection.c
      • \n+
    • ex_depth_target.c
      • \n+
    \n

    al_scale_transform

    \n 
    void al_scale_transform(ALLEGRO_TRANSFORM *trans, float sx, float sy)
    \n

    Source\n Code

    \n

    Apply a scale to a transformation.

    \n

    Parameters:

    \n@@ -649,28 +734,42 @@\n \n

    See also: al_translate_transform,\n al_rotate_transform,\n al_build_transform

    \n+

    Examples:

    \n+
      \n+
    • ex_shader_target.c
      • \n+
    • ex_audio_timer.c
      • \n+
    • ex_polygon.c
      • \n+
    \n

    al_transform_coordinates

    \n 
    void al_transform_coordinates(const ALLEGRO_TRANSFORM *trans, float *x, float *y)
    \n

    Source\n Code

    \n

    Transform a pair of coordinates.

    \n

    Parameters:

    \n
      \n
    • trans - Transformation to use
      • \n
    • x, y - Pointers to the coordinates
      • \n
    \n

    See also: al_use_transform, al_transform_coordinates_3d

    \n+

    Examples:

    \n+
      \n+
    • ex_camera.c
      • \n+
    \n

    al_transform_coordinates_3d

    \n 
    void al_transform_coordinates_3d(const ALLEGRO_TRANSFORM *trans,\n    float *x, float *y, float *z)
    \n

    Source\n Code

    \n

    Transform x, y, z coordinates.

    \n@@ -683,14 +782,19 @@\n want to use al_transform_coordinates_3d_projective\n instead.

    \n

    Since 5.1.9

    \n

    See also: al_use_transform, al_transform_coordinates

    \n+

    Examples:

    \n+
      \n+
    • ex_camera.c
      • \n+
    \n

    al_transform_coordinates_4d

    \n 
    void al_transform_coordinates_4d(const ALLEGRO_TRANSFORM *trans,\n    float *x, float *y, float *z, float *w)
    \n

    Source\n Code

    \n

    Transform x, y, z, w coordinates.

    \n@@ -770,14 +874,19 @@\n \n

    See also: al_translate_transform,\n al_rotate_transform,\n al_scale_transform

    \n+

    Examples:

    \n+
      \n+
    • ex_color_gradient.c
      • \n+
    \n

    al_orthographic_transform

    \n 
    void al_orthographic_transform(ALLEGRO_TRANSFORM *trans,\n    float left, float top, float n,\n    float right, float bottom, float f)
    \n

    Source\n Code

    \n@@ -801,14 +910,19 @@\n href=\"transformations.html#al_use_projection_transform\">al_use_projection_transform\n - see that function for an example use.

    \n

    Since: 5.1.3

    \n

    See also: al_use_projection_transform,\n al_perspective_transform

    \n+

    Examples:

    \n+
      \n+
    • ex_depth_target.c
      • \n+
    \n

    al_perspective_transform

    \n 
    void al_perspective_transform(ALLEGRO_TRANSFORM *trans,\n    float left, float top, float n,\n    float right, float bottom, float f)
    \n

    Source\n Code

    \n@@ -877,25 +991,43 @@\n // pixel (assuming the display is 800 x 450).\n al_draw_filled_rectangle(-1, -1, 1, 1, red);    \n

    Since: 5.1.3

    \n

    See also: al_use_projection_transform,\n al_orthographic_transform

    \n+

    Examples:

    \n+
      \n+
    • ex_projection.c
      • \n+
    • ex_projection2.c
      • \n+
    • ex_camera.c
      • \n+
    \n

    al_translate_transform_3d

    \n 
    void al_translate_transform_3d(ALLEGRO_TRANSFORM *trans, float x, float y,\n     float z)
    \n

    Source\n Code

    \n

    Combines the given transformation with a transformation which\n translates coordinates by the given vector.

    \n

    Since: 5.1.3

    \n

    See also: al_use_projection_transform

    \n+

    Examples:

    \n+
      \n+
    • ex_projection.c
      • \n+
    • ex_depth_target.c
      • \n+
    • ex_projection2.c
      • \n+
    \n

    al_scale_transform_3d

    \n 
    void al_scale_transform_3d(ALLEGRO_TRANSFORM *trans, float sx, float sy,\n     float sz)
    \n

    Source\n Code

    \n

    Combines the given transformation with a transformation which scales\n@@ -910,14 +1042,23 @@\n href=\"https://github.com/liballeg/allegro5/blob/master/src/transformations.c#L566\">Source\n Code

    \n

    Combines the given transformation with a transformation which rotates\n coordinates around the given vector by the given angle in radians.

    \n

    Note: The vector is assumed to be of unit length (otherwise it will\n also incur a scale).

    \n

    Since: 5.1.3

    \n+

    Examples:

    \n+
      \n+
    • ex_projection.c
      • \n+
    • ex_depth_target.c
      • \n+
    • ex_projection2.c
      • \n+
    \n al_horizontal_shear_transform\n 
    void al_horizontal_shear_transform(ALLEGRO_TRANSFORM* trans, float theta)
    \n

    Source\n Code

    \n

    Apply a horizontal shear to the transform

    \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -136,21 +136,27 @@\n typedef struct ALLEGRO_TRANSFORM ALLEGRO_TRANSFORM;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Defines the generic transformation type, a 4x4 matrix. 2D transforms use only a\n small subsection of this matrix, namely the top left 2x2 matrix, and the right\n most 2x1 matrix, for a total of 6 values.\n F\bFi\bie\bel\bld\bds\bs:\b:\n * m - A 4x4 float matrix\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bt_\bi_\bm_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bco\bop\bpy\by_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n void al_copy_transform(ALLEGRO_TRANSFORM *dest, const ALLEGRO_TRANSFORM *src)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Makes a copy of a transformation.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * dest - Source transformation\n * src - Destination transformation\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bse\be_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n void al_use_transform(const ALLEGRO_TRANSFORM *trans)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets the transformation to be used for the the drawing operations on the target\n bitmap (each bitmap maintains its own transformation). Every drawing operation\n after this call will be transformed using this transformation. Call this\n function with an identity transformation to return to the default behaviour.\n@@ -163,21 +169,28 @@\n ALLEGRO_TRANSFORM transform;\n al_translate_transform(&transform, 5, 10);\n al_use_transform(&transform);\n }\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * trans - Transformation to use\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bc_\bu_\br_\br_\be_\bn_\bt_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm_\b__\bc_\bo_\bo_\br_\bd_\bi_\bn_\ba_\bt_\be_\bs\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bt_\bi_\bm_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_c\bcu\bur\brr\bre\ben\bnt\bt_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n const ALLEGRO_TRANSFORM *al_get_current_transform(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the transformation of the current target bitmap, as set by\n _\ba_\bl_\b__\bu_\bs_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm. If there is no target bitmap, this function returns NULL.\n R\bRe\bet\btu\bur\brn\bns\bs:\b: A pointer to the current transformation.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bc_\bu_\br_\br_\be_\bn_\bt_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b__\bg_\br_\ba_\bd_\bi_\be_\bn_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bse\be_\b_p\bpr\bro\boj\bje\bec\bct\bti\bio\bon\bn_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n void al_use_projection_transform(const ALLEGRO_TRANSFORM *trans)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Sets the projection transformation to be used for the drawing operations on the\n target bitmap (each bitmap maintains its own projection transformation). Every\n drawing operation after this call will be transformed using this\n transformation. To return default behavior, call this function with an\n@@ -201,21 +214,27 @@\n projection transform of the target bitmap was temporarily reset to default).\n The parameter is passed by reference as an optimization to avoid the overhead\n of stack copying. The reference will not be stored in the Allegro library so it\n is safe to pass references to local variables.\n Since: 5.1.9\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bc_\bu_\br_\br_\be_\bn_\bt_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bp_\be_\br_\bs_\bp_\be_\bc_\bt_\bi_\bv_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm,\n _\ba_\bl_\b__\bo_\br_\bt_\bh_\bo_\bg_\br_\ba_\bp_\bh_\bi_\bc_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b._\bc\n+ * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b2_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_c\bcu\bur\brr\bre\ben\bnt\bt_\b_p\bpr\bro\boj\bje\bec\bct\bti\bio\bon\bn_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n const ALLEGRO_TRANSFORM *al_get_current_projection_transform(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n If there is no target bitmap, this function returns NULL.\n R\bRe\bet\btu\bur\brn\bns\bs:\b: A pointer to the current transformation.\n Since: 5.1.9\n See also: _\ba_\bl_\b__\bu_\bs_\be_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm\n+Examples:\n+ * _\be_\bx_\b__\bc_\ba_\bm_\be_\br_\ba_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_c\bcu\bur\brr\bre\ben\bnt\bt_\b_i\bin\bnv\bve\ber\brs\bse\be_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n const ALLEGRO_TRANSFORM *al_get_current_inverse_transform(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the inverse of the current transformation of the target bitmap. If\n there is no target bitmap, this function returns NULL.\n This is similar to calling al_invert_transform(al_get_current_transform()) but\n the result of this function is cached.\n@@ -280,14 +299,18 @@\n the default.\n ALLEGRO_TRANSFORM t;\n al_identity_transform(&t);\n al_use_transform(&t);\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * trans - Transformation to alter\n See also: _\ba_\bl_\b__\bt_\br_\ba_\bn_\bs_\bl_\ba_\bt_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\br_\bo_\bt_\ba_\bt_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bs_\bc_\ba_\bl_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bt_\bi_\bm_\be_\br_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_b\bbu\bui\bil\bld\bd_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n void al_build_transform(ALLEGRO_TRANSFORM *trans, float x, float y,\n float sx, float sy, float theta)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Builds a transformation given some parameters. This call is equivalent to\n calling the transformations in this order: make identity, rotate, scale,\n translate. This method is faster, however, than actually calling those\n@@ -298,14 +321,18 @@\n * sx, sy - Scale\n * theta - Rotation angle in radians\n N\bNo\bot\bte\be: this function was previously documented to be equivalent to a\n different (and more useful) order of operations: identity, scale,\n rotate, translate.\n See also: _\ba_\bl_\b__\bt_\br_\ba_\bn_\bs_\bl_\ba_\bt_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\br_\bo_\bt_\ba_\bt_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bs_\bc_\ba_\bl_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm,\n _\ba_\bl_\b__\bc_\bo_\bm_\bp_\bo_\bs_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm\n+Examples:\n+ * _\be_\bx_\b__\bt_\bh_\br_\be_\ba_\bd_\bs_\b._\bc\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b__\bg_\br_\ba_\bd_\bi_\be_\bn_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bi_\bm_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_b\bbu\bui\bil\bld\bd_\b_c\bca\bam\bme\ber\bra\ba_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n void al_build_camera_transform(ALLEGRO_TRANSFORM *trans,\n float position_x, float position_y, float position_z,\n float look_x, float look_y, float look_z,\n float up_x, float up_y, float up_z)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Builds a transformation which can be used to transform 3D coordinates in world\n@@ -334,59 +361,77 @@\n al_build_camera_transform(&t,\n 1, 1, 1,\n 5, 5, 5,\n 1, 1, 0);\n Since 5.1.9\n See also: _\ba_\bl_\b__\bt_\br_\ba_\bn_\bs_\bl_\ba_\bt_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm_\b__\b3_\bd, _\ba_\bl_\b__\br_\bo_\bt_\ba_\bt_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm_\b__\b3_\bd,\n _\ba_\bl_\b__\bs_\bc_\ba_\bl_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm_\b__\b3_\bd, _\ba_\bl_\b__\bc_\bo_\bm_\bp_\bo_\bs_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bu_\bs_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm\n+Examples:\n+ * _\be_\bx_\b__\bc_\ba_\bm_\be_\br_\ba_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_t\btr\bra\ban\bns\bsl\bla\bat\bte\be_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n void al_translate_transform(ALLEGRO_TRANSFORM *trans, float x, float y)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Apply a translation to a transformation.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * trans - Transformation to alter\n * x, y - Translation\n See also: _\ba_\bl_\b__\br_\bo_\bt_\ba_\bt_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bs_\bc_\ba_\bl_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bb_\bu_\bi_\bl_\bd_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_r\bro\bot\bta\bat\bte\be_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n void al_rotate_transform(ALLEGRO_TRANSFORM *trans, float theta)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Apply a rotation to a transformation.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * trans - Transformation to alter\n * theta - Rotation angle in radians\n See also: _\ba_\bl_\b__\bt_\br_\ba_\bn_\bs_\bl_\ba_\bt_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bs_\bc_\ba_\bl_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bb_\bu_\bi_\bl_\bd_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm\n+Examples:\n+ * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bm_\ba_\bs_\bk_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b._\bc\n+ * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bsc\bca\bal\ble\be_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n void al_scale_transform(ALLEGRO_TRANSFORM *trans, float sx, float sy)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Apply a scale to a transformation.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * trans - Transformation to alter\n * sx, sy - Scale\n See also: _\ba_\bl_\b__\bt_\br_\ba_\bn_\bs_\bl_\ba_\bt_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\br_\bo_\bt_\ba_\bt_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bb_\bu_\bi_\bl_\bd_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm\n+Examples:\n+ * _\be_\bx_\b__\bs_\bh_\ba_\bd_\be_\br_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\ba_\bu_\bd_\bi_\bo_\b__\bt_\bi_\bm_\be_\br_\b._\bc\n+ * _\be_\bx_\b__\bp_\bo_\bl_\by_\bg_\bo_\bn_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm_\b_c\bco\boo\bor\brd\bdi\bin\bna\bat\bte\bes\bs *\b**\b**\b**\b**\b**\b*\n void al_transform_coordinates(const ALLEGRO_TRANSFORM *trans, float *x, float\n *y)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Transform a pair of coordinates.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * trans - Transformation to use\n * x, y - Pointers to the coordinates\n See also: _\ba_\bl_\b__\bu_\bs_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm_\b__\bc_\bo_\bo_\br_\bd_\bi_\bn_\ba_\bt_\be_\bs_\b__\b3_\bd\n+Examples:\n+ * _\be_\bx_\b__\bc_\ba_\bm_\be_\br_\ba_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm_\b_c\bco\boo\bor\brd\bdi\bin\bna\bat\bte\bes\bs_\b_3\b3d\bd *\b**\b**\b**\b**\b**\b*\n void al_transform_coordinates_3d(const ALLEGRO_TRANSFORM *trans,\n float *x, float *y, float *z)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Transform x, y, z coordinates.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * trans - Transformation to use\n * x, y, z - Pointers to the coordinates\n Note: If you are using a projection transform you most likely will want to use\n _\ba_\bl_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm_\b__\bc_\bo_\bo_\br_\bd_\bi_\bn_\ba_\bt_\be_\bs_\b__\b3_\bd_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bv_\be instead.\n Since 5.1.9\n See also: _\ba_\bl_\b__\bu_\bs_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm_\b__\bc_\bo_\bo_\br_\bd_\bi_\bn_\ba_\bt_\be_\bs\n+Examples:\n+ * _\be_\bx_\b__\bc_\ba_\bm_\be_\br_\ba_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm_\b_c\bco\boo\bor\brd\bdi\bin\bna\bat\bte\bes\bs_\b_4\b4d\bd *\b**\b**\b**\b**\b**\b*\n void al_transform_coordinates_4d(const ALLEGRO_TRANSFORM *trans,\n float *x, float *y, float *z, float *w)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Transform x, y, z, w coordinates.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * trans - Transformation to use\n@@ -438,14 +483,16 @@\n Note that the order of matrix multiplications is important. The effect of\n applying the combined transform will be as if first applying trans and then\n applying other and not the other way around.\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * trans - Transformation to alter\n * other - Transformation used to transform trans\n See also: _\ba_\bl_\b__\bt_\br_\ba_\bn_\bs_\bl_\ba_\bt_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\br_\bo_\bt_\ba_\bt_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bs_\bc_\ba_\bl_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm\n+Examples:\n+ * _\be_\bx_\b__\bc_\bo_\bl_\bo_\br_\b__\bg_\br_\ba_\bd_\bi_\be_\bn_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_o\bor\brt\bth\bho\bog\bgr\bra\bap\bph\bhi\bic\bc_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n void al_orthographic_transform(ALLEGRO_TRANSFORM *trans,\n float left, float top, float n,\n float right, float bottom, float f)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Combines the given transformation with an orthographic transformation which\n maps the screen rectangle to the given left/top and right/bottom coordinates.\n@@ -461,14 +508,16 @@\n artifacts.\n The result of applying this transformation to coordinates will be to normalize\n visible coordinates into the cube from -1/-1/-1 to 1/1/1. Such a transformation\n is mostly useful for passing it to _\ba_\bl_\b__\bu_\bs_\be_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm - see that\n function for an example use.\n Since: 5.1.3\n See also: _\ba_\bl_\b__\bu_\bs_\be_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bp_\be_\br_\bs_\bp_\be_\bc_\bt_\bi_\bv_\be_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm\n+Examples:\n+ * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_p\bpe\ber\brs\bsp\bpe\bec\bct\bti\biv\bve\be_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n void al_perspective_transform(ALLEGRO_TRANSFORM *trans,\n float left, float top, float n,\n float right, float bottom, float f)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bo_\br_\bt_\bh_\bo_\bg_\br_\ba_\bp_\bh_\bi_\bc_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm but honors perspective. If everything is at a z-\n position of -near it will look the same as with an orthographic transformation.\n@@ -529,22 +578,30 @@\n // At a z distance of 4 with a 90\u00b0 hfov everything would be scaled\n // down to 25%. However we also zoom 2-fold, so the final scaling is\n // 50%. This rectangle therefore will appear at a size of 400 x 225\n // pixel (assuming the display is 800 x 450).\n al_draw_filled_rectangle(-1, -1, 1, 1, red);\n Since: 5.1.3\n See also: _\ba_\bl_\b__\bu_\bs_\be_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm, _\ba_\bl_\b__\bo_\br_\bt_\bh_\bo_\bg_\br_\ba_\bp_\bh_\bi_\bc_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b2_\b._\bc\n+ * _\be_\bx_\b__\bc_\ba_\bm_\be_\br_\ba_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_t\btr\bra\ban\bns\bsl\bla\bat\bte\be_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm_\b_3\b3d\bd *\b**\b**\b**\b**\b**\b*\n void al_translate_transform_3d(ALLEGRO_TRANSFORM *trans, float x, float y,\n float z)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Combines the given transformation with a transformation which translates\n coordinates by the given vector.\n Since: 5.1.3\n See also: _\ba_\bl_\b__\bu_\bs_\be_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b__\bt_\br_\ba_\bn_\bs_\bf_\bo_\br_\bm\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b._\bc\n+ * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b2_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bsc\bca\bal\ble\be_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm_\b_3\b3d\bd *\b**\b**\b**\b**\b**\b*\n void al_scale_transform_3d(ALLEGRO_TRANSFORM *trans, float sx, float sy,\n float sz)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Combines the given transformation with a transformation which scales\n coordinates by the given vector.\n Since: 5.1.3\n@@ -554,14 +611,18 @@\n float x, float y, float z, float angle)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Combines the given transformation with a transformation which rotates\n coordinates around the given vector by the given angle in radians.\n Note: The vector is assumed to be of unit length (otherwise it will also incur\n a scale).\n Since: 5.1.3\n+Examples:\n+ * _\be_\bx_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b._\bc\n+ * _\be_\bx_\b__\bd_\be_\bp_\bt_\bh_\b__\bt_\ba_\br_\bg_\be_\bt_\b._\bc\n+ * _\be_\bx_\b__\bp_\br_\bo_\bj_\be_\bc_\bt_\bi_\bo_\bn_\b2_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_h\bho\bor\bri\biz\bzo\bon\bnt\bta\bal\bl_\b_s\bsh\bhe\bea\bar\br_\b_t\btr\bra\ban\bns\bsf\bfo\bor\brm\bm *\b**\b**\b**\b**\b**\b*\n void al_horizontal_shear_transform(ALLEGRO_TRANSFORM* trans, float theta)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Apply a horizontal shear to the transform\n P\bPa\bar\bra\bam\bme\bet\bte\ber\brs\bs:\b:\n * trans - Transformation to alter\n * theta - Rotation angle in radians\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/utf8.html", "source2": "./usr/share/doc/allegro5-doc/refman/utf8.html", "unified_diff": "@@ -444,28 +444,46 @@\n 
    typedef struct _al_tagbstring ALLEGRO_USTR;
    \n

    Source\n Code

    \n

    An opaque type representing a string. ALLEGRO_USTRs normally contain\n UTF-8 encoded strings, but they may be used to hold any byte sequences,\n including NULs.

    \n+

    Examples:

    \n+
      \n+
    • ex_font_multiline.cpp
      • \n+
    • nihgui.cpp
      • \n+
    • ex_blend.c
      • \n+
    \n

    ALLEGRO_USTR_INFO

    \n 
    typedef struct _al_tagbstring ALLEGRO_USTR_INFO;
    \n

    Source\n Code

    \n

    A type that holds additional information for an ALLEGRO_USTR that references an\n external memory buffer. You can convert it back to ALLEGRO_USTR via al_ref_info.

    \n

    See also: al_ref_cstr, al_ref_buffer, al_ref_info and al_ref_ustr.

    \n+

    Examples:

    \n+
      \n+
    • ex_font_multiline.cpp
      • \n+
    • nihgui.cpp
      • \n+
    • ex_blend.c
      • \n+
    \n

    Creating and destroying\n strings

    \n

    al_ustr_new

    \n 
    ALLEGRO_USTR *al_ustr_new(const char *s)
    \n

    Source\n Code

    \n@@ -473,24 +491,38 @@\n s. The string must eventually be freed with al_ustr_free.

    \n

    See also: al_ustr_new_from_buffer, al_ustr_newf, al_ustr_dup, al_ustr_new_from_utf16

    \n+

    Examples:

    \n+
      \n+
    • nihgui.cpp
      • \n+
    • ex_loading_thread.c
      • \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_new_from_buffer

    \n 
    ALLEGRO_USTR *al_ustr_new_from_buffer(const char *s, size_t size)
    \n

    Source\n Code

    \n

    Create a new string containing a copy of the buffer pointed to by\n s of the given size in bytes. The string must\n eventually be freed with al_ustr_free.

    \n

    See also: al_ustr_new

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_newf

    \n 
    ALLEGRO_USTR *al_ustr_newf(const char *fmt, ...)
    \n

    Source\n Code

    \n

    Create a new string using a printf-style format string.

    \n

    Notes:

    \n@@ -503,24 +535,38 @@\n code point. Therefore it is only usable for ASCII characters (value\n <= 127) or if you really mean to output byte values from 128\u2013255. To\n insert the UTF-8 encoding of a code point, encode it into a memory\n buffer using al_utf8_encode then\n use the \u201c%s\u201d specifier. Remember to NUL terminate the buffer.

    \n

    See also: al_ustr_new, al_ustr_appendf

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_free

    \n 
    void al_ustr_free(ALLEGRO_USTR *us)
    \n

    Source\n Code

    \n

    Free a previously allocated string. Does nothing if the argument is\n NULL.

    \n

    See also: al_ustr_new, al_ustr_new_from_buffer, al_ustr_newf

    \n+

    Examples:

    \n+
      \n+
    • nihgui.cpp
      • \n+
    • ex_loading_thread.c
      • \n+
    • ex_utf8.c
      • \n+
    \n

    al_cstr

    \n 
    const char *al_cstr(const ALLEGRO_USTR *us)
    \n

    Source\n Code

    \n

    Get a char * pointer to the data in a string. This\n pointer will only be valid while the

    If the ALLEGRO_USTR references another string, the returned C\n string will point into the referenced string. Again, no NUL terminator\n will be added to the referenced string.

    \n \n

    See also: al_ustr_to_buffer, al_cstr_dup

    \n+

    Examples:

    \n+
      \n+
    • nihgui.cpp
      • \n+
    • ex_loading_thread.c
      • \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_to_buffer

    \n 
    void al_ustr_to_buffer(const ALLEGRO_USTR *us, char *buffer, int size)
    \n

    Source\n Code

    \n

    Write the contents of the string into a pre-allocated buffer of the\n given size in bytes. The result will always be NUL terminated, so a\n maximum of size - 1 bytes will be copied.

    \n

    See also: al_cstr, al_cstr_dup

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_cstr_dup

    \n 
    char *al_cstr_dup(const ALLEGRO_USTR *us)
    \n

    Source\n Code

    \n

    Create a NUL ('\\0') terminated copy of the string. Any\n embedded NUL bytes will still be presented in the returned string. The\n new string must eventually be freed with al_free.

    \n

    If an error occurs NULL is returned.

    \n

    See also: al_cstr, al_ustr_to_buffer, al_free

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_dup

    \n 
    ALLEGRO_USTR *al_ustr_dup(const ALLEGRO_USTR *us)
    \n

    Source\n Code

    \n

    Return a duplicate copy of a string. The new string will need to be\n freed with al_ustr_free.

    \n

    See also: al_ustr_dup_substr, al_ustr_free

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_dup_substr

    \n 
    ALLEGRO_USTR *al_ustr_dup_substr(const ALLEGRO_USTR *us, int start_pos,\n    int end_pos)
    \n

    Source\n Code

    \n

    Return a new copy of a string, containing its contents in the byte\n@@ -586,22 +656,32 @@\n will be NUL terminated and will need to be freed with al_ustr_free.

    \n

    If necessary, use al_ustr_offset to find the byte\n offsets for a given code point that you are interested in.

    \n

    See also: al_ustr_dup, al_ustr_free

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    Predefined strings

    \n

    al_ustr_empty_string

    \n 
    const ALLEGRO_USTR *al_ustr_empty_string(void)
    \n

    Source\n Code

    \n

    Return a pointer to a static empty string. The string is read only\n and must not be freed.

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    Creating strings by\n referencing other data

    \n

    al_ref_cstr

    \n 
    const ALLEGRO_USTR *al_ref_cstr(ALLEGRO_USTR_INFO *info, const char *s)
    \n

    Source\n Code

    \n@@ -613,25 +693,41 @@\n operation is required.

    \n

    The string is valid until the underlying C string disappears.

    \n

    Example:

    \n 
    ALLEGRO_USTR_INFO info;\n ALLEGRO_USTR *us = al_ref_cstr(&info, "my string");
    \n

    See also: al_ref_buffer, al_ref_ustr

    \n+

    Examples:

    \n+
      \n+
    • ex_blend.c
      • \n+
    • ex_utf8.c
      • \n+
    • ex_ttf.c
      • \n+
    \n

    al_ref_buffer

    \n 
    const ALLEGRO_USTR *al_ref_buffer(ALLEGRO_USTR_INFO *info, const char *s, size_t size)
    \n

    Source\n Code

    \n

    Create a string that references the storage of an underlying buffer.\n The size of the buffer is given in bytes. You can use it to reference\n only part of a string or an arbitrary region of memory.

    \n

    The string is valid while the underlying memory buffer is valid.

    \n

    See also: al_ref_cstr, al_ref_ustr

    \n+

    Examples:

    \n+
      \n+
    • ex_font_multiline.cpp
      • \n+
    • ex_utf8.c
      • \n+
    \n

    al_ref_ustr

    \n 
    const ALLEGRO_USTR *al_ref_ustr(ALLEGRO_USTR_INFO *info, const ALLEGRO_USTR *us,\n    int start_pos, int end_pos)
    \n

    Source\n Code

    \n

    Create a read-only string that references the storage of another The string is valid until the underlying string is modified or\n destroyed.

    \n

    If you need a range of code-points instead of bytes, use al_ustr_offset to find the byte\n offsets.

    \n

    See also: al_ref_cstr, al_ref_buffer

    \n+

    Examples:

    \n+
      \n+
    • nihgui.cpp
      • \n+
    • ex_blend.c
      • \n+
    • ex_utf8.c
      • \n+
    \n

    al_ref_info

    \n 
    const ALLEGRO_USTR *al_ref_info(const ALLEGRO_USTR_INFO *info)
    \n

    Source\n Code

    \n

    Create a read-only string that references the storage of another ALLEGRO_USTR string that has already\n@@ -670,35 +775,60 @@\n

    Source\n Code

    \n

    Return the size of the string in bytes. This is equal to the number\n of code points in the string if the string is empty or contains only\n 7-bit ASCII characters.

    \n

    See also: al_ustr_length

    \n+

    Examples:

    \n+
      \n+
    • nihgui.cpp
      • \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_length

    \n 
    size_t al_ustr_length(const ALLEGRO_USTR *us)
    \n

    Source\n Code

    \n

    Return the number of code points in the string.

    \n

    See also: al_ustr_size, al_ustr_offset

    \n+

    Examples:

    \n+
      \n+
    • ex_blend.c
      • \n+
    • ex_utf8.c
      • \n+
    • ex_ttf.c
      • \n+
    \n

    al_ustr_offset

    \n 
    int al_ustr_offset(const ALLEGRO_USTR *us, int index)
    \n

    Source\n Code

    \n

    Return the byte offset (from the start of the string) of the code\n point at the specified index in the string. A zero index parameter will\n return the first character of the string. If index is negative, it\n counts backward from the end of the string, so an index of -1 will\n return an offset to the last code point.

    \n

    If the index is past the end of the string, returns the offset of the\n end of the string.

    \n

    See also: al_ustr_length

    \n+

    Examples:

    \n+
      \n+
    • ex_blend.c
      • \n+
    • ex_utf8.c
      • \n+
    • ex_ttf.c
      • \n+
    \n

    al_ustr_next

    \n 
    bool al_ustr_next(const ALLEGRO_USTR *us, int *pos)
    \n

    Source\n Code

    \n

    Find the byte offset of the next code point in string, beginning at\n *pos. *pos does not have to be at the\n@@ -708,14 +838,21 @@\n *pos was already at the end of the string, and\n *pos is unmodified.

    \n

    This function just looks for an appropriate byte; it doesn\u2019t check if\n found offset is the beginning of a valid code point. If you are working\n with possibly invalid UTF-8 strings then it could skip over some invalid\n bytes.

    \n

    See also: al_ustr_prev

    \n+

    Examples:

    \n+
      \n+
    • nihgui.cpp
      • \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_prev

    \n 
    bool al_ustr_prev(const ALLEGRO_USTR *us, int *pos)
    \n

    Source\n Code

    \n

    Find the byte offset of the previous code point in string, before\n *pos. *pos does not have to be at the\n@@ -724,41 +861,62 @@\n Otherwise returns false if *pos was already at the end of\n the string, and *pos is unmodified.

    \n

    This function just looks for an appropriate byte; it doesn\u2019t check if\n found offset is the beginning of a valid code point. If you are working\n with possibly invalid UTF-8 strings then it could skip over some invalid\n bytes.

    \n

    See also: al_ustr_next

    \n+

    Examples:

    \n+
      \n+
    • nihgui.cpp
      • \n+
    • ex_utf8.c
      • \n+
    • ex_logo.c
      • \n+
    \n

    Getting code points

    \n

    al_ustr_get

    \n 
    int32_t al_ustr_get(const ALLEGRO_USTR *ub, int pos)
    \n

    Source\n Code

    \n

    Return the code point in ub beginning at byte offset\n pos.

    \n

    On success returns the code point value. If pos was out\n of bounds (e.g.\u00a0past the end of the string), return -1. On an error,\n such as an invalid byte sequence, return -2.

    \n

    See also: al_ustr_get_next,\n al_ustr_prev_get

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    • ex_ttf.c
      • \n+
    \n

    al_ustr_get_next

    \n 
    int32_t al_ustr_get_next(const ALLEGRO_USTR *us, int *pos)
    \n

    Source\n Code

    \n

    Find the code point in us beginning at byte offset\n *pos, then advance to the next code point.

    \n

    On success return the code point value. If pos was out\n of bounds (e.g.\u00a0past the end of the string), return -1. On an error,\n such as an invalid byte sequence, return -2. As with al_ustr_next, invalid byte sequences\n may be skipped while advancing.

    \n

    See also: al_ustr_get, al_ustr_prev_get

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_prev_get

    \n 
    int32_t al_ustr_prev_get(const ALLEGRO_USTR *us, int *pos)
    \n

    Source\n Code

    \n

    Find the beginning of a code point before byte offset\n *pos, then return it. Note this performs a\n@@ -766,14 +924,19 @@\n

    On success returns the code point value. If pos was out\n of bounds (e.g.\u00a0past the end of the string), return -1. On an error,\n such as an invalid byte sequence, return -2. As with al_ustr_prev, invalid byte sequences\n may be skipped while advancing.

    \n

    See also: al_ustr_get_next

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    Inserting into strings

    \n

    al_ustr_insert

    \n 
    bool al_ustr_insert(ALLEGRO_USTR *us1, int pos, const ALLEGRO_USTR *us2)
    \n

    Source\n Code

    \n

    Insert us2 into us1 beginning at byte\n@@ -786,36 +949,55 @@\n offset for a given code point index.

    \n

    Returns true on success, false on error.

    \n

    See also: al_ustr_insert_cstr, al_ustr_insert_chr, al_ustr_append, al_ustr_offset

    \n+

    Examples:

    \n+
      \n+
    • nihgui.cpp
      • \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_insert_cstr

    \n 
    bool al_ustr_insert_cstr(ALLEGRO_USTR *us, int pos, const char *s)
    \n

    Source\n Code

    \n

    Like al_ustr_insert but\n inserts a C-style string at byte offset pos.

    \n

    See also: al_ustr_insert, al_ustr_insert_chr

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_insert_chr

    \n 
    size_t al_ustr_insert_chr(ALLEGRO_USTR *us, int pos, int32_t c)
    \n

    Source\n Code

    \n

    Insert a code point into us beginning at byte offset\n pos. pos cannot be less than 0. If\n pos is past the end of us then the space\n between the end of the string and pos will be padded with\n NUL ('\\0') bytes.

    \n

    Returns the number of bytes inserted, or 0 on error.

    \n

    See also: al_ustr_insert, al_ustr_insert_cstr

    \n+

    Examples:

    \n+
      \n+
    • nihgui.cpp
      • \n+
    • ex_utf8.c
      • \n+
    \n

    Appending to strings

    \n

    al_ustr_append

    \n 
    bool al_ustr_append(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)
    \n

    Source\n Code

    \n

    Append us2 to the end of us1.

    \n@@ -824,138 +1006,208 @@\n 
      ALLEGRO_USTR_INFO info;\n   al_ustr_append(us, al_ref_buffer(&info, buf, size));
    \n

    See also: al_ustr_append_cstr, al_ustr_append_chr, al_ustr_appendf, al_ustr_vappendf

    \n+

    Examples:

    \n+
      \n+
    • ex_loading_thread.c
      • \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_append_cstr

    \n 
    bool al_ustr_append_cstr(ALLEGRO_USTR *us, const char *s)
    \n

    Source\n Code

    \n

    Append C-style string s to the end of\n us.

    \n

    Returns true on success, false on error.

    \n

    See also: al_ustr_append

    \n+

    Examples:

    \n+
      \n+
    • ex_loading_thread.c
      • \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_append_chr

    \n 
    size_t al_ustr_append_chr(ALLEGRO_USTR *us, int32_t c)
    \n

    Source\n Code

    \n

    Append a code point to the end of us.

    \n

    Returns the number of bytes added, or 0 on error.

    \n

    See also: al_ustr_append

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_appendf

    \n 
    bool al_ustr_appendf(ALLEGRO_USTR *us, const char *fmt, ...)
    \n

    Source\n Code

    \n

    This function appends formatted output to the string us.\n fmt is a printf-style format string. See al_ustr_newf about the \u201c%s\u201d and \u201c%c\u201d\n specifiers.

    \n

    Returns true on success, false on error.

    \n

    See also: al_ustr_vappendf,\n al_ustr_append

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_vappendf

    \n 
    bool al_ustr_vappendf(ALLEGRO_USTR *us, const char *fmt, va_list ap)
    \n

    Source\n Code

    \n

    Like al_ustr_appendf but you\n pass the variable argument list directly, instead of the arguments\n themselves. See al_ustr_newf about\n the \u201c%s\u201d and \u201c%c\u201d specifiers.

    \n

    Returns true on success, false on error.

    \n

    See also: al_ustr_appendf, al_ustr_append

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    Removing parts of strings

    \n

    al_ustr_remove_chr

    \n 
    bool al_ustr_remove_chr(ALLEGRO_USTR *us, int pos)
    \n

    Source\n Code

    \n

    Remove the code point beginning at byte offset pos.\n Returns true on success. If pos is out of range or\n pos is not the beginning of a valid code point, returns\n false leaving the string unmodified.

    \n

    Use al_ustr_offset to find the\n byte offset for a code-points offset.

    \n

    See also: al_ustr_remove_range

    \n+

    Examples:

    \n+
      \n+
    • nihgui.cpp
      • \n+
    • ex_utf8.c
      • \n+
    • ex_logo.c
      • \n+
    \n

    al_ustr_remove_range

    \n 
    bool al_ustr_remove_range(ALLEGRO_USTR *us, int start_pos, int end_pos)
    \n

    Source\n Code

    \n

    Remove the interval [start_pos, end_pos)\n from a string. start_pos and end_pos are byte\n offsets. Both may be past the end of the string but cannot be less than\n 0 (the start of the string).

    \n

    Returns true on success, false on error.

    \n

    See also: al_ustr_remove_chr, al_ustr_truncate

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_truncate

    \n 
    bool al_ustr_truncate(ALLEGRO_USTR *us, int start_pos)
    \n

    Source\n Code

    \n

    Truncate a portion of a string from byte offset\n start_pos onwards. start_pos can be past the\n end of the string (has no effect) but cannot be less than 0.

    \n

    Returns true on success, false on error.

    \n

    See also: al_ustr_remove_range, al_ustr_ltrim_ws, al_ustr_rtrim_ws, al_ustr_trim_ws

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_ltrim_ws

    \n 
    bool al_ustr_ltrim_ws(ALLEGRO_USTR *us)
    \n

    Source\n Code

    \n

    Remove leading whitespace characters from a string, as defined by the\n C function isspace().

    \n

    Returns true on success, or false on error.

    \n

    See also: al_ustr_rtrim_ws,\n al_ustr_trim_ws

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_rtrim_ws

    \n 
    bool al_ustr_rtrim_ws(ALLEGRO_USTR *us)
    \n

    Source\n Code

    \n

    Remove trailing (\u201cright\u201d) whitespace characters from a string, as\n defined by the C function isspace().

    \n

    Returns true on success, or false on error.

    \n

    See also: al_ustr_ltrim_ws,\n al_ustr_trim_ws

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_trim_ws

    \n 
    bool al_ustr_trim_ws(ALLEGRO_USTR *us)
    \n

    Source\n Code

    \n

    Remove both leading and trailing whitespace characters from a\n string.

    \n

    Returns true on success, or false on error.

    \n

    See also: al_ustr_ltrim_ws,\n al_ustr_rtrim_ws

    \n+

    Examples:

    \n+
      \n+
    • ex_loading_thread.c
      • \n+
    • ex_utf8.c
      • \n+
    \n

    Assigning one string to\n another

    \n

    al_ustr_assign

    \n 
    bool al_ustr_assign(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)
    \n

    Source\n Code

    \n

    Overwrite the string us1 with another string\n us2. Returns true on success, false on error.

    \n

    See also: al_ustr_assign_substr, al_ustr_assign_cstr

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_assign_substr

    \n 
    bool al_ustr_assign_substr(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2,\n    int start_pos, int end_pos)
    \n

    Source\n Code

    \n

    Overwrite the string us1 with the contents of\n@@ -964,25 +1216,35 @@\n us2.

    \n

    Usually you will first have to use al_ustr_offset to find the byte\n offsets.

    \n

    Returns true on success, false on error.

    \n

    See also: al_ustr_assign, al_ustr_assign_cstr

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_assign_cstr

    \n 
    bool al_ustr_assign_cstr(ALLEGRO_USTR *us1, const char *s)
    \n

    Source\n Code

    \n

    Overwrite the string us1 with the contents of the\n C-style string s. Returns true on success, false on\n error.

    \n

    See also: al_ustr_assign_substr, al_ustr_assign_cstr

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    Replacing parts of string

    \n

    al_ustr_set_chr

    \n 
    size_t al_ustr_set_chr(ALLEGRO_USTR *us, int start_pos, int32_t c)
    \n

    Source\n Code

    \n

    Replace the code point beginning at byte offset\n@@ -992,14 +1254,21 @@\n start_pos will be padded with NUL ('\\0')\n bytes. If start_pos is not the start of a valid code point,\n that is an error and the string will be unmodified.

    \n

    On success, returns the number of bytes written, i.e.\u00a0the offset to\n the following code point. On error, returns 0.

    \n

    See also: al_ustr_replace_range

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    • ex_logo.c
      • \n+
    \n

    al_ustr_replace_range

    \n 
    bool al_ustr_replace_range(ALLEGRO_USTR *us1, int start_pos1, int end_pos1,\n    const ALLEGRO_USTR *us2)
    \n

    Source\n Code

    \n

    Replace the part of us1 in the byte interval\n@@ -1008,60 +1277,85 @@\n start_pos1 is past the end of us1 then the\n space between the end of the string and start_pos1 will be\n padded with NUL ('\\0') bytes.

    \n

    Use al_ustr_offset to find the\n byte offsets.

    \n

    Returns true on success, false on error.

    \n

    See also: al_ustr_set_chr

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    Searching

    \n

    al_ustr_find_chr

    \n 
    int al_ustr_find_chr(const ALLEGRO_USTR *us, int start_pos, int32_t c)
    \n

    Source\n Code

    \n

    Search for the encoding of code point c in\n us from byte offset start_pos (inclusive).

    \n

    Returns the position where it is found or -1 if it is not found.

    \n

    See also: al_ustr_rfind_chr

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_rfind_chr

    \n 
    int al_ustr_rfind_chr(const ALLEGRO_USTR *us, int end_pos, int32_t c)
    \n

    Source\n Code

    \n

    Search for the encoding of code point c in\n us backwards from byte offset end_pos\n (exclusive). Returns the position where it is found or -1 if it is not\n found.

    \n

    See also: al_ustr_find_chr

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_find_set

    \n 
    int al_ustr_find_set(const ALLEGRO_USTR *us, int start_pos,\n    const ALLEGRO_USTR *accept)
    \n

    Source\n Code

    \n

    This function finds the first code point in us,\n beginning from byte offset start_pos, that matches any code\n point in accept. Returns the position if a code point was\n found. Otherwise returns -1.

    \n

    See also: al_ustr_find_set_cstr, al_ustr_find_cset

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_find_set_cstr

    \n 
    int al_ustr_find_set_cstr(const ALLEGRO_USTR *us, int start_pos,\n    const char *accept)
    \n

    Source\n Code

    \n

    Like al_ustr_find_set but\n takes a C-style string for accept.

    \n

    See also: al_ustr_find_set,\n al_ustr_find_cset_cstr

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_find_cset

    \n 
    int al_ustr_find_cset(const ALLEGRO_USTR *us, int start_pos,\n    const ALLEGRO_USTR *reject)
    \n

    Source\n Code

    \n

    This function finds the first code point in us,\n@@ -1069,186 +1363,275 @@\n not match any code point in reject. In other words\n it finds a code point in the complementary set of reject.\n Returns the byte position of that code point, if any. Otherwise returns\n -1.

    \n

    See also: al_ustr_find_cset_cstr, al_ustr_find_set

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_find_cset_cstr

    \n 
    int al_ustr_find_cset_cstr(const ALLEGRO_USTR *us, int start_pos,\n    const char *reject)
    \n

    Source\n Code

    \n

    Like al_ustr_find_cset but\n takes a C-style string for reject.

    \n

    See also: al_ustr_find_cset, al_ustr_find_set_cstr

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_find_str

    \n 
    int al_ustr_find_str(const ALLEGRO_USTR *haystack, int start_pos,\n    const ALLEGRO_USTR *needle)
    \n

    Source\n Code

    \n

    Find the first occurrence of string needle in\n haystack, beginning from byte offset start_pos\n (inclusive). Return the byte offset of the occurrence if it is found,\n otherwise return -1.

    \n

    See also: al_ustr_find_cstr, al_ustr_rfind_str, al_ustr_find_replace

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_find_cstr

    \n 
    int al_ustr_find_cstr(const ALLEGRO_USTR *haystack, int start_pos,\n    const char *needle)
    \n

    Source\n Code

    \n

    Like al_ustr_find_str but\n takes a C-style string for needle.

    \n

    See also: al_ustr_find_str,\n al_ustr_rfind_cstr

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_rfind_str

    \n 
    int al_ustr_rfind_str(const ALLEGRO_USTR *haystack, int end_pos,\n    const ALLEGRO_USTR *needle)
    \n

    Source\n Code

    \n

    Find the last occurrence of string needle in\n haystack before byte offset end_pos\n (exclusive). Return the byte offset of the occurrence if it is found,\n otherwise return -1.

    \n

    See also: al_ustr_rfind_cstr, al_ustr_find_str

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_rfind_cstr

    \n 
    int al_ustr_rfind_cstr(const ALLEGRO_USTR *haystack, int end_pos,\n    const char *needle)
    \n

    Source\n Code

    \n

    Like al_ustr_rfind_str but\n takes a C-style string for needle.

    \n

    See also: al_ustr_rfind_str, al_ustr_find_cstr

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_find_replace

    \n 
    bool al_ustr_find_replace(ALLEGRO_USTR *us, int start_pos,\n    const ALLEGRO_USTR *find, const ALLEGRO_USTR *replace)
    \n

    Source\n Code

    \n

    Replace all occurrences of find in us with\n replace, beginning at byte offset start_pos.\n The find string must be non-empty. Returns true on success,\n false on error.

    \n

    See also: al_ustr_find_replace_cstr

    \n+

    Examples:

    \n+
      \n+
    • ex_loading_thread.c
      • \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_find_replace_cstr

    \n 
    bool al_ustr_find_replace_cstr(ALLEGRO_USTR *us, int start_pos,\n    const char *find, const char *replace)
    \n

    Source\n Code

    \n

    Like al_ustr_find_replace but takes\n C-style strings for find and replace.

    \n+

    Examples:

    \n+
      \n+
    • ex_loading_thread.c
      • \n+
    • ex_utf8.c
      • \n+
    \n

    Comparing

    \n

    al_ustr_equal

    \n 
    bool al_ustr_equal(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)
    \n

    Source\n Code

    \n

    Return true iff the two strings are equal. This function is more\n efficient than al_ustr_compare\n so is preferable if ordering is not important.

    \n

    See also: al_ustr_compare

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_compare

    \n 
    int al_ustr_compare(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)
    \n

    Source\n Code

    \n

    This function compares us1 and us2 by code\n point values. Returns zero if the strings are equal, a positive number\n if us1 comes after us2, else a negative\n number.

    \n

    This does not take into account locale-specific sorting\n rules. For that you will need to use another library.

    \n

    See also: al_ustr_ncompare,\n al_ustr_equal

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_ncompare

    \n 
    int al_ustr_ncompare(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2, int n)
    \n

    Source\n Code

    \n

    Like al_ustr_compare but only\n compares up to the first n code points of both strings.

    \n

    Returns zero if the strings are equal, a positive number if\n us1 comes after us2, else a negative\n number.

    \n

    See also: al_ustr_compare, al_ustr_equal

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_has_prefix

    \n 
    bool al_ustr_has_prefix(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)
    \n

    Source\n Code

    \n

    Returns true iff us1 begins with us2.

    \n

    See also: al_ustr_has_prefix_cstr, al_ustr_has_suffix

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_has_prefix_cstr

    \n 
    bool al_ustr_has_prefix_cstr(const ALLEGRO_USTR *us1, const char *s2)
    \n

    Source\n Code

    \n

    Returns true iff us1 begins with s2.

    \n

    See also: al_ustr_has_prefix, al_ustr_has_suffix_cstr

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_has_suffix

    \n 
    bool al_ustr_has_suffix(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)
    \n

    Source\n Code

    \n

    Returns true iff us1 ends with us2.

    \n

    See also: al_ustr_has_suffix_cstr, al_ustr_has_prefix

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_has_suffix_cstr

    \n 
    bool al_ustr_has_suffix_cstr(const ALLEGRO_USTR *us1, const char *s2)
    \n

    Source\n Code

    \n

    Returns true iff us1 ends with s2.

    \n

    See also: al_ustr_has_suffix, al_ustr_has_prefix_cstr

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    UTF-16 conversion

    \n

    al_ustr_new_from_utf16

    \n 
    ALLEGRO_USTR *al_ustr_new_from_utf16(uint16_t const *s)
    \n

    Source\n Code

    \n

    Create a new string containing a copy of the 0-terminated string\n s which must be encoded as UTF-16. The string must\n eventually be freed with al_ustr_free.

    \n

    See also: al_ustr_new

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_size_utf16

    \n 
    size_t al_ustr_size_utf16(const ALLEGRO_USTR *us)
    \n

    Source\n Code

    \n

    Returns the number of bytes required to encode the string in UTF-16\n (including the terminating 0). Usually called before al_ustr_encode_utf16 to\n determine the size of the buffer to allocate.

    \n

    See also: al_ustr_size

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    al_ustr_encode_utf16

    \n 
    size_t al_ustr_encode_utf16(const ALLEGRO_USTR *us, uint16_t *s,\n    size_t n)
    \n

    Source\n Code

    \n

    Encode the string into the given buffer, in UTF-16. Returns the\n@@ -1256,37 +1639,56 @@\n written. The minimum size to encode the complete string can be queried\n with al_ustr_size_utf16. If\n the n parameter is smaller than that, the string will be\n truncated but still always 0 terminated.

    \n

    See also: al_ustr_size_utf16, al_utf16_encode

    \n+

    Examples:

    \n+
      \n+
    • ex_utf8.c
      • \n+
    \n

    Low-level UTF-8 routines

    \n

    al_utf8_width

    \n 
    size_t al_utf8_width(int32_t c)
    \n

    Source\n Code

    \n

    Returns the number of bytes that would be occupied by the specified\n code point when encoded in UTF-8. This is between 1 and 4 bytes for\n legal code point values. Otherwise returns 0.

    \n

    See also: al_utf8_encode, al_utf16_width

    \n+

    Examples:

    \n+
      \n+
    • nihgui.cpp
      • \n+
    • ex_utf8.c
      • \n+
    \n

    al_utf8_encode

    \n 
    size_t al_utf8_encode(char s[], int32_t c)
    \n

    Source\n Code

    \n

    Encode the specified code point to UTF-8 into the buffer\n s. The buffer must have enough space to hold the encoding,\n which takes between 1 and 4 bytes. This routine will refuse to encode\n code points above 0x10FFFF.

    \n

    Returns the number of bytes written, which is the same as that\n returned by al_utf8_width.

    \n

    See also: al_utf16_encode

    \n+

    Examples:

    \n+
      \n+
    • ex_keyboard_events.c
      • \n+
    • ex_utf8.c
      • \n+
    \n

    Low-level UTF-16 routines

    \n

    al_utf16_width

    \n 
    size_t al_utf16_width(int c)
    \n

    Source\n Code

    \n

    Returns the number of bytes that would be occupied by the specified\n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -195,35 +195,49 @@\n *\b**\b**\b**\b**\b**\b* U\bUT\bTF\bF-\b-8\b8 s\bst\btr\bri\bin\bng\bg t\bty\byp\bpe\bes\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_U\bUS\bST\bTR\bR *\b**\b**\b**\b**\b*\n typedef struct _al_tagbstring ALLEGRO_USTR;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n An opaque type representing a string. ALLEGRO_USTRs normally contain UTF-\n 8 encoded strings, but they may be used to hold any byte sequences, including\n NULs.\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b._\bc_\bp_\bp\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b._\bc\n *\b**\b**\b**\b**\b* A\bAL\bLL\bLE\bEG\bGR\bRO\bO_\b_U\bUS\bST\bTR\bR_\b_I\bIN\bNF\bFO\bO *\b**\b**\b**\b**\b*\n typedef struct _al_tagbstring ALLEGRO_USTR_INFO;\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n A type that holds additional information for an _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bU_\bS_\bT_\bR that references an\n external memory buffer. You can convert it back to _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bU_\bS_\bT_\bR via\n _\ba_\bl_\b__\br_\be_\bf_\b__\bi_\bn_\bf_\bo.\n See also: _\ba_\bl_\b__\br_\be_\bf_\b__\bc_\bs_\bt_\br, _\ba_\bl_\b__\br_\be_\bf_\b__\bb_\bu_\bf_\bf_\be_\br, _\ba_\bl_\b__\br_\be_\bf_\b__\bi_\bn_\bf_\bo and _\ba_\bl_\b__\br_\be_\bf_\b__\bu_\bs_\bt_\br.\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b._\bc_\bp_\bp\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b._\bc\n *\b**\b**\b**\b**\b**\b* C\bCr\bre\bea\bat\bti\bin\bng\bg a\ban\bnd\bd d\bde\bes\bst\btr\bro\boy\byi\bin\bng\bg s\bst\btr\bri\bin\bng\bgs\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_n\bne\bew\bw *\b**\b**\b**\b**\b*\n ALLEGRO_USTR *al_ustr_new(const char *s)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a new string containing a copy of the C-style string s. The string must\n eventually be freed with _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\br_\be_\be.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bn_\be_\bw_\b__\bf_\br_\bo_\bm_\b__\bb_\bu_\bf_\bf_\be_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bn_\be_\bw_\bf, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bd_\bu_\bp,\n _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bn_\be_\bw_\b__\bf_\br_\bo_\bm_\b__\bu_\bt_\bf_\b1_\b6\n+Examples:\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_n\bne\bew\bw_\b_f\bfr\bro\bom\bm_\b_b\bbu\buf\bff\bfe\ber\br *\b**\b**\b**\b**\b*\n ALLEGRO_USTR *al_ustr_new_from_buffer(const char *s, size_t size)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a new string containing a copy of the buffer pointed to by s of the\n given size in bytes. The string must eventually be freed with _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\br_\be_\be.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bn_\be_\bw\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_n\bne\bew\bwf\bf *\b**\b**\b**\b**\b*\n ALLEGRO_USTR *al_ustr_newf(const char *fmt, ...)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a new string using a printf-style format string.\n N\bNo\bot\bte\bes\bs:\b:\n The \u201c%s\u201d specifier takes C string arguments, not ALLEGRO_USTRs. Therefore to\n pass an ALLEGRO_USTR as a parameter you must use _\ba_\bl_\b__\bc_\bs_\bt_\br, and it must be NUL\n@@ -231,19 +245,25 @@\n byte onwards will be ignored.\n The \u201c%c\u201d specifier outputs a single byte, not the UTF-8 encoding of a code\n point. Therefore it is only usable for ASCII characters (value <= 127) or if\n you really mean to output byte values from 128\u2013255. To insert the UTF-\n 8 encoding of a code point, encode it into a memory buffer using _\ba_\bl_\b__\bu_\bt_\bf_\b8_\b__\be_\bn_\bc_\bo_\bd_\be\n then use the \u201c%s\u201d specifier. Remember to NUL terminate the buffer.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bn_\be_\bw, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bp_\bp_\be_\bn_\bd_\bf\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_f\bfr\bre\bee\be *\b**\b**\b**\b**\b*\n void al_ustr_free(ALLEGRO_USTR *us)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Free a previously allocated string. Does nothing if the argument is NULL.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bn_\be_\bw, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bn_\be_\bw_\b__\bf_\br_\bo_\bm_\b__\bb_\bu_\bf_\bf_\be_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bn_\be_\bw_\bf\n+Examples:\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcs\bst\btr\br *\b**\b**\b**\b**\b*\n const char *al_cstr(const ALLEGRO_USTR *us)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get a char * pointer to the data in a string. This pointer will only be valid\n while the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bU_\bS_\bT_\bR object is not modified and not destroyed. The pointer\n may be passed to functions expecting C-style strings, with the following\n caveats:\n@@ -253,74 +273,95 @@\n terminated. A string which is dynamically allocated will always be NUL\n terminated, but a string which references the middle of another string or\n region of memory will n\bno\bot\bt be NUL terminated.\n * If the ALLEGRO_USTR references another string, the returned C string will\n point into the referenced string. Again, no NUL terminator will be added\n to the referenced string.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bt_\bo_\b__\bb_\bu_\bf_\bf_\be_\br, _\ba_\bl_\b__\bc_\bs_\bt_\br_\b__\bd_\bu_\bp\n+Examples:\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_t\bto\bo_\b_b\bbu\buf\bff\bfe\ber\br *\b**\b**\b**\b**\b*\n void al_ustr_to_buffer(const ALLEGRO_USTR *us, char *buffer, int size)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Write the contents of the string into a pre-allocated buffer of the given size\n in bytes. The result will always be NUL terminated, so a maximum of size - 1\n bytes will be copied.\n See also: _\ba_\bl_\b__\bc_\bs_\bt_\br, _\ba_\bl_\b__\bc_\bs_\bt_\br_\b__\bd_\bu_\bp\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcs\bst\btr\br_\b_d\bdu\bup\bp *\b**\b**\b**\b**\b*\n char *al_cstr_dup(const ALLEGRO_USTR *us)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a NUL ('\\0') terminated copy of the string. Any embedded NUL bytes will\n still be presented in the returned string. The new string must eventually be\n freed with _\ba_\bl_\b__\bf_\br_\be_\be.\n If an error occurs NULL is returned.\n See also: _\ba_\bl_\b__\bc_\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bt_\bo_\b__\bb_\bu_\bf_\bf_\be_\br, _\ba_\bl_\b__\bf_\br_\be_\be\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_d\bdu\bup\bp *\b**\b**\b**\b**\b*\n ALLEGRO_USTR *al_ustr_dup(const ALLEGRO_USTR *us)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return a duplicate copy of a string. The new string will need to be freed with\n _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\br_\be_\be.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bd_\bu_\bp_\b__\bs_\bu_\bb_\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\br_\be_\be\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_d\bdu\bup\bp_\b_s\bsu\bub\bbs\bst\btr\br *\b**\b**\b**\b**\b*\n ALLEGRO_USTR *al_ustr_dup_substr(const ALLEGRO_USTR *us, int start_pos,\n int end_pos)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return a new copy of a string, containing its contents in the byte interval\n [start_pos, end_pos). The new string will be NUL terminated and will need to be\n freed with _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\br_\be_\be.\n If necessary, use _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bo_\bf_\bf_\bs_\be_\bt to find the byte offsets for a given code\n point that you are interested in.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bd_\bu_\bp, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\br_\be_\be\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b**\b* P\bPr\bre\bed\bde\bef\bfi\bin\bne\bed\bd s\bst\btr\bri\bin\bng\bgs\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_e\bem\bmp\bpt\bty\by_\b_s\bst\btr\bri\bin\bng\bg *\b**\b**\b**\b**\b*\n const ALLEGRO_USTR *al_ustr_empty_string(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return a pointer to a static empty string. The string is read only and must not\n be freed.\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b**\b* C\bCr\bre\bea\bat\bti\bin\bng\bg s\bst\btr\bri\bin\bng\bgs\bs b\bby\by r\bre\bef\bfe\ber\bre\ben\bnc\bci\bin\bng\bg o\bot\bth\bhe\ber\br d\bda\bat\bta\ba *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bef\bf_\b_c\bcs\bst\btr\br *\b**\b**\b**\b**\b*\n const ALLEGRO_USTR *al_ref_cstr(ALLEGRO_USTR_INFO *info, const char *s)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a string that references the storage of a C-style string. The\n information about the string (e.g.\u00a0its size) is stored in the structure pointed\n to by the info parameter. The string will not have any other storage allocated\n of its own, so if you allocate the info structure on the stack then no explicit\n \u201cfree\u201d operation is required.\n The string is valid until the underlying C string disappears.\n Example:\n ALLEGRO_USTR_INFO info;\n ALLEGRO_USTR *us = al_ref_cstr(&info, \"my string\");\n See also: _\ba_\bl_\b__\br_\be_\bf_\b__\bb_\bu_\bf_\bf_\be_\br, _\ba_\bl_\b__\br_\be_\bf_\b__\bu_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b._\bc\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bef\bf_\b_b\bbu\buf\bff\bfe\ber\br *\b**\b**\b**\b**\b*\n const ALLEGRO_USTR *al_ref_buffer(ALLEGRO_USTR_INFO *info, const char *s,\n size_t size)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a string that references the storage of an underlying buffer. The size\n of the buffer is given in bytes. You can use it to reference only part of a\n string or an arbitrary region of memory.\n The string is valid while the underlying memory buffer is valid.\n See also: _\ba_\bl_\b__\br_\be_\bf_\b__\bc_\bs_\bt_\br, _\ba_\bl_\b__\br_\be_\bf_\b__\bu_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bf_\bo_\bn_\bt_\b__\bm_\bu_\bl_\bt_\bi_\bl_\bi_\bn_\be_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bef\bf_\b_u\bus\bst\btr\br *\b**\b**\b**\b**\b*\n const ALLEGRO_USTR *al_ref_ustr(ALLEGRO_USTR_INFO *info, const ALLEGRO_USTR\n *us,\n int start_pos, int end_pos)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a read-only string that references the storage of another _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bU_\bS_\bT_\bR\n string. The information about the string (e.g.\u00a0its size) is stored in the\n@@ -328,14 +369,18 @@\n other storage allocated of its own, so if you allocate the info structure on\n the stack then no explicit \u201cfree\u201d operation is required.\n The referenced interval is [start_pos, end_pos). Both are byte offsets.\n The string is valid until the underlying string is modified or destroyed.\n If you need a range of code-points instead of bytes, use _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bo_\bf_\bf_\bs_\be_\bt to find\n the byte offsets.\n See also: _\ba_\bl_\b__\br_\be_\bf_\b__\bc_\bs_\bt_\br, _\ba_\bl_\b__\br_\be_\bf_\b__\bb_\bu_\bf_\bf_\be_\br\n+Examples:\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b._\bc\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_r\bre\bef\bf_\b_i\bin\bnf\bfo\bo *\b**\b**\b**\b**\b*\n const ALLEGRO_USTR *al_ref_info(const ALLEGRO_USTR_INFO *info)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a read-only string that references the storage of another _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bU_\bS_\bT_\bR\n string that has already been stored in the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bU_\bS_\bT_\bR_\b__\bI_\bN_\bF_\bO structure.\n The string is valid until the underlying string is modified or destroyed.\n See also: _\ba_\bl_\b__\br_\be_\bf_\b__\bc_\bs_\bt_\br, _\ba_\bl_\b__\br_\be_\bf_\b__\bb_\bu_\bf_\bf_\be_\br, _\ba_\bl_\b__\br_\be_\bf_\b__\bu_\bs_\bt_\br\n@@ -343,405 +388,528 @@\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_s\bsi\biz\bze\be *\b**\b**\b**\b**\b*\n size_t al_ustr_size(const ALLEGRO_USTR *us)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the size of the string in bytes. This is equal to the number of code\n points in the string if the string is empty or contains only 7-bit ASCII\n characters.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bl_\be_\bn_\bg_\bt_\bh\n+Examples:\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_l\ble\ben\bng\bgt\bth\bh *\b**\b**\b**\b**\b*\n size_t al_ustr_length(const ALLEGRO_USTR *us)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the number of code points in the string.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bs_\bi_\bz_\be, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bo_\bf_\bf_\bs_\be_\bt\n+Examples:\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b._\bc\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_o\bof\bff\bfs\bse\bet\bt *\b**\b**\b**\b**\b*\n int al_ustr_offset(const ALLEGRO_USTR *us, int index)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the byte offset (from the start of the string) of the code point at the\n specified index in the string. A zero index parameter will return the first\n character of the string. If index is negative, it counts backward from the end\n of the string, so an index of -1 will return an offset to the last code point.\n If the index is past the end of the string, returns the offset of the end of\n the string.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bl_\be_\bn_\bg_\bt_\bh\n+Examples:\n+ * _\be_\bx_\b__\bb_\bl_\be_\bn_\bd_\b._\bc\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_n\bne\bex\bxt\bt *\b**\b**\b**\b**\b*\n bool al_ustr_next(const ALLEGRO_USTR *us, int *pos)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Find the byte offset of the next code point in string, beginning at *pos. *pos\n does not have to be at the beginning of a code point.\n Returns true on success, and the value pointed to by pos will be updated to the\n found offset. Otherwise returns false if *pos was already at the end of the\n string, and *pos is unmodified.\n This function just looks for an appropriate byte; it doesn\u2019t check if found\n offset is the beginning of a valid code point. If you are working with possibly\n invalid UTF-8 strings then it could skip over some invalid bytes.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bp_\br_\be_\bv\n+Examples:\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_p\bpr\bre\bev\bv *\b**\b**\b**\b**\b*\n bool al_ustr_prev(const ALLEGRO_USTR *us, int *pos)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Find the byte offset of the previous code point in string, before *pos. *pos\n does not have to be at the beginning of a code point. Returns true on success,\n and the value pointed to by pos will be updated to the found offset. Otherwise\n returns false if *pos was already at the end of the string, and *pos is\n unmodified.\n This function just looks for an appropriate byte; it doesn\u2019t check if found\n offset is the beginning of a valid code point. If you are working with possibly\n invalid UTF-8 strings then it could skip over some invalid bytes.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bn_\be_\bx_\bt\n+Examples:\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\bg_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* G\bGe\bet\btt\bti\bin\bng\bg c\bco\bod\bde\be p\bpo\boi\bin\bnt\bts\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_g\bge\bet\bt *\b**\b**\b**\b**\b*\n int32_t al_ustr_get(const ALLEGRO_USTR *ub, int pos)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return the code point in ub beginning at byte offset pos.\n On success returns the code point value. If pos was out of bounds (e.g.\u00a0past\n the end of the string), return -1. On an error, such as an invalid byte\n sequence, return -2.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bg_\be_\bt_\b__\bn_\be_\bx_\bt, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bp_\br_\be_\bv_\b__\bg_\be_\bt\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n+ * _\be_\bx_\b__\bt_\bt_\bf_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_g\bge\bet\bt_\b_n\bne\bex\bxt\bt *\b**\b**\b**\b**\b*\n int32_t al_ustr_get_next(const ALLEGRO_USTR *us, int *pos)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Find the code point in us beginning at byte offset *pos, then advance to the\n next code point.\n On success return the code point value. If pos was out of bounds (e.g.\u00a0past the\n end of the string), return -1. On an error, such as an invalid byte sequence,\n return -2. As with _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bn_\be_\bx_\bt, invalid byte sequences may be skipped while\n advancing.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bg_\be_\bt, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bp_\br_\be_\bv_\b__\bg_\be_\bt\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_p\bpr\bre\bev\bv_\b_g\bge\bet\bt *\b**\b**\b**\b**\b*\n int32_t al_ustr_prev_get(const ALLEGRO_USTR *us, int *pos)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Find the beginning of a code point before byte offset *pos, then return it.\n Note this performs a p\bpr\bre\be-\b-i\bin\bnc\bcr\bre\bem\bme\ben\bnt\bt.\n On success returns the code point value. If pos was out of bounds (e.g.\u00a0past\n the end of the string), return -1. On an error, such as an invalid byte\n sequence, return -2. As with _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bp_\br_\be_\bv, invalid byte sequences may be\n skipped while advancing.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bg_\be_\bt_\b__\bn_\be_\bx_\bt\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b**\b* I\bIn\bns\bse\ber\brt\bti\bin\bng\bg i\bin\bnt\bto\bo s\bst\btr\bri\bin\bng\bgs\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_i\bin\bns\bse\ber\brt\bt *\b**\b**\b**\b**\b*\n bool al_ustr_insert(ALLEGRO_USTR *us1, int pos, const ALLEGRO_USTR *us2)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Insert us2 into us1 beginning at byte offset pos. pos cannot be less than 0. If\n pos is past the end of us1 then the space between the end of the string and pos\n will be padded with NUL ('\\0') bytes.\n If required, use _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bo_\bf_\bf_\bs_\be_\bt to find the byte offset for a given code point\n index.\n Returns true on success, false on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bi_\bn_\bs_\be_\br_\bt_\b__\bc_\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bi_\bn_\bs_\be_\br_\bt_\b__\bc_\bh_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bp_\bp_\be_\bn_\bd,\n _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bo_\bf_\bf_\bs_\be_\bt\n+Examples:\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_i\bin\bns\bse\ber\brt\bt_\b_c\bcs\bst\btr\br *\b**\b**\b**\b**\b*\n bool al_ustr_insert_cstr(ALLEGRO_USTR *us, int pos, const char *s)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bi_\bn_\bs_\be_\br_\bt but inserts a C-style string at byte offset pos.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bi_\bn_\bs_\be_\br_\bt, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bi_\bn_\bs_\be_\br_\bt_\b__\bc_\bh_\br\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_i\bin\bns\bse\ber\brt\bt_\b_c\bch\bhr\br *\b**\b**\b**\b**\b*\n size_t al_ustr_insert_chr(ALLEGRO_USTR *us, int pos, int32_t c)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Insert a code point into us beginning at byte offset pos. pos cannot be less\n than 0. If pos is past the end of us then the space between the end of the\n string and pos will be padded with NUL ('\\0') bytes.\n Returns the number of bytes inserted, or 0 on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bi_\bn_\bs_\be_\br_\bt, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bi_\bn_\bs_\be_\br_\bt_\b__\bc_\bs_\bt_\br\n+Examples:\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAp\bpp\bpe\ben\bnd\bdi\bin\bng\bg t\bto\bo s\bst\btr\bri\bin\bng\bgs\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_a\bap\bpp\bpe\ben\bnd\bd *\b**\b**\b**\b**\b*\n bool al_ustr_append(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Append us2 to the end of us1.\n Returns true on success, false on error.\n This function can be used to append an arbitrary buffer:\n ALLEGRO_USTR_INFO info;\n al_ustr_append(us, al_ref_buffer(&info, buf, size));\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bp_\bp_\be_\bn_\bd_\b__\bc_\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bp_\bp_\be_\bn_\bd_\b__\bc_\bh_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bp_\bp_\be_\bn_\bd_\bf,\n _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bv_\ba_\bp_\bp_\be_\bn_\bd_\bf\n+Examples:\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_a\bap\bpp\bpe\ben\bnd\bd_\b_c\bcs\bst\btr\br *\b**\b**\b**\b**\b*\n bool al_ustr_append_cstr(ALLEGRO_USTR *us, const char *s)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Append C-style string s to the end of us.\n Returns true on success, false on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bp_\bp_\be_\bn_\bd\n+Examples:\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_a\bap\bpp\bpe\ben\bnd\bd_\b_c\bch\bhr\br *\b**\b**\b**\b**\b*\n size_t al_ustr_append_chr(ALLEGRO_USTR *us, int32_t c)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Append a code point to the end of us.\n Returns the number of bytes added, or 0 on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bp_\bp_\be_\bn_\bd\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_a\bap\bpp\bpe\ben\bnd\bdf\bf *\b**\b**\b**\b**\b*\n bool al_ustr_appendf(ALLEGRO_USTR *us, const char *fmt, ...)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This function appends formatted output to the string us. fmt is a printf-style\n format string. See _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bn_\be_\bw_\bf about the \u201c%s\u201d and \u201c%c\u201d specifiers.\n Returns true on success, false on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bv_\ba_\bp_\bp_\be_\bn_\bd_\bf, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bp_\bp_\be_\bn_\bd\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_v\bva\bap\bpp\bpe\ben\bnd\bdf\bf *\b**\b**\b**\b**\b*\n bool al_ustr_vappendf(ALLEGRO_USTR *us, const char *fmt, va_list ap)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bp_\bp_\be_\bn_\bd_\bf but you pass the variable argument list directly, instead\n of the arguments themselves. See _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bn_\be_\bw_\bf about the \u201c%s\u201d and \u201c%c\u201d\n specifiers.\n Returns true on success, false on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bp_\bp_\be_\bn_\bd_\bf, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bp_\bp_\be_\bn_\bd\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b**\b* R\bRe\bem\bmo\bov\bvi\bin\bng\bg p\bpa\bar\brt\bts\bs o\bof\bf s\bst\btr\bri\bin\bng\bgs\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_r\bre\bem\bmo\bov\bve\be_\b_c\bch\bhr\br *\b**\b**\b**\b**\b*\n bool al_ustr_remove_chr(ALLEGRO_USTR *us, int pos)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Remove the code point beginning at byte offset pos. Returns true on success. If\n pos is out of range or pos is not the beginning of a valid code point, returns\n false leaving the string unmodified.\n Use _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bo_\bf_\bf_\bs_\be_\bt to find the byte offset for a code-points offset.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\br_\be_\bm_\bo_\bv_\be_\b__\br_\ba_\bn_\bg_\be\n+Examples:\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\bg_\bo_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_r\bre\bem\bmo\bov\bve\be_\b_r\bra\ban\bng\bge\be *\b**\b**\b**\b**\b*\n bool al_ustr_remove_range(ALLEGRO_USTR *us, int start_pos, int end_pos)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Remove the interval [start_pos, end_pos) from a string. start_pos and end_pos\n are byte offsets. Both may be past the end of the string but cannot be less\n than 0 (the start of the string).\n Returns true on success, false on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\br_\be_\bm_\bo_\bv_\be_\b__\bc_\bh_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bt_\br_\bu_\bn_\bc_\ba_\bt_\be\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_t\btr\bru\bun\bnc\bca\bat\bte\be *\b**\b**\b**\b**\b*\n bool al_ustr_truncate(ALLEGRO_USTR *us, int start_pos)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Truncate a portion of a string from byte offset start_pos onwards. start_pos\n can be past the end of the string (has no effect) but cannot be less than 0.\n Returns true on success, false on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\br_\be_\bm_\bo_\bv_\be_\b__\br_\ba_\bn_\bg_\be, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bl_\bt_\br_\bi_\bm_\b__\bw_\bs, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\br_\bt_\br_\bi_\bm_\b__\bw_\bs,\n _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bt_\br_\bi_\bm_\b__\bw_\bs\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_l\blt\btr\bri\bim\bm_\b_w\bws\bs *\b**\b**\b**\b**\b*\n bool al_ustr_ltrim_ws(ALLEGRO_USTR *us)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Remove leading whitespace characters from a string, as defined by the C\n function isspace().\n Returns true on success, or false on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\br_\bt_\br_\bi_\bm_\b__\bw_\bs, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bt_\br_\bi_\bm_\b__\bw_\bs\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_r\brt\btr\bri\bim\bm_\b_w\bws\bs *\b**\b**\b**\b**\b*\n bool al_ustr_rtrim_ws(ALLEGRO_USTR *us)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Remove trailing (\u201cright\u201d) whitespace characters from a string, as defined by\n the C function isspace().\n Returns true on success, or false on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bl_\bt_\br_\bi_\bm_\b__\bw_\bs, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bt_\br_\bi_\bm_\b__\bw_\bs\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_t\btr\bri\bim\bm_\b_w\bws\bs *\b**\b**\b**\b**\b*\n bool al_ustr_trim_ws(ALLEGRO_USTR *us)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Remove both leading and trailing whitespace characters from a string.\n Returns true on success, or false on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bl_\bt_\br_\bi_\bm_\b__\bw_\bs, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\br_\bt_\br_\bi_\bm_\b__\bw_\bs\n+Examples:\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b**\b* A\bAs\bss\bsi\big\bgn\bni\bin\bng\bg o\bon\bne\be s\bst\btr\bri\bin\bng\bg t\bto\bo a\ban\bno\bot\bth\bhe\ber\br *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_a\bas\bss\bsi\big\bgn\bn *\b**\b**\b**\b**\b*\n bool al_ustr_assign(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Overwrite the string us1 with another string us2. Returns true on success,\n false on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bs_\bs_\bi_\bg_\bn_\b__\bs_\bu_\bb_\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bs_\bs_\bi_\bg_\bn_\b__\bc_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_a\bas\bss\bsi\big\bgn\bn_\b_s\bsu\bub\bbs\bst\btr\br *\b**\b**\b**\b**\b*\n bool al_ustr_assign_substr(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2,\n int start_pos, int end_pos)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Overwrite the string us1 with the contents of us2 in the byte interval\n [start_pos, end_pos). The end points will be clamped to the bounds of us2.\n Usually you will first have to use _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bo_\bf_\bf_\bs_\be_\bt to find the byte offsets.\n Returns true on success, false on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bs_\bs_\bi_\bg_\bn, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bs_\bs_\bi_\bg_\bn_\b__\bc_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_a\bas\bss\bsi\big\bgn\bn_\b_c\bcs\bst\btr\br *\b**\b**\b**\b**\b*\n bool al_ustr_assign_cstr(ALLEGRO_USTR *us1, const char *s)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Overwrite the string us1 with the contents of the C-style string s. Returns\n true on success, false on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bs_\bs_\bi_\bg_\bn_\b__\bs_\bu_\bb_\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\ba_\bs_\bs_\bi_\bg_\bn_\b__\bc_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b**\b* R\bRe\bep\bpl\bla\bac\bci\bin\bng\bg p\bpa\bar\brt\bts\bs o\bof\bf s\bst\btr\bri\bin\bng\bg *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_s\bse\bet\bt_\b_c\bch\bhr\br *\b**\b**\b**\b**\b*\n size_t al_ustr_set_chr(ALLEGRO_USTR *us, int start_pos, int32_t c)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Replace the code point beginning at byte offset start_pos with c. start_pos\n cannot be less than 0. If start_pos is past the end of us then the space\n between the end of the string and start_pos will be padded with NUL ('\\0')\n bytes. If start_pos is not the start of a valid code point, that is an error\n and the string will be unmodified.\n On success, returns the number of bytes written, i.e.\u00a0the offset to the\n following code point. On error, returns 0.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\br_\be_\bp_\bl_\ba_\bc_\be_\b__\br_\ba_\bn_\bg_\be\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n+ * _\be_\bx_\b__\bl_\bo_\bg_\bo_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_r\bre\bep\bpl\bla\bac\bce\be_\b_r\bra\ban\bng\bge\be *\b**\b**\b**\b**\b*\n bool al_ustr_replace_range(ALLEGRO_USTR *us1, int start_pos1, int end_pos1,\n const ALLEGRO_USTR *us2)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Replace the part of us1 in the byte interval [start_pos1, end_pos1) with the\n contents of us2. start_pos1 cannot be less than 0. If start_pos1 is past the\n end of us1 then the space between the end of the string and start_pos1 will be\n padded with NUL ('\\0') bytes.\n Use _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bo_\bf_\bf_\bs_\be_\bt to find the byte offsets.\n Returns true on success, false on error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bs_\be_\bt_\b__\bc_\bh_\br\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b**\b* S\bSe\bea\bar\brc\bch\bhi\bin\bng\bg *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_f\bfi\bin\bnd\bd_\b_c\bch\bhr\br *\b**\b**\b**\b**\b*\n int al_ustr_find_chr(const ALLEGRO_USTR *us, int start_pos, int32_t c)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Search for the encoding of code point c in us from byte offset start_pos\n (inclusive).\n Returns the position where it is found or -1 if it is not found.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\br_\bf_\bi_\bn_\bd_\b__\bc_\bh_\br\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_r\brf\bfi\bin\bnd\bd_\b_c\bch\bhr\br *\b**\b**\b**\b**\b*\n int al_ustr_rfind_chr(const ALLEGRO_USTR *us, int end_pos, int32_t c)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Search for the encoding of code point c in us backwards from byte offset\n end_pos (exclusive). Returns the position where it is found or -1 if it is not\n found.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bc_\bh_\br\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_f\bfi\bin\bnd\bd_\b_s\bse\bet\bt *\b**\b**\b**\b**\b*\n int al_ustr_find_set(const ALLEGRO_USTR *us, int start_pos,\n const ALLEGRO_USTR *accept)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This function finds the first code point in us, beginning from byte offset\n start_pos, that matches any code point in accept. Returns the position if a\n code point was found. Otherwise returns -1.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bs_\be_\bt_\b__\bc_\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bc_\bs_\be_\bt\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_f\bfi\bin\bnd\bd_\b_s\bse\bet\bt_\b_c\bcs\bst\btr\br *\b**\b**\b**\b**\b*\n int al_ustr_find_set_cstr(const ALLEGRO_USTR *us, int start_pos,\n const char *accept)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bs_\be_\bt but takes a C-style string for accept.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bs_\be_\bt, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bc_\bs_\be_\bt_\b__\bc_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_f\bfi\bin\bnd\bd_\b_c\bcs\bse\bet\bt *\b**\b**\b**\b**\b*\n int al_ustr_find_cset(const ALLEGRO_USTR *us, int start_pos,\n const ALLEGRO_USTR *reject)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This function finds the first code point in us, beginning from byte offset\n start_pos, that does n\bno\bot\bt match any code point in reject. In other words it\n finds a code point in the complementary set of reject. Returns the byte\n position of that code point, if any. Otherwise returns -1.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bc_\bs_\be_\bt_\b__\bc_\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bs_\be_\bt\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_f\bfi\bin\bnd\bd_\b_c\bcs\bse\bet\bt_\b_c\bcs\bst\btr\br *\b**\b**\b**\b**\b*\n int al_ustr_find_cset_cstr(const ALLEGRO_USTR *us, int start_pos,\n const char *reject)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bc_\bs_\be_\bt but takes a C-style string for reject.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bc_\bs_\be_\bt, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bs_\be_\bt_\b__\bc_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_f\bfi\bin\bnd\bd_\b_s\bst\btr\br *\b**\b**\b**\b**\b*\n int al_ustr_find_str(const ALLEGRO_USTR *haystack, int start_pos,\n const ALLEGRO_USTR *needle)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Find the first occurrence of string needle in haystack, beginning from byte\n offset start_pos (inclusive). Return the byte offset of the occurrence if it is\n found, otherwise return -1.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bc_\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\br_\bf_\bi_\bn_\bd_\b__\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\br_\be_\bp_\bl_\ba_\bc_\be\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_f\bfi\bin\bnd\bd_\b_c\bcs\bst\btr\br *\b**\b**\b**\b**\b*\n int al_ustr_find_cstr(const ALLEGRO_USTR *haystack, int start_pos,\n const char *needle)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bs_\bt_\br but takes a C-style string for needle.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\br_\bf_\bi_\bn_\bd_\b__\bc_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_r\brf\bfi\bin\bnd\bd_\b_s\bst\btr\br *\b**\b**\b**\b**\b*\n int al_ustr_rfind_str(const ALLEGRO_USTR *haystack, int end_pos,\n const ALLEGRO_USTR *needle)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Find the last occurrence of string needle in haystack before byte offset\n end_pos (exclusive). Return the byte offset of the occurrence if it is found,\n otherwise return -1.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\br_\bf_\bi_\bn_\bd_\b__\bc_\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_r\brf\bfi\bin\bnd\bd_\b_c\bcs\bst\btr\br *\b**\b**\b**\b**\b*\n int al_ustr_rfind_cstr(const ALLEGRO_USTR *haystack, int end_pos,\n const char *needle)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\br_\bf_\bi_\bn_\bd_\b__\bs_\bt_\br but takes a C-style string for needle.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\br_\bf_\bi_\bn_\bd_\b__\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\bc_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_f\bfi\bin\bnd\bd_\b_r\bre\bep\bpl\bla\bac\bce\be *\b**\b**\b**\b**\b*\n bool al_ustr_find_replace(ALLEGRO_USTR *us, int start_pos,\n const ALLEGRO_USTR *find, const ALLEGRO_USTR *replace)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Replace all occurrences of find in us with replace, beginning at byte offset\n start_pos. The find string must be non-empty. Returns true on success, false on\n error.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\br_\be_\bp_\bl_\ba_\bc_\be_\b__\bc_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_f\bfi\bin\bnd\bd_\b_r\bre\bep\bpl\bla\bac\bce\be_\b_c\bcs\bst\btr\br *\b**\b**\b**\b**\b*\n bool al_ustr_find_replace_cstr(ALLEGRO_USTR *us, int start_pos,\n const char *find, const char *replace)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\bi_\bn_\bd_\b__\br_\be_\bp_\bl_\ba_\bc_\be but takes C-style strings for find and replace.\n+Examples:\n+ * _\be_\bx_\b__\bl_\bo_\ba_\bd_\bi_\bn_\bg_\b__\bt_\bh_\br_\be_\ba_\bd_\b._\bc\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b**\b* C\bCo\bom\bmp\bpa\bar\bri\bin\bng\bg *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_e\beq\bqu\bua\bal\bl *\b**\b**\b**\b**\b*\n bool al_ustr_equal(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Return true iff the two strings are equal. This function is more efficient than\n _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bc_\bo_\bm_\bp_\ba_\br_\be so is preferable if ordering is not important.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bc_\bo_\bm_\bp_\ba_\br_\be\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_c\bco\bom\bmp\bpa\bar\bre\be *\b**\b**\b**\b**\b*\n int al_ustr_compare(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This function compares us1 and us2 by code point values. Returns zero if the\n strings are equal, a positive number if us1 comes after us2, else a negative\n number.\n This does n\bno\bot\bt take into account locale-specific sorting rules. For that you\n will need to use another library.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bn_\bc_\bo_\bm_\bp_\ba_\br_\be, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\be_\bq_\bu_\ba_\bl\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_n\bnc\bco\bom\bmp\bpa\bar\bre\be *\b**\b**\b**\b**\b*\n int al_ustr_ncompare(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2, int n)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bc_\bo_\bm_\bp_\ba_\br_\be but only compares up to the first n code points of both\n strings.\n Returns zero if the strings are equal, a positive number if us1 comes after\n us2, else a negative number.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bc_\bo_\bm_\bp_\ba_\br_\be, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\be_\bq_\bu_\ba_\bl\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_h\bha\bas\bs_\b_p\bpr\bre\bef\bfi\bix\bx *\b**\b**\b**\b**\b*\n bool al_ustr_has_prefix(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true iff us1 begins with us2.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bh_\ba_\bs_\b__\bp_\br_\be_\bf_\bi_\bx_\b__\bc_\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bh_\ba_\bs_\b__\bs_\bu_\bf_\bf_\bi_\bx\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_h\bha\bas\bs_\b_p\bpr\bre\bef\bfi\bix\bx_\b_c\bcs\bst\btr\br *\b**\b**\b**\b**\b*\n bool al_ustr_has_prefix_cstr(const ALLEGRO_USTR *us1, const char *s2)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true iff us1 begins with s2.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bh_\ba_\bs_\b__\bp_\br_\be_\bf_\bi_\bx, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bh_\ba_\bs_\b__\bs_\bu_\bf_\bf_\bi_\bx_\b__\bc_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_h\bha\bas\bs_\b_s\bsu\buf\bff\bfi\bix\bx *\b**\b**\b**\b**\b*\n bool al_ustr_has_suffix(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true iff us1 ends with us2.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bh_\ba_\bs_\b__\bs_\bu_\bf_\bf_\bi_\bx_\b__\bc_\bs_\bt_\br, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bh_\ba_\bs_\b__\bp_\br_\be_\bf_\bi_\bx\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_h\bha\bas\bs_\b_s\bsu\buf\bff\bfi\bix\bx_\b_c\bcs\bst\btr\br *\b**\b**\b**\b**\b*\n bool al_ustr_has_suffix_cstr(const ALLEGRO_USTR *us1, const char *s2)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true iff us1 ends with s2.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bh_\ba_\bs_\b__\bs_\bu_\bf_\bf_\bi_\bx, _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bh_\ba_\bs_\b__\bp_\br_\be_\bf_\bi_\bx_\b__\bc_\bs_\bt_\br\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b**\b* U\bUT\bTF\bF-\b-1\b16\b6 c\bco\bon\bnv\bve\ber\brs\bsi\bio\bon\bn *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_n\bne\bew\bw_\b_f\bfr\bro\bom\bm_\b_u\but\btf\bf1\b16\b6 *\b**\b**\b**\b**\b*\n ALLEGRO_USTR *al_ustr_new_from_utf16(uint16_t const *s)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Create a new string containing a copy of the 0-terminated string s which must\n be encoded as UTF-16. The string must eventually be freed with _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bf_\br_\be_\be.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bn_\be_\bw\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_s\bsi\biz\bze\be_\b_u\but\btf\bf1\b16\b6 *\b**\b**\b**\b**\b*\n size_t al_ustr_size_utf16(const ALLEGRO_USTR *us)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the number of bytes required to encode the string in UTF-16 (including\n the terminating 0). Usually called before _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\be_\bn_\bc_\bo_\bd_\be_\b__\bu_\bt_\bf_\b1_\b6 to determine the\n size of the buffer to allocate.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bs_\bi_\bz_\be\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\bus\bst\btr\br_\b_e\ben\bnc\bco\bod\bde\be_\b_u\but\btf\bf1\b16\b6 *\b**\b**\b**\b**\b*\n size_t al_ustr_encode_utf16(const ALLEGRO_USTR *us, uint16_t *s,\n size_t n)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Encode the string into the given buffer, in UTF-16. Returns the number of bytes\n written. There are never more than n bytes written. The minimum size to encode\n the complete string can be queried with _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bs_\bi_\bz_\be_\b__\bu_\bt_\bf_\b1_\b6. If the n parameter\n is smaller than that, the string will be truncated but still always 0\n terminated.\n See also: _\ba_\bl_\b__\bu_\bs_\bt_\br_\b__\bs_\bi_\bz_\be_\b__\bu_\bt_\bf_\b1_\b6, _\ba_\bl_\b__\bu_\bt_\bf_\b1_\b6_\b__\be_\bn_\bc_\bo_\bd_\be\n+Examples:\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b**\b* L\bLo\bow\bw-\b-l\ble\bev\bve\bel\bl U\bUT\bTF\bF-\b-8\b8 r\bro\bou\but\bti\bin\bne\bes\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\but\btf\bf8\b8_\b_w\bwi\bid\bdt\bth\bh *\b**\b**\b**\b**\b*\n size_t al_utf8_width(int32_t c)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the number of bytes that would be occupied by the specified code point\n when encoded in UTF-8. This is between 1 and 4 bytes for legal code point\n values. Otherwise returns 0.\n See also: _\ba_\bl_\b__\bu_\bt_\bf_\b8_\b__\be_\bn_\bc_\bo_\bd_\be, _\ba_\bl_\b__\bu_\bt_\bf_\b1_\b6_\b__\bw_\bi_\bd_\bt_\bh\n+Examples:\n+ * _\bn_\bi_\bh_\bg_\bu_\bi_\b._\bc_\bp_\bp\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\but\btf\bf8\b8_\b_e\ben\bnc\bco\bod\bde\be *\b**\b**\b**\b**\b*\n size_t al_utf8_encode(char s[], int32_t c)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Encode the specified code point to UTF-8 into the buffer s. The buffer must\n have enough space to hold the encoding, which takes between 1 and 4 bytes. This\n routine will refuse to encode code points above 0x10FFFF.\n Returns the number of bytes written, which is the same as that returned by\n _\ba_\bl_\b__\bu_\bt_\bf_\b8_\b__\bw_\bi_\bd_\bt_\bh.\n See also: _\ba_\bl_\b__\bu_\bt_\bf_\b1_\b6_\b__\be_\bn_\bc_\bo_\bd_\be\n+Examples:\n+ * _\be_\bx_\b__\bk_\be_\by_\bb_\bo_\ba_\br_\bd_\b__\be_\bv_\be_\bn_\bt_\bs_\b._\bc\n+ * _\be_\bx_\b__\bu_\bt_\bf_\b8_\b._\bc\n *\b**\b**\b**\b**\b**\b* L\bLo\bow\bw-\b-l\ble\bev\bve\bel\bl U\bUT\bTF\bF-\b-1\b16\b6 r\bro\bou\but\bti\bin\bne\bes\bs *\b**\b**\b**\b**\b**\b*\n *\b**\b**\b**\b**\b* a\bal\bl_\b_u\but\btf\bf1\b16\b6_\b_w\bwi\bid\bdt\bth\bh *\b**\b**\b**\b**\b*\n size_t al_utf16_width(int c)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the number of bytes that would be occupied by the specified code point\n when encoded in UTF-16. This is either 2 or 4 bytes for legal code point\n values. Otherwise returns 0.\n"}]}, {"source1": "./usr/share/doc/allegro5-doc/refman/video.html", "source2": "./usr/share/doc/allegro5-doc/refman/video.html", "unified_diff": "@@ -290,14 +290,19 @@\n

    al_init_video_addon

    \n 
    bool al_init_video_addon(void)
    \n

    Source\n Code

    \n

    Initializes the video addon.

    \n

    Since: 5.1.12

    \n+

    Examples:

    \n+
      \n+
    • ex_video.c
      • \n+
    \n al_is_video_addon_initialized\n 
    bool al_is_video_addon_initialized(void)
    \n

    Source\n Code

    \n

    Returns true if the video addon is initialized, otherwise returns\n@@ -323,14 +328,19 @@\n 

    ALLEGRO_VIDEO *al_open_video(char const *filename)
    \n

    Source\n Code

    \n

    Reads a video file. This does not start playing yet but reads the\n meta info so you can query e.g.\u00a0the size or audio rate.

    \n

    Since: 5.1.0

    \n+

    Examples:

    \n+
      \n+
    • ex_video.c
      • \n+
    \n

    al_identify_video

    \n 
    char const *al_identify_video(char const *filename)
    \n

    Source\n Code

    \n

    This works exactly as al_identify_video_f but you\n@@ -362,21 +372,31 @@\n 

    void al_close_video(ALLEGRO_VIDEO *video)
    \n

    Source\n Code

    \n

    Closes the video and frees all allocated resources. The video pointer\n is invalid after the function returns.

    \n

    Since: 5.1.0

    \n+

    Examples:

    \n+
      \n+
    • ex_video.c
      • \n+
    \n

    al_start_video

    \n 
    void al_start_video(ALLEGRO_VIDEO *video, ALLEGRO_MIXER *mixer)
    \n

    Source\n Code

    \n

    Starts playing the video from the beginning.

    \n

    Since: 5.1.0

    \n+

    Examples:

    \n+
      \n+
    • ex_video.c
      • \n+
    \n

    al_start_video_with_voice

    \n 
    void al_start_video_with_voice(ALLEGRO_VIDEO *video, ALLEGRO_VOICE *voice)
    \n

    Source\n Code

    \n

    Like al_start_video but audio\n is routed to the provided voice.

    \n@@ -386,65 +406,100 @@\n

    Source\n Code

    \n

    Get an event source for the video. The possible events are described\n under ALLEGRO_VIDEO_EVENT_TYPE.

    \n

    Since: 5.1.0

    \n+

    Examples:

    \n+
      \n+
    • ex_video.c
      • \n+
    \n

    al_set_video_playing

    \n 
    void al_set_video_playing(ALLEGRO_VIDEO *video, bool play)
    \n

    Source\n Code

    \n

    Paused or resumes playback.

    \n

    Since: 5.1.12

    \n+

    Examples:

    \n+
      \n+
    • ex_video.c
      • \n+
    \n

    al_is_video_playing

    \n 
    bool al_is_video_playing(ALLEGRO_VIDEO *video)
    \n

    Source\n Code

    \n

    Returns true if the video is currently playing.

    \n

    Since: 5.1.12

    \n+

    Examples:

    \n+
      \n+
    • ex_video.c
      • \n+
    \n

    al_get_video_audio_rate

    \n 
    double al_get_video_audio_rate(ALLEGRO_VIDEO *video)
    \n

    Source\n Code

    \n

    Returns the audio rate of the video, in Hz.

    \n

    Since: 5.1.0

    \n+

    Examples:

    \n+
      \n+
    • ex_video.c
      • \n+
    \n

    al_get_video_fps

    \n 
    double al_get_video_fps(ALLEGRO_VIDEO *video)
    \n

    Source\n Code

    \n

    Returns the speed of the video in frames per second. Often this will\n not be an integer value.

    \n

    Since: 5.1.0

    \n+

    Examples:

    \n+
      \n+
    • ex_video.c
      • \n+
    \n

    al_get_video_scaled_width

    \n 
    float al_get_video_scaled_width(ALLEGRO_VIDEO *video)
    \n

    Source\n Code

    \n

    Returns the width with which the video frame should be drawn. Videos\n often do not use square pixels, so this will may return a value larger\n than the width of the frame bitmap.

    \n

    Since: 5.1.12

    \n

    See also: al_get_video_frame

    \n+

    Examples:

    \n+
      \n+
    • ex_video.c
      • \n+
    \n

    al_get_video_scaled_height

    \n 
    float al_get_video_scaled_height(ALLEGRO_VIDEO *video)
    \n

    Source\n Code

    \n

    Returns the height with which the video frame should be drawn. Videos\n often do not use square pixels, so this will may return a value larger\n than the height of the frame bitmap.

    \n

    See also: al_get_video_frame

    \n

    Since: 5.1.12

    \n+

    Examples:

    \n+
      \n+
    • ex_video.c
      • \n+
    \n

    al_get_video_frame

    \n 
    ALLEGRO_BITMAP *al_get_video_frame(ALLEGRO_VIDEO *video)
    \n

    Source\n Code

    \n

    Returns the current video frame. The bitmap is owned by the video so\n do not attempt to free it. The bitmap will stay valid until the next\n@@ -459,29 +514,47 @@\n float dh = scale * al_get_video_scaled_height(video);\n al_draw_scaled_bitmap(frame, 0, 0, sw, sh, 0, 0, dw, dh, 0);\n

    Since: 5.1.0

    \n

    See also: al_get_video_scaled_width,\n al_get_video_scaled_height

    \n+

    Examples:

    \n+
      \n+
    • ex_video.c
      • \n+
    \n

    al_get_video_position

    \n 
    double al_get_video_position(ALLEGRO_VIDEO *video, ALLEGRO_VIDEO_POSITION_TYPE which)
    \n

    Source\n Code

    \n

    Returns the current position of the video stream in seconds since the\n beginning. The parameter is one of the ALLEGRO_VIDEO_POSITION_TYPE\n constants.

    \n

    Since: 5.1.0

    \n+

    Examples:

    \n+
      \n+
    • ex_video.c
      • \n+
    \n

    al_seek_video

    \n 
    bool al_seek_video(ALLEGRO_VIDEO *video, double pos_in_seconds)
    \n

    Source\n Code

    \n

    Seek to a different position in the video. Currently only seeking to\n the beginning of the video is supported.

    \n

    Since: 5.1.0

    \n-\n+

    Examples:

    \n+
      \n+
    • ex_video.c
      • \n+
    \n+

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

    \n \n \n \n", "details": [{"source1": "html2text {}", "source2": "html2text {}", "unified_diff": "@@ -109,14 +109,16 @@\n in sync.\n Since: 5.1.11\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bin\bni\bit\bt_\b_v\bvi\bid\bde\beo\bo_\b_a\bad\bdd\bdo\bon\bn *\b**\b**\b**\b**\b**\b*\n bool al_init_video_addon(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Initializes the video addon.\n Since: 5.1.12\n+Examples:\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_v\bvi\bid\bde\beo\bo_\b_a\bad\bdd\bdo\bon\bn_\b_i\bin\bni\bit\bti\bia\bal\bli\biz\bze\bed\bd *\b**\b**\b**\b**\b**\b*\n bool al_is_video_addon_initialized(void)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if the video addon is initialized, otherwise returns false.\n Since: 5.2.6\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bsh\bhu\but\btd\bdo\bow\bwn\bn_\b_v\bvi\bid\bde\beo\bo_\b_a\bad\bdd\bdo\bon\bn *\b**\b**\b**\b**\b**\b*\n void al_shutdown_video_addon(void)\n@@ -132,14 +134,16 @@\n Since: 5.1.12\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_o\bop\bpe\ben\bn_\b_v\bvi\bid\bde\beo\bo *\b**\b**\b**\b**\b**\b*\n ALLEGRO_VIDEO *al_open_video(char const *filename)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Reads a video file. This does not start playing yet but reads the meta info so\n you can query e.g.\u00a0the size or audio rate.\n Since: 5.1.0\n+Examples:\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bid\bde\ben\bnt\bti\bif\bfy\by_\b_v\bvi\bid\bde\beo\bo *\b**\b**\b**\b**\b**\b*\n char const *al_identify_video(char const *filename)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n This works exactly as _\ba_\bl_\b__\bi_\bd_\be_\bn_\bt_\bi_\bf_\by_\b__\bv_\bi_\bd_\be_\bo_\b__\bf but you specify the filename of the\n file for which to detect the type and not a file handle. The extension, if any,\n of the passed filename is not taken into account - only the file contents.\n Since: 5.2.8\n@@ -157,67 +161,85 @@\n See also: _\ba_\bl_\b__\bi_\bn_\bi_\bt_\b__\bv_\bi_\bd_\be_\bo_\b__\ba_\bd_\bd_\bo_\bn, _\ba_\bl_\b__\bi_\bd_\be_\bn_\bt_\bi_\bf_\by_\b__\bv_\bi_\bd_\be_\bo\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_c\bcl\blo\bos\bse\be_\b_v\bvi\bid\bde\beo\bo *\b**\b**\b**\b**\b**\b*\n void al_close_video(ALLEGRO_VIDEO *video)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Closes the video and frees all allocated resources. The video pointer is\n invalid after the function returns.\n Since: 5.1.0\n+Examples:\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bst\bta\bar\brt\bt_\b_v\bvi\bid\bde\beo\bo *\b**\b**\b**\b**\b**\b*\n void al_start_video(ALLEGRO_VIDEO *video, ALLEGRO_MIXER *mixer)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Starts playing the video from the beginning.\n Since: 5.1.0\n+Examples:\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bst\bta\bar\brt\bt_\b_v\bvi\bid\bde\beo\bo_\b_w\bwi\bit\bth\bh_\b_v\bvo\boi\bic\bce\be *\b**\b**\b**\b**\b**\b*\n void al_start_video_with_voice(ALLEGRO_VIDEO *video, ALLEGRO_VOICE *voice)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Like _\ba_\bl_\b__\bs_\bt_\ba_\br_\bt_\b__\bv_\bi_\bd_\be_\bo but audio is routed to the provided voice.\n Since: 5.1.0\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_v\bvi\bid\bde\beo\bo_\b_e\bev\bve\ben\bnt\bt_\b_s\bso\bou\bur\brc\bce\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_EVENT_SOURCE *al_get_video_event_source(ALLEGRO_VIDEO *video)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Get an event source for the video. The possible events are described under\n _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bI_\bD_\bE_\bO_\b__\bE_\bV_\bE_\bN_\bT_\b__\bT_\bY_\bP_\bE.\n Since: 5.1.0\n+Examples:\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bet\bt_\b_v\bvi\bid\bde\beo\bo_\b_p\bpl\bla\bay\byi\bin\bng\bg *\b**\b**\b**\b**\b**\b*\n void al_set_video_playing(ALLEGRO_VIDEO *video, bool play)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Paused or resumes playback.\n Since: 5.1.12\n+Examples:\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_i\bis\bs_\b_v\bvi\bid\bde\beo\bo_\b_p\bpl\bla\bay\byi\bin\bng\bg *\b**\b**\b**\b**\b**\b*\n bool al_is_video_playing(ALLEGRO_VIDEO *video)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns true if the video is currently playing.\n Since: 5.1.12\n+Examples:\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_v\bvi\bid\bde\beo\bo_\b_a\bau\bud\bdi\bio\bo_\b_r\bra\bat\bte\be *\b**\b**\b**\b**\b**\b*\n double al_get_video_audio_rate(ALLEGRO_VIDEO *video)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the audio rate of the video, in Hz.\n Since: 5.1.0\n+Examples:\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_v\bvi\bid\bde\beo\bo_\b_f\bfp\bps\bs *\b**\b**\b**\b**\b**\b*\n double al_get_video_fps(ALLEGRO_VIDEO *video)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the speed of the video in frames per second. Often this will not be an\n integer value.\n Since: 5.1.0\n+Examples:\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_v\bvi\bid\bde\beo\bo_\b_s\bsc\bca\bal\ble\bed\bd_\b_w\bwi\bid\bdt\bth\bh *\b**\b**\b**\b**\b**\b*\n float al_get_video_scaled_width(ALLEGRO_VIDEO *video)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the width with which the video frame should be drawn. Videos often do\n not use square pixels, so this will may return a value larger than the width of\n the frame bitmap.\n Since: 5.1.12\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bv_\bi_\bd_\be_\bo_\b__\bf_\br_\ba_\bm_\be\n+Examples:\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_v\bvi\bid\bde\beo\bo_\b_s\bsc\bca\bal\ble\bed\bd_\b_h\bhe\bei\big\bgh\bht\bt *\b**\b**\b**\b**\b**\b*\n float al_get_video_scaled_height(ALLEGRO_VIDEO *video)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the height with which the video frame should be drawn. Videos often do\n not use square pixels, so this will may return a value larger than the height\n of the frame bitmap.\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bv_\bi_\bd_\be_\bo_\b__\bf_\br_\ba_\bm_\be\n Since: 5.1.12\n+Examples:\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_v\bvi\bid\bde\beo\bo_\b_f\bfr\bra\bam\bme\be *\b**\b**\b**\b**\b**\b*\n ALLEGRO_BITMAP *al_get_video_frame(ALLEGRO_VIDEO *video)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the current video frame. The bitmap is owned by the video so do not\n attempt to free it. The bitmap will stay valid until the next call to\n al_get_video_frame.\n Videos often do not use square pixels so the recommended way to draw a video\n@@ -227,20 +249,27 @@\n float sw = al_get_bitmap_width(frame);\n float sh = al_get_bitmap_height(frame);\n float dw = scale * al_get_video_scaled_width(video);\n float dh = scale * al_get_video_scaled_height(video);\n al_draw_scaled_bitmap(frame, 0, 0, sw, sh, 0, 0, dw, dh, 0);\n Since: 5.1.0\n See also: _\ba_\bl_\b__\bg_\be_\bt_\b__\bv_\bi_\bd_\be_\bo_\b__\bs_\bc_\ba_\bl_\be_\bd_\b__\bw_\bi_\bd_\bt_\bh, _\ba_\bl_\b__\bg_\be_\bt_\b__\bv_\bi_\bd_\be_\bo_\b__\bs_\bc_\ba_\bl_\be_\bd_\b__\bh_\be_\bi_\bg_\bh_\bt\n+Examples:\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_g\bge\bet\bt_\b_v\bvi\bid\bde\beo\bo_\b_p\bpo\bos\bsi\bit\bti\bio\bon\bn *\b**\b**\b**\b**\b**\b*\n double al_get_video_position(ALLEGRO_VIDEO *video, ALLEGRO_VIDEO_POSITION_TYPE\n which)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Returns the current position of the video stream in seconds since the\n beginning. The parameter is one of the _\bA_\bL_\bL_\bE_\bG_\bR_\bO_\b__\bV_\bI_\bD_\bE_\bO_\b__\bP_\bO_\bS_\bI_\bT_\bI_\bO_\bN_\b__\bT_\bY_\bP_\bE constants.\n Since: 5.1.0\n+Examples:\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n *\b**\b**\b**\b**\b**\b* a\bal\bl_\b_s\bse\bee\bek\bk_\b_v\bvi\bid\bde\beo\bo *\b**\b**\b**\b**\b**\b*\n bool al_seek_video(ALLEGRO_VIDEO *video, double pos_in_seconds)\n _\bS_\bo_\bu_\br_\bc_\be_\b _\bC_\bo_\bd_\be\n Seek to a different position in the video. Currently only seeking to the\n beginning of the video is supported.\n Since: 5.1.0\n+Examples:\n+ * _\be_\bx_\b__\bv_\bi_\bd_\be_\bo_\b._\bc\n+Allegro version 5.2.10 - Last updated: 2025-01-09 13:52:42 UTC\n"}]}]}]}]}, {"source1": "liballegro5-dev_5.2.10.1+dfsg-1_amd64.deb", "source2": "liballegro5-dev_5.2.10.1+dfsg-1_amd64.deb", "unified_diff": null, "details": [{"source1": "control.tar.xz", "source2": "control.tar.xz", "unified_diff": null, "details": [{"source1": "control.tar", "source2": "control.tar", "unified_diff": null, "details": [{"source1": "./md5sums", "source2": "./md5sums", "unified_diff": null, "details": [{"source1": "./md5sums", "source2": "./md5sums", "comments": ["Files differ"], "unified_diff": null}]}]}]}, {"source1": "data.tar.xz", "source2": "data.tar.xz", "unified_diff": null, "details": [{"source1": "data.tar", "source2": "data.tar", "unified_diff": null, "details": [{"source1": "file list", "source2": "file list", "unified_diff": "@@ -93,15 +93,15 @@\n drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/include/x86_64-linux-gnu/allegro5/\n drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/include/x86_64-linux-gnu/allegro5/platform/\n -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\n drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/lib/\n drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/\n drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/cmake/\n drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/cmake/allegro/\n--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\n+-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\n -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\n -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\n -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\n drwxr-xr-x 0 root (0) root (0) 0 2025-01-09 13:52:42.000000 ./usr/lib/x86_64-linux-gnu/pkgconfig/\n -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\n -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\n -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\n"}, {"source1": "./usr/lib/x86_64-linux-gnu/cmake/allegro/AllegroConfig.cmake", "source2": "./usr/lib/x86_64-linux-gnu/cmake/allegro/AllegroConfig.cmake", "unified_diff": "@@ -31,11 +31,11 @@\n set(ALLEGRO_PKG_VERSION_PATCH 10)\n set(ALLEGRO_PKG_VERSION 5.2.10)\n \n # Architecture, compiler and other low level flags\n set(ALLEGRO_PKG_LIBRARY_ARCHITECTURE \"x86_64-linux-gnu\")\n set(ALLEGRO_PKG_COMPILER \"GNU\")\n set(ALLEGRO_PKG_COMPILER_VERSION \"14.2.0\")\n-set(ALLEGRO_PKG_HOST_SYSTEM \"Linux-6.12.12+bpo-amd64\")\n+set(ALLEGRO_PKG_HOST_SYSTEM \"Linux-6.1.0-31-amd64\")\n \n # Targets\n include(\"${CMAKE_CURRENT_LIST_DIR}/AllegroTargets.cmake\")\n"}]}]}]}]}