| [PATCH] Docs corrections and clarifications |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
- Subject: [PATCH] Docs corrections and clarifications
- From: Polybios <polybios@xxxxxxxxxx>
- Date: Thu, 12 Mar 2015 22:04:23 +0100
---
docs/src/pandoc.css | 1 +
docs/src/refman/acodec.txt | 2 +-
docs/src/refman/audio.txt | 10 +--
docs/src/refman/config.txt | 14 ++--
docs/src/refman/display.txt | 56 ++++++++++---
docs/src/refman/events.txt | 155 ++++++++++++++++++++----------------
docs/src/refman/file.txt | 2 +-
docs/src/refman/fixed.txt | 25 +++---
docs/src/refman/font.txt | 103 +++++++++++-------------
docs/src/refman/fshook.txt | 2 +-
docs/src/refman/fullscreen_mode.txt | 2 +
docs/src/refman/graphics.txt | 12 +--
docs/src/refman/haptic.txt | 82 +++++++++----------
docs/src/refman/joystick.txt | 11 +--
docs/src/refman/keyboard.txt | 3 +-
docs/src/refman/monitor.txt | 2 +-
docs/src/refman/mouse.txt | 10 ++-
docs/src/refman/native_dialog.txt | 63 ++++++++-------
docs/src/refman/opengl.txt | 2 +-
docs/src/refman/path.txt | 2 +-
docs/src/refman/primitives.txt | 90 +++++++++++----------
docs/src/refman/shader.txt | 6 +-
docs/src/refman/state.txt | 4 +-
docs/src/refman/system.txt | 4 +-
docs/src/refman/threads.txt | 2 +-
docs/src/refman/time.txt | 8 +-
docs/src/refman/timer.txt | 3 +-
docs/src/refman/touch.txt | 6 +-
docs/src/refman/transformations.txt | 15 +++-
docs/src/refman/utf8.txt | 40 +++++-----
docs/src/refman/video.txt | 4 +-
31 files changed, 398 insertions(+), 343 deletions(-)
diff --git a/docs/src/pandoc.css b/docs/src/pandoc.css
index f4217e0..aac526d 100644
--- a/docs/src/pandoc.css
+++ b/docs/src/pandoc.css
@@ -145,6 +145,7 @@ div.searchbox {
/* font-size isn't inherited (at least not in Firefox and Chrome) */
input#q {
font-size: small;
+ width: 95%; /* fix searchfield being wider than sidebar */
}
/* Body of page */
diff --git a/docs/src/refman/acodec.txt b/docs/src/refman/acodec.txt
index 2375ec2..90833c9 100644
--- a/docs/src/refman/acodec.txt
+++ b/docs/src/refman/acodec.txt
@@ -19,7 +19,7 @@ extensions is: .wav, .flac, .ogg, .it, .mod, .s3m, .xm, .voc.
- Saving is only supported for wav files.
-- Wav file loader currently only supports 8/16 bit little endian PCM files.
+- The wav file loader currently only supports 8/16 bit little endian PCM files.
16 bits are used when saving wav files. Use flac files if more precision is
required.
diff --git a/docs/src/refman/audio.txt b/docs/src/refman/audio.txt
index 5cd83b8..118db08 100644
--- a/docs/src/refman/audio.txt
+++ b/docs/src/refman/audio.txt
@@ -235,7 +235,7 @@ Since: 5.1.8
Creates a voice structure and allocates a voice from the digital sound driver.
The passed frequency, sample format and channel configuration are used as a
hint to what kind of data will be sent to the voice. However, the underlying
-sound driver is free to use non-matching values. For example it may be the
+sound driver is free to use non-matching values. For example, it may be the
native format of the sound hardware. If a mixer is attached to the voice, the
mixer will convert from the mixer's format to the voice format and care does
not have to be taken for this.
@@ -947,7 +947,7 @@ See also: [al_set_audio_stream_speed].
Set the relative playback speed. 1.0 is normal speed.
-Return true on success, false on failure. Will fail if the sample instance is
+Return true on success, false on failure. Will fail if the audio stream is
attached directly to a voice.
See also: [al_get_audio_stream_speed].
@@ -962,7 +962,7 @@ See also: [al_set_audio_stream_gain].
Set the playback gain.
-Returns true on success, false on failure. Will fail if the sample instance
+Returns true on success, false on failure. Will fail if the audio stream
is attached directly to a voice.
See also: [al_get_audio_stream_gain].
@@ -982,7 +982,7 @@ A special value [ALLEGRO_AUDIO_PAN_NONE] disables panning and plays the
stream at its original level. This will be louder than a pan value of 0.0.
Returns true on success, false on failure.
-Will fail if the sample instance is attached directly to a voice.
+Will fail if the audio stream is attached directly to a voice.
See also: [al_get_audio_stream_pan], [ALLEGRO_AUDIO_PAN_NONE]
@@ -1468,7 +1468,7 @@ Since: 5.1.1
### API: al_destroy_audio_recorder
Destroys the audio recorder and frees all resources associated with it. It
-is safe to destroy a recorder that is playing.
+is safe to destroy a recorder that is recording.
You may receive events after the recorder has been destroyed. They must be
ignored, as the fragment buffer will no longer be valid.
diff --git a/docs/src/refman/config.txt b/docs/src/refman/config.txt
index 68c31bd..3f91c76 100644
--- a/docs/src/refman/config.txt
+++ b/docs/src/refman/config.txt
@@ -31,16 +31,14 @@ declarations belong to the global section. Sections do not nest.
Here is an example configuration file:
-~~~~ini
-# Monster description
-monster name = Allegro Developer
+ # Monster description
+ monster name = Allegro Developer
-[weapon 0]
-damage = 443
+ [weapon 0]
+ damage = 443
-[weapon 1]
-damage = 503
-~~~~
+ [weapon 1]
+ damage = 503
It can then be accessed like this (make sure to check for errors in
an actual program):
diff --git a/docs/src/refman/display.txt b/docs/src/refman/display.txt
index a3f8c84..fea373e 100644
--- a/docs/src/refman/display.txt
+++ b/docs/src/refman/display.txt
@@ -6,6 +6,38 @@ These functions are declared in the main Allegro header file:
#include <allegro5/allegro.h>
~~~~
+All drawing operations end up being visible on a display which is the same as
+a window in windowed environments. Thus, before any drawing can take place,
+a display needs to be created.
+
+Before creating a display with [al_create_display], flags and options can be set
+with [al_set_new_display_flags] and [al_set_new_display_option]. For example, you
+can enable the use of shaders or choose between the OpenGL and Direct3D backends
+(on platforms that support both) with [al_set_new_display_flags]. Display options
+are rather optional settings that do not affect Allegro itself, e.g. they allow
+you to specify whether you want a depth buffer or enable multisampling.
+
+The actual properties of a display that has been successfully created can be queried
+via [al_get_display_option], [al_get_display_flags], [al_get_display_width] etc...
+Note that you can query some additional read-only properties such as the maximum
+allowed bitmap (i. e. texture) size via [al_get_display_option].
+
+Each display has a backbuffer associated to it which is the default target for any
+drawing operations. In order to make visible what has been drawn previously, you
+have to to call [al_flip_display]. Note that it is generally advisable to redraw
+the whole screen (or [clear][al_clear_to_color] it in advance) to avoid artefacts
+of uninitialised memory becoming visible with some drivers.
+
+You don't have to use Allegro's drawing routines, however: since creating a display
+implies the creation of an OpenGL context or Direct3D device respectively, you can
+use these APIs directly if you prefer to do so. Allegro provides integration for
+both (see the OpenGL / Direct3D sections), so you can retrieve the underlying
+textures of [ALLEGRO_BITMAP]s, for example.
+
+In order to write a well-behaved application, it is necessary to remember that
+displays will also inform you about important [events][ALLEGRO_EVENT_DISPLAY_EXPOSE]
+via their [event sources][al_get_display_event_source].
+
## Display creation
### API: ALLEGRO_DISPLAY
@@ -23,8 +55,8 @@ backbuffer selected for drawing.
Returns NULL on error.
-Each display has a distinct OpenGL rendering context associated with it. See
-[al_set_target_bitmap] for the discussion about rendering contexts.
+Each display that uses OpenGL as a backend has a distinct OpenGL rendering context
+associated with it. See [al_set_target_bitmap] for the discussion about rendering contexts.
See also: [al_set_new_display_flags], [al_set_new_display_option],
[al_set_new_display_refresh_rate], [al_set_new_display_adapter],
@@ -182,7 +214,7 @@ ALLEGRO_RED_SHIFT, ALLEGRO_GREEN_SHIFT, ALLEGRO_BLUE_SHIFT, ALLEGRO_ALPHA_SHIFT
ALLEGRO_ACC_RED_SIZE, ALLEGRO_ACC_GREEN_SIZE, ALLEGRO_ACC_BLUE_SIZE, ALLEGRO_ACC_ALPHA_SIZE
: This can be used to define the required accumulation buffer size.
-
+
ALLEGRO_STEREO
: Whether the display is a stereo display.
@@ -290,7 +322,7 @@ ALLEGRO_SUPPORTED_ORIENTATIONS
LANDSCAPE means only the two landscape orientations and ALL allows
all four orientations. When the orientation changes between a
portrait and a landscape orientation the display needs to be
- resizes. This is done by sending an [ALLEGRO_EVENT_DISPLAY_RESIZE]
+ resized. This is done by sending an [ALLEGRO_EVENT_DISPLAY_RESIZE]
message which should be handled by calling [al_acknowledge_resize].
Since: 5.1.0
@@ -314,7 +346,7 @@ See also: [al_set_new_window_position]
Sets where the top left pixel of the client area of newly
created windows (non-fullscreen) will be on screen,
for displays created by the calling thread.
-Negative values allowed on some multihead systems.
+Negative values are allowed on some multihead systems.
To reset to the default behaviour, pass (INT_MAX, INT_MAX).
@@ -344,7 +376,9 @@ See also: [al_get_new_display_refresh_rate]
### API: al_get_display_event_source
-Retrieve the associated event source.
+Retrieve the associated event source. See the
+[documentation on events][ALLEGRO_EVENT_DISPLAY_EXPOSE]
+for a list of the events displays will generate.
### API: al_get_backbuffer
@@ -354,7 +388,7 @@ display.
Care should be taken when using the backbuffer bitmap (and its
sub-bitmaps) as the source bitmap (e.g as the bitmap argument to
[al_draw_bitmap]). Only untransformed operations are hardware
-accelerated. This consists of [al_draw_bitmap] and
+accelerated. These consist of [al_draw_bitmap] and
[al_draw_bitmap_region] when the current transformation is the identity.
If the tranformation is not the identity, or some other drawing
operation is used, the call will be routed through the memory bitmap
@@ -441,10 +475,10 @@ See also: [al_acknowledge_resize]
### API: al_acknowledge_resize
-When the user receives a resize event from a resizable display,
-if they wish the display to be resized they must call this
-function to let the graphics driver know that it can now resize
-the display. Returns true on success.
+When the user receives a [resize event][ALLEGRO_EVENT_DISPLAY_RESIZE]
+from a resizable display, if they wish the display to be resized they
+must call this function to let the graphics driver know that it can now
+resize the display. Returns true on success.
Adjusts the clipping rectangle to the full size of the backbuffer.
diff --git a/docs/src/refman/events.txt b/docs/src/refman/events.txt
index fc3fc3f..e65f9f8 100644
--- a/docs/src/refman/events.txt
+++ b/docs/src/refman/events.txt
@@ -6,6 +6,25 @@ These functions are declared in the main Allegro header file:
#include <allegro5/allegro.h>
~~~~
+Events are generated by event sources. Most notably, each of the input
+subsystems provides an event source, but also timers, displays, and audio
+streams will generate events.
+
+Event sources are registered to event queues which aggregate events from
+multiple sources. A single event source can also be registered to multiple
+event queues.
+
+Event queues can then be queried for events. In particular, it is possible
+to wait until events become available in order to save CPU time. You can combine
+this with [timers][ALLEGRO_TIMER] to make your main-loop run at a specific speed
+without wasting CPU time or missing events.
+
+In addition to the predefined event types, Allegro also allows for user-defined
+events that can be generated by user-defined event sources.
+
+The appropriate reaction to an event is determined by examining the fields of
+the [ALLEGRO_EVENT] union according to the event type.
+
## API: ALLEGRO_EVENT
An ALLEGRO_EVENT is a union of all builtin event structures, i.e. it is an
@@ -173,8 +192,8 @@ mouse.display (ALLEGRO_DISPLAY *)
: The display which had mouse focus.
> *Note:* Calling [al_set_mouse_xy] also will result in a change of axis
-values, but such a change is reported with ALLEGRO_EVENT_MOUSE_WARPED
-events instead.
+values, but such a change is reported with [ALLEGRO_EVENT_MOUSE_WARPED]
+events instead which are identical except for their type.
> *Note:* currently mouse.display may be NULL if an event is generated in
response to [al_set_mouse_axis].
@@ -255,7 +274,7 @@ mouse.display (ALLEGRO_DISPLAY *)
### API: ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY
-The mouse cursor leave the boundaries of a window opened by the program.
+The mouse cursor left the boundaries of a window opened by the program.
mouse.x (int)
: x-coordinate
@@ -272,9 +291,58 @@ mouse.w (int)
mouse.display (ALLEGRO_DISPLAY *)
: The display which had mouse focus.
+### API: ALLEGRO_EVENT_TOUCH_BEGIN
+
+The touch input device registered a new touch.
+
+touch.display (ALLEGRO_DISPLAY)
+: The display which was touched.
+touch.id (int)
+: An identifier for this touch. If supported by the device it will
+ stay the same for events from the same finger until the touch
+ ends.
+touch.x (float)
+: The x coordinate of the touch in pixels.
+touch.y (float)
+: The y coordinate of the touch in pixels.
+touch.dx (float)
+: Movement speed in pixels in x direction.
+touch.dy (float)
+: Movement speed in pixels in y direction.
+touch.primary (bool)
+: Whether this is the only/first touch or an additional touch.
+
+Since: 5.1.0
+
+### API: ALLEGRO_EVENT_TOUCH_END
+
+A touch ended.
+
+Has the same fields as [ALLEGRO_EVENT_TOUCH_BEGIN].
+
+Since: 5.1.0
+
+### API: ALLEGRO_EVENT_TOUCH_MOVE
+
+The position of a touch changed.
+
+Has the same fields as [ALLEGRO_EVENT_TOUCH_BEGIN].
+
+Since: 5.1.0
+
+### API: ALLEGRO_EVENT_TOUCH_CANCEL
+
+A touch was cancelled. This is device specific but could for example
+mean that a finger moved off the border of the device or moved so
+fast that it could not be tracked any longer.
+
+Has the same fields as [ALLEGRO_EVENT_TOUCH_BEGIN].
+
+Since: 5.1.0
+
### API: ALLEGRO_EVENT_TIMER
-A timer counter incremented.
+A [timer][ALLEGRO_TIMER] counter incremented.
timer.source (ALLEGRO_TIMER *)
: The timer which generated the event.
@@ -293,7 +361,7 @@ display.x (int)
:
display.y (int)
:
-: The top-left corner of the display which was exposed.
+: The top-left corner of the rectangle which was exposed.
display.width (int)
:
@@ -337,9 +405,9 @@ display.source (ALLEGRO_DISPLAY *)
When using Direct3D, displays can enter
a "lost" state. In that state, drawing calls are ignored, and upon
entering the state, bitmap's pixel data can become undefined. Allegro
-does its best to preserve the correct contents of bitmaps
-(see ALLEGRO_NO_PRESERVE_TEXTURE) and restore them when the device
-is "found" (see ALLEGRO_EVENT_DISPLAY_FOUND). However, this is not 100%
+does its best to preserve the correct contents of bitmaps (see the
+ALLEGRO_NO_PRESERVE_TEXTURE flag) and restore them when the device is
+"found" (see [ALLEGRO_EVENT_DISPLAY_FOUND]). However, this is not 100%
fool proof.
To ensure that all bitmap contents are restored accurately,
@@ -365,7 +433,7 @@ display.source (ALLEGRO_DISPLAY *)
### API: ALLEGRO_EVENT_DISPLAY_FOUND
Generated when a lost device is restored to operating state.
-See ALLEGRO_EVENT_DISPLAY_LOST.
+See [ALLEGRO_EVENT_DISPLAY_LOST].
display.source (ALLEGRO_DISPLAY *)
: The display which was found.
@@ -414,7 +482,7 @@ situations where the application is not active but still should continue
drawing, for example when a popup is displayed in front of it.
> *Note:* This event means that the next time you call a drawing function, your
-program will crash. So you must stop drawing and you must immediately reply
+program will crash. So you *must* stop drawing and you *must* immediately reply
with [al_acknowledge_drawing_halt]. Allegro sends this event because it cannot
handle this automatically. Your program might be doing the drawing in a
different thread from the event handling, in which case the drawing thread
@@ -462,59 +530,6 @@ physical display. However, on iOS, a secondary physical display is suported.
display.source (ALLEGRO_DISPLAY *)
: The display which was disconnected.
-### API: ALLEGRO_EVENT_TOUCH_BEGIN
-
-The touch input device registered a new touch.
-
-touch.display (ALLEGRO_DISPLAY)
-: The display which was touched.
-touch.id (int)
-: An identifier for this touch. If supported by the device it will
- stay the same for events from the same finger until the touch
- ends.
-touch.x (float)
-: The x coordinate of the touch in pixels.
-touch.y (float)
-: The y coordinate of the touch in pixels.
-touch.dx (float)
-: Movement speed in pixels in x direction.
-touch.dy (float)
-: Movement speed in pixels in y direction.
-touch.primary (bool)
-: Whether this is the only/first touch or an additional touch.
-
-Since: 5.1.0
-
-### API: ALLEGRO_EVENT_TOUCH_END
-
-A touch ended.
-
-Has the same fields as [ALLEGRO_EVENT_TOUCH_BEGIN].
-
-Since: 5.1.0
-
-### API: ALLEGRO_EVENT_TOUCH_MOVE
-
-The position of a touch changed.
-
-Has the same fields as [ALLEGRO_EVENT_TOUCH_BEGIN].
-
-Since: 5.1.0
-
-### API: ALLEGRO_EVENT_TOUCH_CANCEL
-
-A touch was cancelled. This is device specific but could for example
-mean that a finger moved off the border of the device or moved so
-fast that it could not be tracked any longer.
-
-Has the same fields as [ALLEGRO_EVENT_TOUCH_BEGIN].
-
-Since: 5.1.0
-
-See also: [ALLEGRO_EVENT_SOURCE], [ALLEGRO_EVENT_TYPE], [ALLEGRO_USER_EVENT],
-[ALLEGRO_GET_EVENT_TYPE]
-
-
## API: ALLEGRO_USER_EVENT
An event structure that can be emitted by user event sources.
@@ -555,7 +570,7 @@ Event type identifiers for user events are assigned by the user.
Please see the documentation for [ALLEGRO_GET_EVENT_TYPE] for the rules you
should follow when assigning identifiers.
-See also: [al_emit_user_event], [ALLEGRO_GET_EVENT_TYPE]
+See also: [al_emit_user_event], [ALLEGRO_GET_EVENT_TYPE], [al_init_user_event_source]
## API: ALLEGRO_EVENT_QUEUE
@@ -624,8 +639,8 @@ type, i.e. one of those described in [ALLEGRO_EVENT_TYPE].
## API: al_create_event_queue
-Create a new, empty event queue, returning a pointer to object if
-successful. Returns NULL on error.
+Create a new, empty event queue, returning a pointer to the newly created
+object if successful. Returns NULL on error.
See also: [al_register_event_source], [al_destroy_event_queue],
[ALLEGRO_EVENT_QUEUE]
@@ -660,8 +675,8 @@ See also: [al_register_event_source]
## API: al_pause_event_queue
-Pause or resume accepting new events into the event queue.
-Events already in the queue are unaffected.
+Pause or resume accepting new events into the event queue (to resume, pass false
+for `pause`). Events already in the queue are unaffected.
While a queue is paused, any events which would be entered into the
queue are simply ignored.
@@ -738,7 +753,7 @@ into `ret_event` and removed from the queue. If `ret_event` is NULL
the first event is left at the head of the queue.
`secs` determines approximately how many seconds to wait. If the call times
-out, false is returned. Otherwise true is returned.
+out, false is returned. Otherwise, if an event ocurred, true is returned.
See also: [ALLEGRO_EVENT], [al_wait_for_event], [al_wait_for_event_until]
@@ -750,7 +765,7 @@ into `ret_event` and removed from the queue. If `ret_event` is NULL
the first event is left at the head of the queue.
`timeout` determines how long to wait. If the call times out, false is
-returned. Otherwise true is returned.
+returned. Otherwise, if an event ocurred, true is returned.
See also: [ALLEGRO_EVENT], [ALLEGRO_TIMEOUT], [al_init_timeout],
[al_wait_for_event], [al_wait_for_event_timed]
diff --git a/docs/src/refman/file.txt b/docs/src/refman/file.txt
index ce8f83a..24bc2e7 100644
--- a/docs/src/refman/file.txt
+++ b/docs/src/refman/file.txt
@@ -459,7 +459,7 @@ Returns the opened [ALLEGRO_FILE] on success, NULL on failure.
By default, the Allegro file I/O routines use the C library I/O routines,
hence work with files on the local filesystem, but can be overridden so that
-you can read and write to other streams. For example, you can work with block
+you can read and write to other streams. For example, you can work with blocks
of memory or sub-files inside .zip files.
There are two ways to get an [ALLEGRO_FILE] that doesn't use stdio.
diff --git a/docs/src/refman/fixed.txt b/docs/src/refman/fixed.txt
index cdb4fa7..aa42a81 100644
--- a/docs/src/refman/fixed.txt
+++ b/docs/src/refman/fixed.txt
@@ -26,12 +26,12 @@ floating point coprocessor to use them. This was great in the time period of
i386 and i486 machines, but stopped being so useful with the coming of the
Pentium class of processors. From Pentium onwards, CPUs have increased their
strength in floating point operations, equaling or even surpassing integer
-math performance.
+math performance. However, many embedded processors have no FPUs so fixed
+point maths can still be useful there.
Depending on the type of operations your program may need, using floating
point types may be faster than fixed types if you are targeting a specific
-machine class. Many embedded processors have no FPUs so fixed point maths can
-be useful there.
+machine class.
## API: al_itofix
@@ -343,8 +343,7 @@ assert(result == 1);
~~~~
Return value:
-Returns the sine of a fixed point binary format angle. The return value will be
-in radians.
+Returns the sine of a fixed point binary format angle as a fixed point value.
### API: al_fixcos
@@ -366,8 +365,7 @@ assert(result > 0.7 && result < 0.71);
~~~~
Return value:
-Returns the cosine of a fixed point binary format angle. The return value will
-be in radians.
+Returns the cosine of a fixed point binary format angle as a fixed point value.
### API: al_fixtan
@@ -389,8 +387,7 @@ printf("Precision error: %f\n", dif);
~~~~
Return value:
-Returns the tangent of a fixed point binary format angle. The return value will
-be in radians.
+Returns the tangent of a fixed point binary format angle as a fixed point value.
### API: al_fixasin
@@ -424,9 +421,9 @@ All return values of this function will be in the range -64 to 64.
### API: al_fixacos
This function finds the inverse cosine of a value using a lookup table. The
-input value must be a fixed point radian. The inverse cosine is defined only
-in the domain from -1 to 1. Outside of this input range, the function will
-set Allegro's errno to EDOM and return zero.
+input must be a fixed point value. The inverse cosine is defined only in the
+domain from -1 to 1. Outside of this input range, the function will set
+Allegro's errno to EDOM and return zero.
Example:
@@ -445,8 +442,8 @@ return values of this function will be in the range 0 to 128.
### API: al_fixatan
This function finds the inverse tangent of a value using a lookup table. The
-input value must be a fixed point radian. The inverse tangent is the value
-whose tangent is `x`.
+input must be a fixed point value. The inverse tangent is the value whose
+tangent is `x`.
Example:
diff --git a/docs/src/refman/font.txt b/docs/src/refman/font.txt
index 4eb2914..511c7e7 100644
--- a/docs/src/refman/font.txt
+++ b/docs/src/refman/font.txt
@@ -24,10 +24,13 @@ Initialise the font addon.
Note that if you intend to load bitmap fonts, you will need to initialise
allegro_image separately (unless you are using another library to load images).
+Similarly, if you wish to load truetype-fonts, do not forget to also call
+[al_init_ttf_addon].
+
Returns true on success, false on failure.
On the 5.0 branch, this function has no return value. You may wish to avoid
checking the return value if your code needs to be compatible with Allegro
-5.0. Currently, the function only ever true.
+5.0. Currently, the function will never return false.
See also: [al_init_image_addon], [al_init_ttf_addon], [al_shutdown_font_addon]
@@ -44,8 +47,8 @@ Loads a font from disk. This will use [al_load_bitmap_font_flags] if you pass
the name of a known bitmap format, or else [al_load_ttf_font].
The flags parameter is passed through to either of those functions.
-Bitmap and TTF fonts are also affected by the current bitmap flags at the time
-the font is loaded.
+Bitmap and TTF fonts are also affected by the current
+[bitmap flags][al_set_new_bitmap_flags] at the time the font is loaded.
See also: [al_destroy_font], [al_init_font_addon], [al_register_font_loader],
[al_load_bitmap_font_flags], [al_load_ttf_font]
@@ -62,7 +65,7 @@ See also: [al_load_font]
Informs Allegro of a new font file type, telling it how to load files of
this format.
-The extension should include the leading dot ('.') character.
+The `extension` should include the leading dot ('.') character.
It will be matched case-insensitively.
The `load_font` argument may be NULL to unregister an entry.
@@ -135,7 +138,7 @@ The `flags` parameter can be 0 or one of the following flags:
It can also be combined with this flag:
- ALLEGRO_ALIGN_INTEGER - Always draw text aligned to an integer pixel
- position. This is formerly the default behaviour. Since: 5.0.8, 5.1.4
+ position. This was formerly the default behaviour. Since: 5.0.8, 5.1.4
This function does not support newline characters (`\n`),
but you can use [al_draw_multiline_text] for multi line text output.
@@ -154,8 +157,8 @@ See also: [al_draw_text], [al_draw_justified_ustr], [al_draw_multiline_ustr]
Like [al_draw_text], but justifies the string to the region x1-x2.
-The *diff* parameter is the maximum amount of horizontal space to
-allow between words. If justisfying the text would exceed *diff* pixels,
+The `diff` parameter is the maximum amount of horizontal space to
+allow between words. If justisfying the text would exceed `diff` pixels,
or the string contains less than two words, then the string will be drawn
left aligned.
@@ -194,7 +197,7 @@ Sometimes, the [al_get_text_width] and [al_get_font_line_height]
functions are not enough for exact text placement, so this function
returns some additional information.
-Returned variables (all in pixel):
+Returned variables (all in pixels):
- x, y - Offset to upper left corner of bounding box.
- w, h - Dimensions of bounding box.
@@ -207,9 +210,8 @@ See also: [al_get_text_width], [al_get_font_line_height],
### API: al_get_ustr_dimensions
-Sometimes, the [al_get_ustr_width] and [al_get_font_line_height]
-functions are not enough for exact text placement, so this function
-returns some additional information.
+Like [al_get_text_dimensions], except the text is passed as an ALLEGRO_USTR
+instead of a NUL-terminated char array.
See also: [al_get_text_dimensions]
@@ -223,14 +225,14 @@ Returns the (compiled) version of the addon, in the same format as
Gets information about all glyphs contained in a font, as a list of ranges.
Ranges have the same format as with [al_grab_font_from_bitmap].
-*ranges_count* is the maximum number of ranges that will be returned.
+`ranges_count` is the maximum number of ranges that will be returned.
-*ranges* should be an array with room for _ranges_count * 2_ elements. The
+`ranges` should be an array with room for `ranges_count` * 2 elements. The
even integers are the first unicode point in a range, the odd integers the
last unicode point in a range.
Returns the number of ranges contained in the font (even if it is bigger
-than *ranges_count*).
+than `ranges_count`).
Since: 5.1.4
@@ -254,8 +256,8 @@ likely be drawn as a square or a space depending on the font.
The `max_width` parameter controls the maximum desired width of the lines.
This function will try to introduce a "soft" line break after the longest
possible series of words that will fit in `max_length` when drawn
-with the given `font`. A "soft" line break can occur on either a space ` `
-or tab `\t` character.
+with the given `font`. A "soft" line break can occur either on a space or
+tab (`\t`) character.
However, it is possible that `max_width` is too small, or the words in `text`
are too long to fit `max_width` when drawn with `font`. In that case, the word
@@ -263,19 +265,16 @@ that is too wide will simply be drawn completely on a line by itself. If you
don't want the text that overflows `max_width` to be visible, then use
[al_set_clipping_rectangle] to clip it off and hide it.
-The funcion [al_draw_multiline_text] will draw each of the lines using
-the `font`, `x`, `color` and `flags` parametes as they were passed
-to this function. It supports the ALLEGRO_ALIGN_LEFT, ALLEGRO_ALIGN_CENTRE,
-ALLEGRO_ALIGN_RIGHT and ALLEGRO_ALIGN_INTEGER value for `flags`.
+The lines `text` was split into will each be drawn using the `font`, `x`, `color`
+and `flags` parameters, vertically starting at `y` and with a distance of
+`line_height` between them. If `line_height` is zero (`0`), the value returned by
+calling [al_get_font_line_height] on `font` will be used as a default instead.
-The lines that [al_draw_multiline_text] breaks the text into will be drawn
-starting at `y` and with a vertical distance between them of `line_height`.
-If `line_height` is zero (`0`), then the value returned by
-[al_get_font_line_height] on `font` will be used as the default value instead.
+The `flags` ALLEGRO_ALIGN_LEFT, ALLEGRO_ALIGN_CENTRE, ALLEGRO_ALIGN_RIGHT
+and ALLEGRO_ALIGN_INTEGER will be honoured by this function.
-For complex or custom text layout that [al_draw_multiline_text] does not
-provide, or for calculating the size of what this function will draw
-without actually drawing it, you can use use [al_do_multiline_text].
+If you want to calculate the size of what this function will draw without actually
+drawing it, or if you need a complex and/or custom layout, you can use [al_do_multiline_text].
Since: 5.1.9
@@ -308,33 +307,26 @@ This function processes the `text` and splits it into lines as
[al_draw_multiline_text] would, and then calls the callback `cb` once
for every line. This is useful for custom drawing of multiline text,
or for calculating the size of multiline text ahead of time. See the
-documentation of [al_draw_multiline_text] for the explanation of the splitting
+documentation on [al_draw_multiline_text] for an explanation of the splitting
algorithm.
-For every line that this function splits `text` into , the callback `cb`
-will be called once. This callback `cb` must be of type
-`bool callback(int line_num, const char *line, int size, void *extra)`.
-
-The callback `cb` will be called with the number of the line starting from zero
-and counting up in `line_num`, a pointer to the beginning character of the line
-in `line`, the size of the line in `size`, and the pointer passed in the
-`extra` parameter to [al_do_multiline_text].
+For every line that this function splits `text` into the callback `cb`
+will be called once with the following parameters:
-Note that while the `line` pointer points to the beginning of the line,
-however, `line` is NOT guaranteed to be a NUL terminated string.
-In stead, `line` is simply a pointer, normally to a character in `text`,
-or to an empty string in case of an empty line. If you need a NUL terminated
-string, you will have to copy `line` to a buffer and NUL terminate it yourself.
+- `line_num` - the number of the line starting from zero and counting up
+- `line` - a pointer to the beginning character of the line (see below)
+- `size` - the size of the line (0 for empty lines)
+- `extra` - the same pointer that was passed to al_do_multiline_text
-The pointer `line` is not guaranteed to be valid after the callback `cb`
-has returned. So in case you still need the contents of `line` after that,
-you must also make a copy of it yourself. In case of an empty line
-the parameter `size` to the callback will be zero and `line` will point
-to an empty string.
+Note that `line` is *not* guaranteed to be a NUL-terminated string, but will merely
+point to a character within `text` or to an empty string in case of an empty line.
+If you need a NUL-terminated string, you will have to copy `line` to a buffer
+and NUL-terminate it yourself. You will also have to make your own copy if you need
+the contents of `line` after `cb` has returned, as `line` is *not* guaranteed to be
+valid after that.
-When `cb` returns true, [al_do_multiline_text] will continue on
-to the next line. And when `cb` returns false, this function will
-stop immediately and not call `cb` anymore.
+If the callback `cb` returns false, al_do_multiline_text will stop immediately, otherwise
+it will continue on to the next line.
Since: 5.1.9
@@ -416,11 +408,12 @@ See also: [al_load_bitmap], [al_grab_font_from_bitmap]
### API: al_load_bitmap_font
-Load a bitmap font from. It does this by first calling [al_load_bitmap_flags]
-and then
-[al_grab_font_from_bitmap]. If you want to for example load an old A4 font,
-you could load the bitmap yourself, then call [al_convert_mask_to_alpha] on it
-and only then pass it to [al_grab_font_from_bitmap].
+Load a bitmap font from a file. This is done by first calling
+[al_load_bitmap_flags] and then [al_grab_font_from_bitmap].
+
+If you wanted to load an old A4 font, for example, it would be better to
+load the bitmap yourself in order to call [al_convert_mask_to_alpha] on it
+before passing it to [al_grab_font_from_bitmap].
See also: [al_load_bitmap_font_flags], [al_load_font], [al_load_bitmap_flags]
@@ -487,7 +480,7 @@ formats:
*TrueType, OpenType, Type1, CID, CFF, Windows FON/FNT, X11 PCF, and
others*
-The *size* parameter determines the size the font will be rendered at,
+The `size` parameter determines the size the font will be rendered at,
specified in pixels. The standard font size is measured in *units per
EM*, if you instead want to specify the size as the total height of
glyphs in pixels, pass it as a negative value.
diff --git a/docs/src/refman/fshook.txt b/docs/src/refman/fshook.txt
index 2c47ab6..ca837bd 100644
--- a/docs/src/refman/fshook.txt
+++ b/docs/src/refman/fshook.txt
@@ -77,7 +77,7 @@ See also: [al_get_errno], [ALLEGRO_FILE_MODE]
Returns the time in seconds since the epoch since the entry was last
accessed.
-Warning: some filesystem either don't support this flag, or people turn it
+Warning: some filesystems either don't support this flag, or people turn it
off to increase performance.
It may not be valid in all circumstances.
diff --git a/docs/src/refman/fullscreen_mode.txt b/docs/src/refman/fullscreen_mode.txt
index c69935e..9a0d7dd 100644
--- a/docs/src/refman/fullscreen_mode.txt
+++ b/docs/src/refman/fullscreen_mode.txt
@@ -22,6 +22,8 @@ typedef struct ALLEGRO_DISPLAY_MODE {
The `refresh_rate` may be zero if unknown.
+For an explanation of what `format` means, see [ALLEGRO_PIXEL_FORMAT].
+
See also: [al_get_display_mode]
## API: al_get_display_mode
diff --git a/docs/src/refman/graphics.txt b/docs/src/refman/graphics.txt
index 67818b0..5922e03 100644
--- a/docs/src/refman/graphics.txt
+++ b/docs/src/refman/graphics.txt
@@ -74,7 +74,7 @@ See also: [al_map_rgba], [al_map_rgb], [al_map_rgb_f]
### API: al_unmap_rgb
-Retrieves components of an ALLEGRO_COLOR, ignoring alpha
+Retrieves components of an ALLEGRO_COLOR, ignoring alpha.
Components will range from 0-255.
See also: [al_unmap_rgba], [al_unmap_rgba_f], [al_unmap_rgb_f]
@@ -496,7 +496,7 @@ See also: [al_convert_bitmap], [al_create_bitmap]
Destroys the given bitmap, freeing all resources used by it.
This function does nothing if the bitmap argument is NULL.
-As a convenience, if the calling thread is currently targets the
+As a convenience, if the calling thread is currently targeting the
bitmap then the bitmap will be untargeted first.
The new target bitmap is unspecified. (since: 5.0.10, 5.1.6)
@@ -566,7 +566,7 @@ ALLEGRO_NO_PRESERVE_TEXTURE
: Normally, every effort is taken to preserve
the contents of bitmaps, since Direct3D may forget them. This can take
extra processing time. If you know it doesn't matter if a bitmap keeps its
- pixel data, for example its a temporary buffer, use this flag to tell Allegro
+ pixel data, for example when it's a temporary buffer, use this flag to tell Allegro
not to attempt to preserve its contents. This can increase performance of
your game or application, but there is a catch. See
ALLEGRO_EVENT_DISPLAY_LOST for further information.
@@ -1292,7 +1292,7 @@ See also: [al_register_bitmap_saver], [al_register_bitmap_loader_f]
### API: al_register_bitmap_saver
Register a handler for [al_save_bitmap]. The given function will be used to
-handle the loading of bitmaps files with the given extension.
+handle the saving of bitmaps files with the given extension.
The extension should include the leading dot ('.') character.
It will be matched case-insensitively.
@@ -1322,7 +1322,7 @@ See also: [al_register_bitmap_loader]
### API: al_register_bitmap_saver_f
Register a handler for [al_save_bitmap_f]. The given function will be
-used to handle the loading of bitmaps files with the given extension.
+used to handle the saving of bitmaps files with the given extension.
The extension should include the leading dot ('.') character.
It will be matched case-insensitively.
@@ -1541,7 +1541,7 @@ ALLEGRO_ALPHA_TEST_VALUE
ALLEGRO_WRITE_MASK
: This determines how the framebuffer and depthbuffer are updated whenever a
- pixel is written (in case alpha and/or depth testing is enabled, after all
+ pixel is written (in case alpha and/or depth testing is enabled: after all
such enabled tests succeed). Depth values are only written if
ALLEGRO_DEPTH_TEST is 1, in addition to the write mask flag being set.
diff --git a/docs/src/refman/haptic.txt b/docs/src/refman/haptic.txt
index 2b386cd..b182931 100644
--- a/docs/src/refman/haptic.txt
+++ b/docs/src/refman/haptic.txt
@@ -27,7 +27,7 @@ This enum contains flags that are used to define haptic effects and
capabilities. If the flag is set in the return value of
[al_get_haptic_capabilities], it means the device supports the given effect.
The value of these flags should be set into a [ALLEGRO_HAPTIC_EFFECT] struct
-to determine what kind of haptic effect should be caused when it is played.
+to determine what kind of haptic effect should be played.
* ALLEGRO_HAPTIC_RUMBLE - simple vibration effects
* ALLEGRO_HAPTIC_PERIODIC - periodic, wave-form effects
@@ -55,7 +55,7 @@ See also: [al_get_haptic_capabilities], [ALLEGRO_HAPTIC_EFFECT]
## API: ALLEGRO_HAPTIC_EFFECT
This struct models a particular haptic or vibration effect. It needs to be
-filled correctly in and uploaded to a haptic device, before the device can
+filled in correctly and uploaded to a haptic device before the device can
play it back.
*Fields:*
@@ -157,7 +157,7 @@ data
the wave form of the vibration effect that will be played on the haptic
device.
- In these cases, `data.periodic.period` muust be set to the period in
+ In these cases, `data.periodic.period` must be set to the period in
seconds of the wave form. The field `data.periodic.magnitude` must be set
to the relative magnitude of intensity between -1.0 and 1.0 at which the
wave form of the vibration will be played back. The field
@@ -171,9 +171,8 @@ data
`data.periodic.custom_len` doubles, each with values between -1.0 and
1.0. This value array will determine the shape of the wave form of the
haptic effect. ALLEGRO_HAPTIC_CUSTOM is not supported on some platforms,
- so use [al_get_haptic_capabilities] to check if it's available. If not,
- then it's a good idea play back a non-custom wave effect instead as a
- substitute.
+ so use [al_get_haptic_capabilities] to check if it's available. If it isn't,
+ you may want to play back a non-custom wave effect as a substitute instead.
If `type` is set to ALLEGRO_HAPTIC_CONSTANT, then `data.constant.level`
must be set to a relative intensity value between 0.0 and 1.0 to
@@ -181,28 +180,28 @@ data
If `type` is set to any of ALLEGRO_HAPTIC_SPRING,
ALLEGRO_HAPTIC_FRICTION, ALLEGRO_HAPTIC_DAMPER, ALLEGRO_HAPTIC_INERTIA,
- ALLEGRO_HAPTIC_RAMP, then the `data.condition` struct shuld be filled in.
- To explain this better, it's best to keep in mind that this kind of
- effects is most useful for steering-wheel kind of devices, where
- resistance or inertia should be applied when turning the wheel of the
- device a certain distance to the right or the left.
+ ALLEGRO_HAPTIC_RAMP, then the `data.condition` struct should be filled in.
+ To explain this better, it's best to keep in mind that these kinds of
+ effects are most useful for steering-wheel kind of devices, where
+ resistance or inertia should be applied when turning the device's wheel a
+ certain distance to the left or right.
The field `data.condition.right_saturation` must be filled in with a
- relative magnitude between -1.0 and 1.0 to determine the the intensity of
+ relative magnitude between -1.0 and 1.0 to determine the intensity of
resistance or inertia on the "right" side of the axis. Likewise,
`data.condition.left_saturation` must be filled in with a relative
- magnitude between -1.0 and 1.0 to determine the the intensity of
+ magnitude between -1.0 and 1.0 to determine the intensity of
resistance or inertia on the "left" side of the axis.
The field `data.condition.deadband` must be filled in with a relative
- value between 0.0 and 1.0, to determine the relative width of the "dead
+ value between 0.0 and 1.0 to determine the relative width of the "dead
band" of the haptic effect. As long as the axis of the haptic device
remains in the "dead band" area, the effect will not be applied. A value
of 0.0 means there is no dead band, and a value of 1.0 means it applied
over the whole range of the axis in question.
The field `data.condition.center` must be filled in with a relative value
- between -1.0 and 1.0, to determine the relative position of the "center"
+ between -1.0 and 1.0 to determine the relative position of the "center"
of the effect around which the dead band is centered. It should be set to
0.0 in case the center should not be shifted.
@@ -224,23 +223,23 @@ data
ALLEGRO_HAPTIC_CONSTANT, ALLEGRO_HAPTIC_RAMP, then `data.envelope`
determines the "envelope" of the effect. That is, it determines the
duration and intensity for the ramp-up attack or "fade in" and the
- ramp-down "fade out" of the effect.
+ ramp-down or "fade out" of the effect.
In these cases the field `data.envelope.attack_level` must be set to a
relative value between 0.0 and 1.0 that determines the intensity the
- effect should have when it starts playing after `replay.delay` seconds
- have passed since the playback started. The field
+ effect should have when it starts playing (after `replay.delay` seconds
+ have passed since the playback was started). The field
`data.envelope.attack_length` must be set to the time in seconds that the
effect should ramp up to the maximum intensity as set by the other
- parameters of the effect. If `data.envelope.attack_length` is 0, then the
+ parameters. If `data.envelope.attack_length` is 0, then the
effect will play immediately at full intensity.
The field `data.envelope.fade_level` must be set to a relative value
between 0.0 and 1.0 that determines the intensity the effect should have
- when at the moment it stops playing after `replay.length + replay.delay`
- seconds have passed since the playback of the effect started. The field
+ when it stops playing after `replay.length + replay.delay` seconds have
+ passed since the playback of the effect started. The field
`data.envelope.fade_length` must be set to the time in seconds that the
- effect should fade out before it finished playing. If
+ effect should fade out before it finishes playing. If
`data.envelope.fade_length` is 0, then the effect will not fade out.
If you don't want to use an envelope, then set all four fields of
@@ -251,9 +250,9 @@ Since: 5.1.8
## API: ALLEGRO_HAPTIC_EFFECT_ID
-This struct is used as a handle to control playback of a haptic effect.
-The struct should be considered opaque. Its implementation is visible merely
-to allow allocation by the users of the Allegro library.
+This struct is used as a handle to control playback of a haptic effect and should
+be considered opaque. Its implementation is visible merely to allow allocation
+by the users of the Allegro library.
Since: 5.1.8
@@ -261,7 +260,7 @@ Since: 5.1.8
Installs the haptic (force feedback) device subsystem. This must be called
before using any other haptic-related functions. Returns true if the haptics
-subsystem could be initialized correctly, false if not.
+subsystem could be initialized correctly, false in case of error.
For portability you should first open a display before calling
[al_install_haptic]. On some platforms, such as DirectInput under
@@ -269,13 +268,10 @@ Windows, [al_install_haptic] will only work if at least one active
display is available. This display must stay available until
[al_uninstall_haptic] is called.
-If you need to close and reopen your active display, e.g. then you should
-call [al_uninstall_haptic] before closing the display, and
+If you need to close and reopen your active display for example, then you should
+call [al_uninstall_haptic] before closing the display, and
[al_install_haptic] after opening it again.
-on Windows
-and DirectInput
-
Since: 5.1.8
## API: al_uninstall_haptic
@@ -283,8 +279,8 @@ Since: 5.1.8
Uninstalls the haptic device subsystem. This is useful since on some
platforms haptic effects are bound to the active display.
-If you need to close and reopen your active display, e.g. then you should
-call [al_uninstall_haptic] before closing the display, and
+If you need to close and reopen your active display for example, then you should
+call [al_uninstall_haptic] before closing the display, and
[al_install_haptic] after opening it again.
Since: 5.1.8
@@ -309,9 +305,9 @@ Since: 5.1.8
## API: al_is_display_haptic
-Returns true if the display has haptic capabilities, false if not. To be more
-precise, this is mainly meant for force feedback that shakes a hand held
-device, such as a phone or a tablet.
+Returns true if the display has haptic capabilities, false if not. This
+mainly concerns force feedback that shakes a hand held device, such as
+a phone or a tablet.
Since: 5.1.8
@@ -366,7 +362,7 @@ Since: 5.1.8
## API: al_release_haptic
-Releases the haptic device and it's resources when it's not needed anymore.
+Releases the haptic device and its resources when it's not needed anymore.
Should also be used in case the joystick configuration changed, such as when
a joystick is hot plugged. This function also automatically releases all
haptic effects that are still uploaded to the device and that have not been
@@ -389,7 +385,7 @@ Since: 5.1.8
## API: al_is_haptic_capable
-Returns true if the haptic device is supports the feature indicated by
+Returns true if the haptic device supports the feature indicated by
the query parameter, false if the feature is not supported.
The query parameter must be one of the values of [ALLEGRO_HAPTIC_CONSTANTS].
@@ -423,7 +419,7 @@ Since: 5.1.8
Turns on or off the automatic centering feature of the haptic device if
supported. Depending on the device automatic centering may ensure that the
-axes of the device are centered again automatically after playing
+axes of the device are centered again automatically after playing
a haptic effect. The intensity parameter should be passed with a value
between 0.0 and 1.0. The value 0.0 means automatic centering is
disabled, and 1.0 means full strength automatic centering. Any value
@@ -441,7 +437,7 @@ Since: 5.1.9
Returns the current automatic centering intensity of the device.
Depending on the device automatic centering may ensure that the
-axes of the device are centered again automatically after playing
+axes of the device are centered again automatically after playing
a haptic effect. The return value can be between 0.0 and 1.0.
The value 0.0 means automatic centering is disabled, and 1.0 means
automatic centering is enabled at full strength. Any value
@@ -460,7 +456,7 @@ Since: 5.1.9
Returns the maximum amount of haptic effects that can be uploaded to the
device. This depends on the operating system, driver, platform and the
-device itself. This can this can return a value as low as 1.
+device itself. This may return a value as low as 1.
Since: 5.1.8
@@ -505,7 +501,7 @@ Since: 5.1.8
## API: al_upload_and_play_haptic_effect
-Uploads and immediately plays back the haptic effect to the device. Returns
+Uploads the haptic effect to the device and starts playback immediately. Returns
true if the upload and playback were successful, false if either failed.
In case false is returned, the haptic effect will be automatically
@@ -530,7 +526,7 @@ Since: 5.1.8
## API: al_is_haptic_effect_playing
Returns true if the haptic effect is currently playing. Returns false if the
-effect has been stopped or if it finsihed playing, or if it has not been
+effect has been stopped or if it has already finished playing, or if it has not been
played yet. The play_id must be a valid [ALLEGRO_HAPTIC_EFFECT_ID] obtained
from [al_upload_haptic_effect], [al_upload_and_play_haptic_effect] or
[al_rumble_haptic].
diff --git a/docs/src/refman/joystick.txt b/docs/src/refman/joystick.txt
index 837f51c..2a0398a 100644
--- a/docs/src/refman/joystick.txt
+++ b/docs/src/refman/joystick.txt
@@ -7,12 +7,12 @@ These functions are declared in the main Allegro header file:
~~~~
On Windows there are two joystick drivers, a DirectInput one and an Xinput
-one. If support for XInput was compiled in, then it can be eabled by
+one. If support for XInput was compiled in, then it can be enabled by
calling al_set_config_value(al_get_system_config(), "joystick", "driver",
-"xinput") befoire alling al_install_joystick, or by setting the same
+"xinput") before calling al_install_joystick, or by setting the same
option in the allegro5.cfg configuration file. The Xinput and DirectInput
drivers are mutually exclusive. The haptics subsystem will use the
-same drivers as the joystick system does.
+same driver as the joystick system does.
## API: ALLEGRO_JOYSTICK
@@ -199,5 +199,6 @@ See also: [ALLEGRO_JOYSTICK_STATE], [al_get_joystick_num_buttons],
## API: al_get_joystick_event_source
-Returns the global joystick event source. All joystick events
-are generated by this event source.
+Returns the global joystick event source. All
+[joystick events][ALLEGRO_EVENT_JOYSTICK_AXIS] are generated by
+this event source.
diff --git a/docs/src/refman/keyboard.txt b/docs/src/refman/keyboard.txt
index 93e10cc..a24c8b1 100644
--- a/docs/src/refman/keyboard.txt
+++ b/docs/src/refman/keyboard.txt
@@ -197,7 +197,8 @@ indicators.
## API: al_get_keyboard_event_source
-Retrieve the keyboard event source.
+Retrieve the keyboard event source. All [keyboard events][ALLEGRO_EVENT_KEY_DOWN]
+are generated by this event source.
Returns NULL if the keyboard subsystem was not installed.
diff --git a/docs/src/refman/monitor.txt b/docs/src/refman/monitor.txt
index d287948..3cc9d9c 100644
--- a/docs/src/refman/monitor.txt
+++ b/docs/src/refman/monitor.txt
@@ -8,7 +8,7 @@ These functions are declared in the main Allegro header file:
## API: ALLEGRO_MONITOR_INFO
-Describes a monitors size and position relative to other
+Describes a monitor's size and position relative to other
monitors. x1, y1 will be 0, 0 on the primary display.
Other monitors can have negative values if they are to the
left or above the primary display.
diff --git a/docs/src/refman/mouse.txt b/docs/src/refman/mouse.txt
index 3cb3c63..823d387 100644
--- a/docs/src/refman/mouse.txt
+++ b/docs/src/refman/mouse.txt
@@ -44,7 +44,7 @@ This function is automatically called when Allegro is shut down.
## API: al_get_mouse_num_axes
-Return the number of buttons on the mouse.
+Return the number of axes on the mouse.
The first axis is 0.
See also: [al_get_mouse_num_buttons]
@@ -101,7 +101,7 @@ See also: [ALLEGRO_MOUSE_STATE], [al_get_mouse_state], [al_get_mouse_state_axis]
Try to position the mouse at the given coordinates on the given display.
The mouse movement resulting from a successful move will generate an
-ALLEGRO_EVENT_MOUSE_WARPED event.
+[ALLEGRO_EVENT_MOUSE_WARPED] event.
Returns true on success, false on failure.
@@ -136,7 +136,8 @@ See also: [al_set_mouse_xy], [al_set_mouse_z], [al_set_mouse_w]
## API: al_get_mouse_event_source
-Retrieve the mouse event source.
+Retrieve the mouse event source. All [mouse events][ALLEGRO_EVENT_MOUSE_AXES]
+are generated by this event source.
Returns NULL if the mouse subsystem was not installed.
@@ -184,7 +185,8 @@ See also: [al_set_mouse_wheel_precision]
### API: al_create_mouse_cursor
-Create a mouse cursor from the bitmap provided.
+Create a mouse cursor from the bitmap provided. `x_focus` and `y_focus`
+describe the bit of the cursor that will represent the actual mouse position.
Returns a pointer to the cursor on success, or NULL on failure.
diff --git a/docs/src/refman/native_dialog.txt b/docs/src/refman/native_dialog.txt
index 24bf05a..88b7ade 100644
--- a/docs/src/refman/native_dialog.txt
+++ b/docs/src/refman/native_dialog.txt
@@ -46,35 +46,32 @@ at a time.
Parameters:
-- initial_path: The initial search path and filename. Can be NULL.
+- `initial_path`: The initial search path and filename. Can be NULL.
To start with a blank file name the string should end with a directory
separator (this should be the common case).
-- title: Title of the dialog.
+- `title`: Title of the dialog.
-- patterns: A list of semi-colon separated patterns to match. This
- should not contain any whitespace characters. If no file patterns are
- supported by the native dialog, this parameter is ignored. If a pattern
+- `patterns`: A list of semi-colon separated patterns to match. This
+ should not contain any whitespace characters. If a pattern
contains the '/' character, then it is treated as a MIME type (e.g.
- 'image/png'). Not all platforms support this, and on this platforms such
- patterns are ignored.
+ 'image/png'). Not all platforms support file patterns. If the native dialog
+ does not provide support, this parameter is ignored.
-- mode: 0, or a combination of the flags below.
-
-Possible flags for the 'flags' parameter are:
+- `mode`: 0, or a combination of the following flags:
ALLEGRO_FILECHOOSER_FILE_MUST_EXIST
: If supported by the native dialog, it will not allow entering new names,
but just allow existing files to be selected. Else it is ignored.
ALLEGRO_FILECHOOSER_SAVE
: If the native dialog system has a different dialog for saving (for example
- one which allows creating new directories), it is used. Else ignored.
+ one which allows creating new directories), it is used. Else it is ignored.
ALLEGRO_FILECHOOSER_FOLDER
: If there is support for a separate dialog to select a folder instead of a
file, it will be used.
ALLEGRO_FILECHOOSER_PICTURES
: If a different dialog is available for selecting pictures, it is used. Else
- ignored.
+ it is ignored.
ALLEGRO_FILECHOOSER_SHOW_HIDDEN
: If the platform supports it, also hidden files will be shown.
ALLEGRO_FILECHOOSER_MULTIPLE
@@ -84,7 +81,8 @@ Returns:
A handle to the dialog which you can pass to
[al_show_native_file_dialog] to display it, and from which you then can
-query the results. When you are done, call
+query the results using [al_get_native_file_dialog_count] and
+[al_get_native_file_dialog_path]. When you are done, call
[al_destroy_native_file_dialog] on it.
If a dialog window could not be created then this function returns NULL.
@@ -106,7 +104,8 @@ Returns the number of files selected, or 0 if the dialog was cancelled.
## API: al_get_native_file_dialog_path
-Returns one of the selected paths.
+Returns one of the selected paths with index `i`. The index should range
+from `0` to the return value of [al_get_native_file_dialog_count] `-1`.
## API: al_destroy_native_file_dialog
@@ -131,14 +130,14 @@ ALLEGRO_MESSAGEBOX_ERROR
ALLEGRO_MESSAGEBOX_QUESTION
: The message is a question.
ALLEGRO_MESSAGEBOX_OK_CANCEL
-: Instead of the "OK" button also display a cancel button.
+: Display a cancel button alongside the "OK" button.
Ignored if `buttons` is not NULL.
ALLEGRO_MESSAGEBOX_YES_NO
-: Instead of the "OK" button display Yes/No buttons.
+: Display Yes/No buttons instead of the "OK" button.
Ignored if `buttons` is not NULL.
[al_show_native_message_box] may be called without Allegro being installed.
-This is useful to report an error to initialise Allegro itself.
+This is useful to report an error during initialisation of Allegro itself.
Returns:
@@ -159,9 +158,9 @@ int button = al_show_native_message_box(
display,
"Warning",
"Are you sure?",
- "If you click yes then you are confirming that \"Yes\""
- "is your response to the query which you have"
- "generated by the action you took to open this"
+ "If you click yes then you are confirming that \"Yes\" "
+ "is your response to the query which you have "
+ "generated by the action you took to open this "
"message box.",
NULL,
ALLEGRO_MESSAGEBOX_YES_NO
@@ -179,8 +178,8 @@ Use [al_close_native_text_log] to close the window again.
The flags available are:
ALLEGRO_TEXTLOG_NO_CLOSE
-: Prevent the window from having a close button. Otherwise if the close
- button is pressed an event is generated; see
+: Prevent the window from having a close button. Otherwise, if the close
+ button is pressed, an event is generated; see
[al_get_native_text_log_event_source].
ALLEGRO_TEXTLOG_MONOSPACE
@@ -246,7 +245,7 @@ way for you to determine exactly which item generated the event.
There are many functions that take `pos` as a parameter used for locating a
particular menu item. In those cases, it represents one of two things: an ID
-or zero-based index. Any value greater than zero will always be treated as an ID.
+or a zero-based index. Any value greater than zero will always be treated as an ID.
Anything else (including zero) will be considered an index based on the absolute
value. In other words, 0 is the first menu item, -1 is the second menu item, -2
is the third menu item, and so on.
@@ -257,7 +256,7 @@ The event type is `ALLEGRO_EVENT_MENU_CLICK`. It contains three fields:
event.user.data1 = id;
event.user.data2 = (intptr_t) display;
event.user.data3 = (intptr_t) menu;
-~~~~c
+~~~~
The `display` and `menu` may be NULL if it was not possible to tell exactly
which item generated the event.
@@ -265,7 +264,7 @@ which item generated the event.
A basic example:
~~~~c
-#define FILE_EXIT_ID 1
+ #define FILE_EXIT_ID 1
ALLEGRO_MENU *menu = al_create_menu();
ALLEGRO_MENU *file_menu = al_create_menu();
@@ -406,7 +405,7 @@ The `icon` is not yet supported.
The `submenu` parameter indicates that this item contains a child menu.
The child menu must have previously been created with `al_create_menu`,
-and is not associated with any other menu.
+and not be associated with any other menu.
Returns `true` on success.
@@ -416,9 +415,9 @@ See also: [al_append_menu_item], [al_remove_menu_item]
### API: al_remove_menu_item
-Removes the specified item from the menu. If the item contains a sub-menu,
-it too is destroyed. Any references to it are invalidated. If you want to
-preserve that sub-menu, you should first make a copy with [al_clone_menu].
+Removes the specified item from the menu and destroys it. If the item
+contains a sub-menu, it too is destroyed. Any references to it are invalidated.
+If you want to preserve that sub-menu, you should first make a copy with [al_clone_menu].
This is safe to call on a menu that is currently being displayed.
@@ -451,7 +450,7 @@ See also: [al_clone_menu]
### API: al_destroy_menu
Destroys an entire menu, including its sub-menus. Any references to it or
-a sub-menu is no longer valid. It is safe to call this on a menu that is
+a sub-menu are no longer valid. It is safe to call this on a menu that is
currently being displayed.
Since: 5.1.0
@@ -553,7 +552,7 @@ Searches in the `haystack` menu for an item with the given `id`. (Note that
this only represents a literal ID, and cannot be used as an index.)
If `menu` and `index` are not `NULL`, they will be set as the parent menu
-containing the item and the zero-based index of the item. (If the menu item
+containing the item and the zero-based (positive) index of the item. (If the menu item
was not found, then their values are undefined.)
Returns true if the menu item was found.
@@ -613,7 +612,7 @@ to happen, you should first remove the menu with [al_remove_display_menu].
If the menu is already attached to a display, it will not be attached to the
new display. If `menu` is `NULL`, the current menu will still be destroyed.
-Note that attaching a menu may cause the window as available to your application
+> *Note:* Attaching a menu may cause the window as available to your application
to be resized! You should listen for a resize event, check how much space was
lost, and resize the window accordingly if you want to maintain your window's
prior size.
diff --git a/docs/src/refman/opengl.txt b/docs/src/refman/opengl.txt
index 79e3fbc..81acb22 100644
--- a/docs/src/refman/opengl.txt
+++ b/docs/src/refman/opengl.txt
@@ -176,7 +176,7 @@ different OpenGL context, the target bitmap will be changed to NULL.
Normally you do not need to use this function, as the context will be made
current when you call [al_set_target_bitmap] or [al_set_target_backbuffer].
-You might need if it you created an OpenGL "forward compatible" context.
+You might need it if you created an OpenGL "forward compatible" context.
Then [al_get_backbuffer] only returns NULL, so it would not work to pass that
to [al_set_target_bitmap].
diff --git a/docs/src/refman/path.txt b/docs/src/refman/path.txt
index 1098e8d..4c460c2 100644
--- a/docs/src/refman/path.txt
+++ b/docs/src/refman/path.txt
@@ -22,7 +22,7 @@ directory name in the path. Otherwise the last component is treated as the
filename.
The string may be NULL for an empty path.
-See also: [al_create_path], [al_destroy_path]
+See also: [al_create_path_for_directory], [al_destroy_path]
## API: al_create_path_for_directory
diff --git a/docs/src/refman/primitives.txt b/docs/src/refman/primitives.txt
index f881670..d84ceb0 100644
--- a/docs/src/refman/primitives.txt
+++ b/docs/src/refman/primitives.txt
@@ -115,7 +115,7 @@ semi-transparent pixels. The advantages of multisampling is that slanted shapes
will look smoother because they will not have jagged edges. A disadvantage of
multisampling is that it may make vertical and horizontal edges blurry. While
the exact rules for multisampling are unspecified, and may vary from GPU to
-GPU it is usually safe to assume that as long as a pixel is either completely
+GPU, it is usually safe to assume that as long as a pixel is either completely
covered by a shape or completely not covered, then the shape edges will be
sharp. The offsets used in the second diagram were chosen so that this is the
case: if you use those offsets, your shapes (if they are oriented the same way
@@ -264,8 +264,8 @@ assert((int)points[(num_points - 1) * 2 + 1][1] == 9);
* stride - Distance (in bytes) between starts of successive pairs of points
* cx, cy - Center of the arc
* rx, ry - Radii of the arc
-* start_theta - The initial angle from which the arc is calculated
-* delta_theta - Angular span of the arc (pass a negative number to switch
+* start_theta - The initial angle from which the arc is calculated in radians
+* delta_theta - Angular span of the arc in radians (pass a negative number to switch
direction)
* thickness - Thickness of the arc
* num_points - The number of points to calculate
@@ -281,8 +281,8 @@ Draws a pieslice (outlined circular sector).
* cx, cy - Center of the pieslice
* r - Radius of the pieslice
* color - Color of the pieslice
-* start_theta - The initial angle from which the pieslice is drawn
-* delta_theta - Angular span of the pieslice (pass a negative number to switch
+* start_theta - The initial angle from which the pieslice is drawn in radians
+* delta_theta - Angular span of the pieslice in radians (pass a negative number to switch
direction)
* thickness - Thickness of the circle, pass `<= 0` to draw hairline pieslice
@@ -299,8 +299,8 @@ Draws a filled pieslice (filled circular sector).
* cx, cy - Center of the pieslice
* r - Radius of the pieslice
* color - Color of the pieslice
-* start_theta - The initial angle from which the pieslice is drawn
-* delta_theta - Angular span of the pieslice (pass a negative number to switch
+* start_theta - The initial angle from which the pieslice is drawn in radians
+* delta_theta - Angular span of the pieslice in radians (pass a negative number to switch
direction)
Since: 5.0.6, 5.1.0
@@ -366,8 +366,8 @@ Draws an arc.
* cx, cy - Center of the arc
* r - Radius of the arc
* color - Color of the arc
-* start_theta - The initial angle from which the arc is calculated
-* delta_theta - Angular span of the arc (pass a negative number to switch
+* start_theta - The initial angle from which the arc is calculated in radians
+* delta_theta - Angular span of the arc in radians (pass a negative number to switch
direction)
* thickness - Thickness of the arc, pass `<= 0` to draw hairline arc
@@ -382,8 +382,8 @@ Draws an elliptical arc.
* cx, cy - Center of the arc
* rx, ry - Radii of the arc
* color - Color of the arc
-* start_theta - The initial angle from which the arc is calculated
-* delta_theta - Angular span of the arc (pass a negative number to switch
+* start_theta - The initial angle from which the arc is calculated in radians
+* delta_theta - Angular span of the arc in radians (pass a negative number to switch
direction)
* thickness - Thickness of the arc, pass `<= 0` to draw hairline arc
@@ -436,7 +436,7 @@ doublets of floats, corresponding to x and y coordinates of the vertices.
* dest_stride - Distance (in bytes) between starts of successive pairs of
coordinates in the destination buffer
* points - An array of pairs of coordinates for each point
-* points_stride - Distance (in bytes) between starts successive pairs of
+* points_stride - Distance (in bytes) between starts of successive pairs of
coordinates in the points buffer
* thickness - Thickness of the spline ribbon
* num_segments - The number of points to calculate
@@ -445,14 +445,18 @@ See also: [al_draw_ribbon], [al_calculate_arc], [al_calculate_spline]
### API: al_draw_ribbon
-Draws a series of straight lines given an array of points. The ribbon will go
-through all of the passed points.
+Draws a ribbon given an array of points. The ribbon will go through all of
+the passed points. The points buffer should consist of regularly spaced
+doublets of floats, corresponding to x and y coordinates of the vertices.
*Parameters:*
* points - An array of coordinate pairs (x and y) for each point
+* points_stride - Distance (in bytes) between starts of successive pairs of
+ coordinates in the points buffer
* color - Color of the spline
* thickness - Thickness of the spline, pass `<= 0` to draw hairline spline
+* num_segments - The number of segments
See also: [al_calculate_ribbon]
@@ -464,11 +468,11 @@ routines also support using textures on the primitives with the following
restrictions:
For maximum portability, you should only use textures that have dimensions that
-are a power of two, as not every videocard supports them completely. This
-warning is relaxed, however, if the texture coordinates never exit the
-boundaries of a single bitmap (i.e. you are not having the texture repeat/tile).
-As long as that is the case, any texture can be used safely. Sub-bitmaps work
-as textures, but cannot be tiled.
+are a power of two, as not every videocard supports textures of different sizes
+completely. This warning is relaxed, however, if the texture coordinates
+never exit the boundaries of a single bitmap (i.e. you are not having the texture
+repeat/tile). As long as that is the case, any texture can be used safely.
+Sub-bitmaps work as textures, but cannot be tiled.
Some platforms also dictate a minimum texture size, which means that textures
smaller than that size will not tile properly. The minimum size that will work
@@ -490,12 +494,12 @@ Draws a subset of the passed vertex array.
*Parameters:*
-* texture - Texture to use, pass 0 to use only color shaded primitves
+* texture - Texture to use, pass NULL to use only color shaded primitves
* vtxs - Pointer to an array of vertices
-* decl - Pointer to a vertex declaration. If set to NULL, the vertices
- are assumed to be of the ALLEGRO_VERTEX type
+* decl - Pointer to a [vertex declaration][al_create_vertex_decl]. If set to NULL,
+ the vertices are assumed to be of the [ALLEGRO_VERTEX] type
* start - Start index of the subset of the vertex array to draw
-* end - One past the last index of subset of the vertex array to draw
+* end - One past the last index of the subset of the vertex array to draw
* type - A member of the [ALLEGRO_PRIM_TYPE] enumeration, specifying what kind
of primitive to draw
@@ -524,9 +528,9 @@ to specify which vertices to use.
*Parameters:*
-* texture - Texture to use, pass 0 to use only shaded primitves
+* texture - Texture to use, pass NULL to use only color shaded primitves
* vtxs - Pointer to an array of vertices
-* decl - Pointer to a vertex declaration. If set to 0, the vtxs are assumed
+* decl - Pointer to a vertex declaration. If set to NULL, the vtxs are assumed
to be of the ALLEGRO_VERTEX type
* indices - An array of indices into the vertex array
* num_vtx - Number of indices from the indices array you want to draw
@@ -549,7 +553,7 @@ it must be created with the `ALLEGRO_PRIM_BUFFER_READWRITE`).
*Parameters:*
* vertex_buffer - Vertex buffer to draw
-* texture - Texture to use, pass 0 to use only color shaded primitves
+* texture - Texture to use, pass NULL to use only color shaded primitves
* start - Start index of the subset of the vertex buffer to draw
* end - One past the last index of the subset of the vertex buffer to draw
* type - A member of the [ALLEGRO_PRIM_TYPE] enumeration, specifying what kind
@@ -574,7 +578,7 @@ created with the `ALLEGRO_PRIM_BUFFER_READWRITE`).
*Parameters:*
* vertex_buffer - Vertex buffer to draw
-* texture - Texture to use, pass 0 to use only color shaded primitves
+* texture - Texture to use, pass NULL to use only color shaded primitves
* index_buffer - Index buffer to use
* start - Start index of the subset of the vertex buffer to draw
* end - One past the last index of the subset of the vertex buffer to draw
@@ -596,8 +600,8 @@ Draws a triangle using the software rasterizer and user supplied pixel
functions. For help in understanding what these functions do, see the
implementation of the various shading routines in addons/primitives/tri_soft.c.
The triangle is drawn in two segments, from top to bottom. The segments are
-deliniated by the vertically middle vertex of the triangle. One of each segment
-may be absent if two vertices are horizontally collinear.
+deliniated by the vertically middle vertex of the triangle. One of the two
+segments may be absent if two vertices are horizontally collinear.
*Parameters:*
@@ -611,7 +615,7 @@ may be absent if two vertices are horizontally collinear.
drawn in the segment.
The second two are the left minor and the left major steps, respectively.
They represent the sizes of two steps taken by the rasterizer as it walks
- on the left side of the triangle. From then on, the each step will either
+ on the left side of the triangle. From then on, each step will either
be classified as a minor or a major step, corresponding to the above
values.
* step - Called once per scanline. The last parameter is set to 1 if the step
@@ -642,7 +646,7 @@ The line is drawn top to bottom.
* step - Called once per pixel. The second parameter is set to 1 if the step is
a minor step, and 0 if this step is a major step. Minor steps are taken only
either in x or y directions.
- Major steps are taken in both directions diagonally. In all cases, the the
+ Major steps are taken in both directions diagonally. In all cases, the
absolute value of the change in coordinate is at most 1 in either direction.
* draw - Called once per pixel. The function is expected to draw the pixel at
the coordinates passed to it.
@@ -657,7 +661,7 @@ Creates a vertex declaration, which describes a custom vertex format.
*Parameters:*
-* elements - An array of ALLEGRO_VERTEX_ELEMENT structures.
+* elements - An array of [ALLEGRO_VERTEX_ELEMENT] structures.
* stride - Size of the custom vertex structure
*Returns:*
@@ -693,7 +697,7 @@ created (e.g. the system only supports write-only buffers).
*Parameters:*
-* decl - Vertex type that this buffer will hold. 0 implies that this buffer will
+* decl - Vertex type that this buffer will hold. NULL implies that this buffer will
hold [ALLEGRO_VERTEX] vertices
* initial_data - Memory buffer to copy from to initialize the vertex buffer. Can
be `NULL`, in which case the buffer is uninitialized.
@@ -708,7 +712,7 @@ See also: [ALLEGRO_VERTEX_BUFFER], [al_destroy_vertex_buffer]
### API: al_destroy_vertex_buffer
-Destroys a vertex buffer. Does nothing if passed 0.
+Destroys a vertex buffer. Does nothing if passed NULL.
Since: 5.1.3
@@ -716,8 +720,8 @@ See also: [ALLEGRO_VERTEX_BUFFER], [al_create_vertex_buffer]
### API: al_lock_vertex_buffer
-Locks a vertex buffer so you can access its data. Will return 0 if the
-parameters are invalid, if reading is requested from a write only buffer and
+Locks a vertex buffer so you can access its data. Will return NULL if the
+parameters are invalid, if reading is requested from a write only buffer, or
if the buffer is already locked.
*Parameters:*
@@ -778,7 +782,7 @@ See also: [ALLEGRO_INDEX_BUFFER], [al_destroy_index_buffer]
### API: al_destroy_index_buffer
-Destroys a index buffer. Does nothing if passed 0.
+Destroys a index buffer. Does nothing if passed NULL.
Since: 5.1.8
@@ -786,7 +790,7 @@ See also: [ALLEGRO_INDEX_BUFFER], [al_create_index_buffer]
### API: al_lock_index_buffer
-Locks a index buffer so you can access its data. Will return 0 if the
+Locks a index buffer so you can access its data. Will return NULL if the
parameters are invalid, if reading is requested from a write only buffer and
if the buffer is already locked.
@@ -823,7 +827,7 @@ See also: [ALLEGRO_INDEX_BUFFER]
Draw a series of line segments.
-* vertex - Interleaved array of (x, y) vertex coordinates
+* vertices - Interleaved array of (x, y) vertex coordinates
* vertex_stride - the number of bytes between pairs of vertices (the stride)
* vertex_count - Number of vertices in the array
* join_style - Member of [ALLEGRO_LINE_JOIN] specifying how to render the
@@ -956,7 +960,7 @@ to be convex but must not be self-overlapping.
in each hole. The array must be terminated with an element with value zero.
* emit_triangle -
a function to be called for every set of three points that form a triangle.
- The function is passed the indexes of the points in `vertices` and `userdata`.
+ The function is passed the indices of the points in `vertices` and `userdata`.
* userdata - arbitrary data to be passed to emit_triangle.
Since: 5.1.0
@@ -996,11 +1000,11 @@ See also:
A small structure describing a certain element of a vertex. E.g. the
position of the vertex, or its color. These structures are used by the
-al_create_vertex_decl function to create the vertex declaration. For that they
+[al_create_vertex_decl] function to create the vertex declaration. For that they
generally occur in an array. The last element of such an array should have the
attribute field equal to 0, to signify that it is the end of the array.
Here is an example code that would create a declaration describing the
-ALLEGRO_VERTEX structure (passing this as vertex declaration to
+[ALLEGRO_VERTEX] structure (passing this as vertex declaration to
al_draw_prim would be identical to passing NULL):
~~~~c
@@ -1022,7 +1026,7 @@ ALLEGRO_VERTEX_DECL* decl = al_create_vertex_decl(elems, sizeof(ALLEGRO_VERTEX))
this attribute signifies
* storage - A member of the [ALLEGRO_PRIM_STORAGE] enumeration, specifying how
this attribute is stored
-* offset - Offset in bytes from the beginning of the custom vertex structure. C
+* offset - Offset in bytes from the beginning of the custom vertex structure. The C
function offsetof is very useful here.
See also:
diff --git a/docs/src/refman/shader.txt b/docs/src/refman/shader.txt
index 2387eb2..fa24200 100644
--- a/docs/src/refman/shader.txt
+++ b/docs/src/refman/shader.txt
@@ -160,7 +160,7 @@ other shader functions as that will lead to undefined behavior.
Examine the output of [al_get_default_shader_source] for an example of how to
use the above uniforms and attributes.
-Returns true on access and false on error, in which case the error log is
+Returns true on success and false on error, in which case the error log is
updated. The error log can be retrieved with [al_get_shader_log].
Since: 5.1.0
@@ -173,7 +173,7 @@ See also: [al_attach_shader_source_file], [al_build_shader],
Like [al_attach_shader_source] but reads the source code for the shader from
the named file.
-Returns true on access and false on error, in which case the error log is
+Returns true on success and false on error, in which case the error log is
updated. The error log can be retrieved with [al_get_shader_log].
Since: 5.1.0
@@ -186,7 +186,7 @@ This is required before the shader can be used with [al_use_shader]. It should
be called after successfully attaching the pixel and/or vertex shaders with
[al_attach_shader_source] or [al_attach_shader_source_file].
-Returns true on access and false on error, in which case the error log is
+Returns true on success and false on error, in which case the error log is
updated. The error log can be retrieved with [al_get_shader_log].
Since: 5.1.6
diff --git a/docs/src/refman/state.txt b/docs/src/refman/state.txt
index 15264bd..3c014e2 100644
--- a/docs/src/refman/state.txt
+++ b/docs/src/refman/state.txt
@@ -50,7 +50,7 @@ See also: [al_store_state], [ALLEGRO_STATE_FLAGS]
## API: al_store_state
Stores part of the state of the current thread in the given [ALLEGRO_STATE]
-objects. The flags parameter can take any bit-combination of these flags:
+object. The flags parameter can take any bit-combination of these flags:
* ALLEGRO_STATE_NEW_DISPLAY_PARAMETERS - new_display_format,
new_display_refresh_rate, new_display_flags
@@ -74,5 +74,5 @@ for the calling thread.
## API: al_set_errno
-Set the error number for for the calling thread.
+Set the error number for the calling thread.
diff --git a/docs/src/refman/system.txt b/docs/src/refman/system.txt
index 7d49b82..bffdd81 100644
--- a/docs/src/refman/system.txt
+++ b/docs/src/refman/system.txt
@@ -78,7 +78,7 @@ ALLEGRO_RESOURCES_PATH
should use this path to locate that data. On most platforms, this is the
directory that contains the executable file.
- If ran from an OS X app bundle, then this will point to the internal
+ If run from an OS X app bundle, then this will point to the internal
resource directory (<bundle.app>/Contents/Resources). To maintain
consistency, if you put your resources into a directory called "data"
beneath the executable on some other platform (like Windows), then
@@ -218,6 +218,4 @@ debug channels, logging levels and trace format.
Note that logging is disabled in release mode by default and needs to be
enabled in the build system - the callback will never be called otherwise.
-See also: [Configuration files]
-
Since: 5.1.5
diff --git a/docs/src/refman/threads.txt b/docs/src/refman/threads.txt
index 32df28d..5f5b1f4 100644
--- a/docs/src/refman/threads.txt
+++ b/docs/src/refman/threads.txt
@@ -107,7 +107,7 @@ See also: [al_join_thread].
Runs the passed function in its own thread, with `arg` passed to it as only
parameter. This is similar to calling [al_create_thread], [al_start_thread]
and (after the thread has finished) [al_destroy_thread] - but you don't have
-the possibility of ever calling [al_join_thread] on the thread any longer.
+the possibility of ever calling [al_join_thread] on the thread.
## API: al_create_mutex
diff --git a/docs/src/refman/time.txt b/docs/src/refman/time.txt
index 77ed07f..47dcae8 100644
--- a/docs/src/refman/time.txt
+++ b/docs/src/refman/time.txt
@@ -8,7 +8,7 @@ These functions are declared in the main Allegro header file:
## API: ALLEGRO_TIMEOUT
-Represent a timeout value. The size of the structure is known so can be
+Represent a timeout value. The size of the structure is known so it can be
statically allocated. The contents are private.
See also: [al_init_timeout]
@@ -32,7 +32,7 @@ See also: [ALLEGRO_TIMEOUT], [al_wait_for_event_until]
## API: al_rest
-Waits for the specified number seconds. This tells the system to pause
+Waits for the specified number of seconds. This tells the system to pause
the current thread for the given amount of time. With some operating
systems, the accuracy can be in the order of 10ms. That is, even
@@ -40,6 +40,6 @@ systems, the accuracy can be in the order of 10ms. That is, even
al_rest(0.000001)
~~~~
-might pause for something like 10ms. Also see the section <Timer routines>
-on easier ways to time your program without using up all CPU.
+might pause for something like 10ms. Also see the section on Timer routines
+for easier ways to time your program without using up all CPU.
diff --git a/docs/src/refman/timer.txt b/docs/src/refman/timer.txt
index 7243700..2f50cc6 100644
--- a/docs/src/refman/timer.txt
+++ b/docs/src/refman/timer.txt
@@ -113,4 +113,5 @@ See also: [al_get_timer_speed]
## API: al_get_timer_event_source
-Retrieve the associated event source.
+Retrieve the associated event source. Timers will generate events of
+type [ALLEGRO_EVENT_TIMER].
diff --git a/docs/src/refman/touch.txt b/docs/src/refman/touch.txt
index 62d7ee0..011aa57 100644
--- a/docs/src/refman/touch.txt
+++ b/docs/src/refman/touch.txt
@@ -120,7 +120,7 @@ See also: [ALLEGRO_MOUSE_EMULATION_MODE], [al_set_mouse_emulation_mode].
## API: al_get_touch_input_event_source
Returns the global touch input event source. This event source generates
-touch input events.
+[touch input events][ALLEGRO_EVENT_TOUCH_BEGIN].
Since: 5.1.0
@@ -129,8 +129,8 @@ See also: [ALLEGRO_EVENT_SOURCE], [al_register_event_source]
## API: al_get_touch_input_mouse_emulation_event_source
Returns the global touch input event source for emulated mouse events.
-This event source generates emulated mouse events that are based on touch
-events.
+This event source generates [emulated mouse events][ALLEGRO_EVENT_MOUSE_AXES]
+that are based on touch events.
See also: [ALLEGRO_EVENT_SOURCE], [al_register_event_source]
diff --git a/docs/src/refman/transformations.txt b/docs/src/refman/transformations.txt
index 845e75c..1e26e99 100644
--- a/docs/src/refman/transformations.txt
+++ b/docs/src/refman/transformations.txt
@@ -6,13 +6,26 @@ These functions are declared in the main Allegro header file:
#include <allegro5/allegro.h>
~~~~
+Transformations allow you to transform the coordinates you use for drawing
+operations without additional overhead. Scaling, rotating, translating, and
+combinations of these are possible as well as using custom transformations.
+
+Transformations are set per target-bitmap, i. e. a change of the target bitmap
+will also change the active transformation.
+It is also possible to specify custom projection transformations. These are set per
+display.
+
+Allegro provides convenience functions to construct transformations in 2D and 3D
+variants (the latter with a `_3d` suffix), so you don't have to deal with the
+underlying matrix algebra yourself.
+
The transformations are combined in the order of the function invocations. Thus
to create a transformation that first rotates a point and then translates it,
you would (starting with an identity transformation) call [al_rotate_transform]
and then [al_translate_transform]. This approach is opposite of what OpenGL uses
but similar to what Direct3D uses.
-For those who known the matrix algebra going behind the scenes, what the
+For those who know the matrix algebra going behind the scenes, what the
transformation functions in Allegro do is "pre-multiply" the successive
transformations. So, for example, if you have code that does:
diff --git a/docs/src/refman/utf8.txt b/docs/src/refman/utf8.txt
index f1d916e..b600f02 100644
--- a/docs/src/refman/utf8.txt
+++ b/docs/src/refman/utf8.txt
@@ -20,7 +20,7 @@ A *code point* is the integer value of a character, but not all code points are
characters, as some code points have other uses. Unlike legacy character
sets, the set of code points is open ended and more are assigned with time.
-Clearly it is impossible represent each code point with a 8-bit byte (limited
+Clearly it is impossible to represent each code point with a 8-bit byte (limited
to 256 code points) or even a 16-bit integer (limited to 65536 code points).
It is possible to store code points in a 32-bit integers but it is space
inefficient, and not actually that useful (at least, when handling the full
@@ -75,7 +75,7 @@ This is invalid and needs to be guarded against.
In the following "ustr" functions, be careful whether a function takes code
unit (byte) or code point indices. In general, all position parameters are
-in code unit offsets. This may be surprising, but if you think about, is
+in code unit offsets. This may be surprising, but if you think about it, it is
required for good performance. (It also means some functions will work even
if they do not contain UTF-8, since they only care about storing bytes, so
you may actually store arbitrary data in the ALLEGRO_USTRs.)
@@ -116,7 +116,7 @@ See also: [al_ustr_new_from_buffer], [al_ustr_newf], [al_ustr_dup],
### API: al_ustr_new_from_buffer
Create a new string containing a copy of the buffer pointed to by `s` of the
-given size in bytes. The string must eventually be freed with [al_ustr_free].
+given `size` in bytes. The string must eventually be freed with [al_ustr_free].
See also: [al_ustr_new]
@@ -200,7 +200,7 @@ See also: [al_ustr_dup_substr], [al_ustr_free]
### API: al_ustr_dup_substr
Return a new copy of a string, containing its contents in the byte interval
-\[start_pos, end_pos). The new string will be NUL terminated and will
+\[`start_pos`, `end_pos`). The new string will be NUL terminated and will
need to be freed with [al_ustr_free].
If necessary, use [al_ustr_offset] to find the byte offsets for a given code
@@ -259,7 +259,7 @@ pointed to by the `info` parameter. The new string will not have any other
storage allocated of its own, so if you allocate the `info` structure on the
stack then no explicit "free" operation is required.
-The referenced interval is \[start_pos, end_pos). Both are byte offsets.
+The referenced interval is \[`start_pos`, `end_pos`). Both are byte offsets.
The string is valid until the underlying string is modified or destroyed.
@@ -316,9 +316,9 @@ See also: [al_ustr_prev]
Find the byte offset of the previous code point in string, before `*pos`.
`*pos` does not have to be at the beginning of a code point.
-Returns true on success, then value pointed to by `pos` will be updated to the
+Returns true on success, and the value pointed to by `pos` will be updated to the
found offset. Otherwise returns false if `*pos` was already at the end of
-the string, then `*pos` is unmodified.
+the string, and `*pos` is unmodified.
This function just looks for an appropriate byte; it doesn't check if found
offset is the beginning of a valid code point. If you are working with
@@ -331,7 +331,7 @@ See also: [al_ustr_next]
### API: al_ustr_get
-Return the code point in `us` beginning at byte offset `pos`.
+Return the code point in `ub` beginning at byte offset `pos`.
On success returns the code point value.
If `pos` was out of bounds (e.g. past the end of the string), return -1.
@@ -466,7 +466,7 @@ See also: [al_ustr_remove_range]
### API: al_ustr_remove_range
-Remove the interval \[start_pos, end_pos) from a string.
+Remove the interval \[`start_pos`, `end_pos`) from a string.
`start_pos` and `end_pos` are byte offsets.
Both may be past the end of the string
but cannot be less than 0 (the start of the string).
@@ -477,7 +477,7 @@ See also: [al_ustr_remove_chr], [al_ustr_truncate]
### API: al_ustr_truncate
-Truncate a portion of a string at byte offset `start_pos` onwards.
+Truncate a portion of a string from byte offset `start_pos` onwards.
`start_pos` can be past the end of the string (has no effect)
but cannot be less than 0.
@@ -525,7 +525,7 @@ See also: [al_ustr_assign_substr], [al_ustr_assign_cstr]
### API: al_ustr_assign_substr
Overwrite the string `us1` with the contents of `us2` in the byte interval
-\[start_pos, end_pos). The end points will be clamed to the bounds of `us2`.
+\[`start_pos`, `end_pos`). The end points will be clamped to the bounds of `us2`.
Usually you will first have to use [al_ustr_offset] to find the byte offsets.
@@ -535,7 +535,7 @@ See also: [al_ustr_assign], [al_ustr_assign_cstr]
### API: al_ustr_assign_cstr
-Overwrite the string `us` with the contents of the C-style string `s`.
+Overwrite the string `us1` with the contents of the C-style string `s`.
Returns true on success, false on error.
See also: [al_ustr_assign_substr], [al_ustr_assign_cstr]
@@ -545,10 +545,10 @@ See also: [al_ustr_assign_substr], [al_ustr_assign_cstr]
### API: al_ustr_set_chr
-Replace the code point beginning at byte offset `pos` with `c`.
-`pos` cannot be less than 0. If `pos` is past the end of `us1` then the space
-between the end of the string and `pos` will be padded with NUL (`'\0'`) bytes.
-If `pos` is not the start of a valid code point, that is an error and
+Replace the code point beginning at byte offset `start_pos` with `c`.
+`start_pos` cannot be less than 0. If `start_pos` is past the end of `us` then the space
+between the end of the string and `start_pos` will be padded with NUL (`'\0'`) bytes.
+If `start_pos` is not the start of a valid code point, that is an error and
the string will be unmodified.
On success, returns the number of bytes written, i.e. the offset to the
@@ -558,9 +558,9 @@ See also: [al_ustr_replace_range]
### API: al_ustr_replace_range
-Replace the part of `us1` in the byte interval \[start_pos, end_pos) with the
-contents of `us2`. `start_pos` cannot be less than 0. If `start_pos` is past
-the end of `us1` then the space between the end of the string and `start_pos`
+Replace the part of `us1` in the byte interval \[`start_pos1`, `end_pos1`) with the
+contents of `us2`. `start_pos1` cannot be less than 0. If `start_pos1` is past
+the end of `us1` then the space between the end of the string and `start_pos1`
will be padded with NUL (`'\0'`) bytes.
Use [al_ustr_offset] to find the byte offsets.
@@ -621,7 +621,7 @@ See also: [al_ustr_find_cset], [al_ustr_find_set_cstr]
### API: al_ustr_find_str
Find the first occurrence of string `needle` in `haystack`, beginning from byte
-offset `pos` (inclusive). Return the byte offset of the occurrence if it is
+offset `start_pos` (inclusive). Return the byte offset of the occurrence if it is
found, otherwise return -1.
See also: [al_ustr_find_cstr], [al_ustr_rfind_str], [al_ustr_find_replace]
diff --git a/docs/src/refman/video.txt b/docs/src/refman/video.txt
index b26ff84..7d0c54c 100644
--- a/docs/src/refman/video.txt
+++ b/docs/src/refman/video.txt
@@ -70,7 +70,7 @@ Returns the aspect ratio of the video. Videos often do not use square
pixels so you should always check the aspect ratio before displaying
video frames.
-Returns zero or negative value if the aspect ratio is unknown.
+Returns zero or a negative value if the aspect ratio is unknown.
Since: 5.1.0
@@ -89,7 +89,7 @@ Since: 5.1.0
## API: al_get_video_width
-Returns the number of pixel raw pixel columns in the video stream.
+Returns the number of raw pixel columns in the video stream.
Multiply this with the aspect ratio to get the true width.
Since: 5.1.0
--
1.9.1
--------------030703050803090309040902--