diff options
author | 2022-09-02 08:55:16 +1000 | |
---|---|---|
committer | 2022-09-02 08:55:16 +1000 | |
commit | 051c380fd14040c83a0d5b919e6289e70fef9df8 (patch) | |
tree | e247a309f4d1c66c07803c02d67ac89837211bd1 /docs/source | |
parent | 67f129e31518a50a801413f732991972d2c3538a (diff) |
Patched up some gaps in functionality and fixed some bugs.
ui: Added some missing functionality:
* Added an option to copy input device IDs to the relevant menus.
* Added an item for setting the software lists files path (-hashpath) to
the folder setup menu.
* Allow pasting text from clipboard in most places that allow typing
(searching, entering filenames, entering barcodes).
* Changed the software selection menu heading to be a bit less
misleading.
* Made barcode menu less eager to rebuild itself unnecessarily, and
removed some confusing and apparently pointless code.
Exposed more Lua bindings:
* Added low-level palette objects.
* Added indexed bitmap types.
* Added a bitmap method for extracting pixels from a rectangular area as a
packed binary string.
* Changed screen device pixels method to return width and height in
addition to the pixels.
osd: Added some functionality and cleaned up a little:
* Added a function for copying text to the clipboard.
* Moved function for converting Windows error codes to standard error
conditions to winutil.cpp so it can be used from more places.
* Removed duplicate declaration of osd_get_clipboard_text and made the
function noexcept (including fixing implementations).
* Made macOS implementation of osd_get_clipboard_text skip the encoding
conversion if it finds UTF-8 text first.
* Changed the default -uimodekey setting so it doesn't lose the "not
shift" that stops the default from interfering with UI paste.
Various bug fixes:
* util/unicode.cpp: Fixed the version of utf8_from_uchar that returns
std::string blowing up on invalid codepoints.
* util/bitmap.h: Fixed wrapping constructors for indexed bitmaps taking
the wrong parameter type (nothing was using them before).
* util/bitmap.cpp: Fixed potential use-after-free issues with bitmap
palettes.
* emu/input.cpp, emu/inputdev.cpp: Log 1-based device numbers, matching
what's shown in the internal UI and used in tokens in CFG files.
* emu/emumem.cpp: Added the bank tag to a fatal error message where it
was missing.
docs: Reworked and expanded documentation on configuring stable
controller IDs.
For translators, the changes are quite minor:
* There's a menu item for copying a device ID to the clipboard, and
associated success/failure messages.
* There's the menu item for setting the software list file search path.
* One of the lines in the software selection menu heading has changes as
it could be interpreted as implying it showed a software list name.
Diffstat (limited to 'docs/source')
-rw-r--r-- | docs/source/advanced/ctrlr_config.rst | 31 | ||||
-rw-r--r-- | docs/source/advanced/devicemap.rst | 124 | ||||
-rw-r--r-- | docs/source/techspecs/luareference.rst | 296 | ||||
-rw-r--r-- | docs/source/usingmame/mamemenus.rst | 5 |
4 files changed, 415 insertions, 41 deletions
diff --git a/docs/source/advanced/ctrlr_config.rst b/docs/source/advanced/ctrlr_config.rst index 6fdeddc8a8a..9e284f7f945 100644 --- a/docs/source/advanced/ctrlr_config.rst +++ b/docs/source/advanced/ctrlr_config.rst @@ -228,3 +228,34 @@ Here’s an example that overrides defaults for 280-ZZZAP: This sets the controls to steer left and right to the K and J keys, respectively, and disables the toggle setting for the gear shift input. + + +.. _ctrlrcfg-mapdevice: + +Assigning input device numbers +------------------------------ + +Use ``mapdevice`` elements with ``device`` and ``controller`` attributes to +assign stable numbers to input devices. Note that all devices explicitly +configured in this way must be connected when MAME starts for this to work as +expected. + +Set the ``device`` attribute to the device ID of the input device, and set the +``controller`` attribute to the desired input device token (device type and +number). + +Here’s an example numbering two light guns and two XInput game controllers: + +.. code-block:: XML + + <system name="default"> + <input> + <mapdevice device="VID_D209&PID_1601" controller="GUNCODE_1" /> + <mapdevice device="VID_D209&PID_1602" controller="GUNCODE_2" /> + <mapdevice device="XInput Player 1" controller="JOYCODE_1" /> + <mapdevice device="XInput Player 2" controller="JOYCODE_2" /> + </input> + </system> + +MAME applies ``mapdevice`` elements found inside any applicable ``system`` +element. diff --git a/docs/source/advanced/devicemap.rst b/docs/source/advanced/devicemap.rst index 38dcc3a2641..aaf1450d4ab 100644 --- a/docs/source/advanced/devicemap.rst +++ b/docs/source/advanced/devicemap.rst @@ -1,26 +1,52 @@ +.. _devicemap: + Stable Controller IDs -=============================== +===================== + +By default, MAME does not assign stable numbers to input devices. For instance, +a game pad controller may be assigned to “Joy 1” initially, but after +restarting, the same game pad may be reassigned to “Joy 3”. + +The reason is that MAME assigns numbers to input devices in the based on +enumeration order. Factors that can cause this to change include disconnecting +and reconnecting USB or Bluetooth devices, changing ports/hubs, and even just +restarting the computer. Input device numbers can be quite unpredictable. -By default, the mapping between devices and controller IDs is not stable. For instance, a gamepad controller may be assigned to "Joy 1" initially, but after a reboot, it may get re-assigned to "Joy 3". +This is where the ``mapdevice`` configuration setting comes into the picture. +By adding this setting to a :ref:`controller configuration file <ctrlrcfg>`, you +can ensure that a given input device is always assigned the same number in MAME. -The reason is that MAME enumerates attached devices and assigns controller IDs based on the enumeration order. Factors that can cause controller IDs to change include plugging / unplugging USB devices, changing ports / hubs and even system reboots. -It is quite cumbersome to ensure that controller IDs are always correct. +Using mapdevice +--------------- -That's where the "mapdevice" configuration setting comes into the picture. This setting allows you to map a device id to a controller ID, ensuring that the specified device always maps to the same controller ID in MAME. +The ``mapdevice`` XML element is added to the ``input`` XML element in the +controller configuration file. It requires two attributes, ``device`` and +``controller``. Note that ``mapdevice`` elements only take effect in the +controller configuration file (set using the :ref:`-ctrlr option +<mame-commandline-ctrlr>`) – they are ignored in system configuration files and +the default configuration file. -Usage of mapdevice ------------------- -The "mapdevice" xml element is specified under the input xml element in the controller configuration file. It requires two attributes, "device" and "controller". -NOTE: This setting only take effect when added to the **ctrlr** config file. +The ``device`` attribute specifies the device ID of the input device to match. +It may also be a substring of the device ID. To obtain the device ID for an +input device, select it in the :ref:`menus-inputdevices`, and then select **Copy +Device ID**. The device ID will be copied to the clipboard. You can also see +input device IDs by turning on verbose logging (more on this later). The format +of device IDs depends the type of device, selected input provider module and +operating system. Your input device IDs may look very different to the examples +here. -The "device" attribute specifies the id of the device to match. It may also be a substring of the id. To see the list of available devices, enable verbose output and available devices will then be listed to the console at startup (more on this below). +The ``controller`` attribute specifies the input token for the input device type +(i.e. ``JOYCODE``, ``GUNCODE``, ``MOUSECODE``) and number to assign to the +device, separated by an underscore. Numbering starts from 1. For example the +token for the first joystick device will be ``JOYCODE_1``, the second will be +``JOYCODE_2``, and so on. -The "controller" attribute specifies the MAME controller ID. It is made up of a controller class (i.e. ``JOYCODE``, ``GUNCODE``, ``MOUSECODE``) and controller index. For example: ``JOYCODE_1``. Example ------- -Here's an example: + +Here’s an example: | <mameconfig version="10"> | <system name="default"> @@ -40,37 +66,71 @@ Here's an example: In the above example, we have four device mappings specified: -The first two mapdevice entries map player 1 and 2 lightguns to Gun 1 and Gun 2, respectively. We use a substring of the full raw device names to match each devices. Note that, since this is XML, we needed to escape the ``&`` using ``&``. +* The first two ``mapdevice`` elements map player 1 and 2 light guns to Gun 1 + and Gun 2, respectively. We use a substring of the full device IDs to match + each devices. Note that, since this is XML, we needed to escape the + ampersands (``&``) as ``&``. +* The last two ``mapdevices`` elements map player 1 and player 2 gamepad + controllers to Joy 1 and Joy 2, respectively. In this case, these are XInput + game controllers. -The last two mapdevices entries map player 1 and player 2 gamepad controllers to Joy 1 and Joy 2, respectively. In this case, these are XInput devices. Listing Available Devices ------------------------- -How did we obtain the device id's in the above example? Easy! -Run MAME with -v parameter to enable verbose output. It will then list available devices include the corresponding "device id" to the console. +There are two ways to obtain device IDs: by copying them from the +:ref:`menus-inputdevices`, or by :ref:`turning on verbose logging +<mame-commandline-verbose>` and finding the messages logged when input devices +are added. + +To reach the Input Devices menu from the system selection menu, select **General +Settings**, and the select **Input Devices**. To reach the input devices menu +from the :ref:`main menu <menus-main>`, select **Input Settings**, then select +**Input Devices**. From the Input Devices menu, select a device, then select +**Copy Device ID** to copy its device ID to the clipboard. + +To use verbose logging, run MAME with the ``-v`` or ``-verbose`` option on the +command line. Search the output for messages starting with “Input: Adding…” +that show recognised input devices and their respective IDs. Here an example: -| Input: Adding Gun #0: -| Input: Adding Gun #1: -| Input: Adding Gun #2: HID-compliant mouse (**device id: \\?\HID#VID_045E&PID_0053#7&18297dcb&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) -| Input: Adding Gun #3: HID-compliant mouse (**device id: \\?\HID#IrDeviceV2&Col08#2&2818a073&0&0007#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) -| Input: Adding Gun #4: HID-compliant mouse (**device id: \\?\HID#VID_D209&PID_1602&MI_02#8&389ab7f3&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) -| Input: Adding Gun #5: HID-compliant mouse (**device id: \\?\HID#VID_D209&PID_1601&MI_02#9&375eebb1&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) -| Input: Adding Gun #6: HID-compliant mouse (**device id: \\?\HID#VID_1241&PID_1111#8&198f3adc&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) +| Input: Adding lightgun #1: +| Input: Adding lightgun #2: +| Input: Adding lightgun #3: HID-compliant mouse (**device id: \\\\?\\HID#VID_045E&PID_0053#7&18297dcb&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) +| Input: Adding lightgun #4: HID-compliant mouse (**device id: \\\\?\\HID#IrDeviceV2&Col08#2&2818a073&0&0007#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) +| Input: Adding lightgun #5: HID-compliant mouse (**device id: \\\\?\\HID#VID_D209&PID_1602&MI_02#8&389ab7f3&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) +| Input: Adding lightgun #6: HID-compliant mouse (**device id: \\\\?\\HID#VID_D209&PID_1601&MI_02#9&375eebb1&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) +| Input: Adding lightgun #7: HID-compliant mouse (**device id: \\\\?\\HID#VID_1241&PID_1111#8&198f3adc&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}**) | Skipping DirectInput for XInput compatible joystick Controller (XBOX 360 For Windows). -| Input: Adding Joy #0: ATRAK Device #1 (**device id: ATRAK Device #1**) +| Input: Adding joystick #1: ATRAK Device #1 (**device id: ATRAK Device #1**) | Skipping DirectInput for XInput compatible joystick Controller (XBOX 360 For Windows). -| Input: Adding Joy #1: ATRAK Device #2 (**device id: ATRAK Device #2**) -| Input: Adding Joy #2: XInput Player 1 (**device id: XInput Player 1**) -| Input: Adding Joy #3: XInput Player 2 (**device id: XInput Player 2**) +| Input: Adding joystick #2: ATRAK Device #2 (**device id: ATRAK Device #2**) +| Input: Adding joystick #3: XInput Player 1 (**device id: XInput Player 1**) +| Input: Adding joystick #4: XInput Player 2 (**device id: XInput Player 2**) | -Furthermore, when devices are mapped using mapdevice, you'll see that in the verbose logging too, such as: +Furthermore, when devices are reassigned using ``mapdevice`` elements in the +controller configuration file, you’ll see that in the verbose log output, too, +such as: -| Input: Remapped Gun #0: HID-compliant mouse (device id: \\?\HID#VID_D209&PID_1601&MI_02#9&375eebb1&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}) -| Input: Remapped Gun #1: HID-compliant mouse (device id: \\?\HID#VID_D209&PID_1602&MI_02#8&389ab7f3&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}) -| Input: Remapped Joy #0: XInput Player 1 (device id: XInput Player 1) -| Input: Remapped Joy #1: XInput Player 2 (device id: XInput Player 2) +| Input: Remapped lightgun #1: HID-compliant mouse (device id: \\\\?\\HID#VID_D209&PID_1601&MI_02#9&375eebb1&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}) +| Input: Remapped lightgun #2: HID-compliant mouse (device id: \\\\?\\HID#VID_D209&PID_1602&MI_02#8&389ab7f3&0&0000#{378de44c-56ef-11d1-bc8c-00a0c91405dd}) +| Input: Remapped joystick #1: XInput Player 1 (device id: XInput Player 1) +| Input: Remapped joystick #2: XInput Player 2 (device id: XInput Player 2) | + +Note that the devices numbers in the verbose log output are zero-based, while +the device numbers shown in MAME’s user interface and set in configuration files + + +Limitations +----------- + +You can only assign stable numbers to devices if MAME receives stable, unique +device IDs from the input device provider and operating system. This is not +always the case. For example the SDL joystick provider is not capable of +providing unique IDs for many USB game controllers. + +If not all configured devices are connected when MAME starts, the devices that +are connected may not be numbered as expected. diff --git a/docs/source/techspecs/luareference.rst b/docs/source/techspecs/luareference.rst index b1d4334e9fb..206202df68a 100644 --- a/docs/source/techspecs/luareference.rst +++ b/docs/source/techspecs/luareference.rst @@ -870,8 +870,8 @@ Palette device Wraps MAME’s ``device_palette_interface`` class, which represents a device that translates pen values to colours. -Colours are in alpha/red/green/blue (ARGB) format. Channel values are in the -range 0 (transparent or off) to 255 (opaque or full intensity), inclusive. +Colours are represented in alpha/red/green/blue (ARGB) format. Channel values +range from 0 (transparent or off) to 255 (opaque or full intensity), inclusive. Colour channel values are not pre-multiplied by the alpha value. Channel values are packed into the bytes of 32-bit unsigned integers, in the order alpha, red, green, blue from most-significant to least-significant byte. @@ -931,6 +931,9 @@ palette:set_shadow_mode(mode) Properties ^^^^^^^^^^ +palette.palette (read-only) + The underlying :ref:`palette <luareference-render-palette>` managed by the + device. palette.entries (read-only) The number of colour entries in the palette. palette.indirect_entries (read-only) @@ -1001,10 +1004,12 @@ screen:pixel(x, y) packed into a 32-bit integer. Returns zero (0) if the specified point is outside the visible area. screen:pixels() - Returns all visible pixels as 32-bit integers packed into a binary string in - host Endian order. Pixels are organised in row-major order, from left to - right then top to bottom. Pixels values are either palette indices or - colours in RGB format packed into 32-bit integers. + Returns all visible pixels, the visible area width and visible area height. + + Pixels are returned as 32-bit integers packed into a binary string in host + Endian order. Pixels are organised in row-major order, from left to right + then top to bottom. Pixels values are either palette indices or colours in + RGB format packed into 32-bit integers. screen:draw_box(left, top, right, bottom, [line], [fill]) Draws an outlined rectangle with edges at the specified positions. @@ -2699,12 +2704,140 @@ color.b (read/write) Blue channel value, in the range of zero (0, off) to one (1, full intensity). +.. _luareference-render-palette: + +Palette +~~~~~~~ + +Wraps MAME’s ``palette_t`` class, which represents a table of colours that can +be looked up by zero-based index. Palettes always contain additional special +entries for black and white. + +Each colour has an associated contrast adjustment value. Each adjustment group +has associated brightness and contrast adjustment values. The palette also has +overall brightness, contrast and gamma adjustment values. + +Colours are represented in alpha/red/green/blue (ARGB) format. Channel values +range from 0 (transparent or off) to 255 (opaque or full intensity), inclusive. +Colour channel values are not pre-multiplied by the alpha value. Channel values +are packed into the bytes of 32-bit unsigned integers, in the order alpha, red, +green, blue from most-significant to least-significant byte. + +Instantiation +^^^^^^^^^^^^^ + +emu.palette(colors, [groups]) + Creates a palette with the specified number of colours and + brightness/contrast adjustment groups. The number of colour groups defaults + to one if not specified. Colours are initialised to black, brightness + adjustment is initialised to 0.0, contrast adjustment initialised to 1.0, + and gamma adjustment is initialised to 1.0. + +Methods +^^^^^^^ + +palette:entry_color(index) + Gets the colour at the specified zero-based index. + + Index values range from zero to the number of colours in the palette minus + one. Returns black if the index is greater than or equal to the number of + colours in the palette. +palette:entry_contrast(index) + Gets the contrast adjustment for the colour at the specified zero-based + index. This is a floating-point number. + + Index values range from zero to the number of colours in the palette minus + one. Returns 1.0 if the index is greater than or equal to the number of + colours in the palette. +palette:entry_adjusted_color(index, [group]) + Gets a colour with brightness, contrast and gamma adjustments applied. + + If the group is specified, colour index values range from zero to the number + of colours in the palette minus one, and group values range from zero to the + number of adjustment groups in the palette minus one. + + If the group is not specified, index values range from zero to the number of + colours multiplied by the number of adjustment groups plus one. Index + values may be calculated by multiplying the zero-based group index by the + number of colours in the palette, and adding the zero-based colour index. + The last two index values correspond to the special entries for black and + white, respectively. + + Returns black if the specified combination of index and adjustment group is + invalid. +palette:entry_set_color(index, color) + Sets the colour at the specified zero-based index. The colour may be + specified as a single packed 32-bit value; or as individual red, green and + blue channel values, in that order. + + Index values range from zero to the number of colours in the palette minus + one. Raises an error if the index value is invalid. +palette:entry_set_red_level(index, level) + Sets the red channel value of the colour at the specified zero-based index. + Other channel values are not affected. + + Index values range from zero to the number of colours in the palette minus + one. Raises an error if the index value is invalid. +palette:entry_set_green_level(index, level) + Sets the green channel value of the colour at the specified zero-based + index. Other channel values are not affected. + + Index values range from zero to the number of colours in the palette minus + one. Raises an error if the index value is invalid. +palette:entry_set_blue_level(index, level) + Sets the blue channel value of the colour at the specified zero-based index. + Other channel values are not affected. + + Index values range from zero to the number of colours in the palette minus + one. Raises an error if the index value is invalid. +palette:entry_set_contrast(index, level) + Sets the contrast adjustment value for the colour at the specified + zero-based index. This must be a floating-point number. + + Index values range from zero to the number of colours in the palette minus + one. Raises an error if the index value is invalid. +palette:group_set_brightness(group, brightness) + Sets the brightness adjustment value for the adjustment group at the + specified zero-based index. This must be a floating-point number. + + Group values range from zero to the number of adjustment groups in the + palette minus one. Raises an error if the index value is invalid. +palette:group_set_contrast(group, contrast) + Sets the contrast adjustment value for the adjustment group at the specified + zero-based index. This must be a floating-point number. + + Group values range from zero to the number of adjustment groups in the + palette minus one. Raises an error if the index value is invalid. + +Properties +^^^^^^^^^^ + +palette.colors (read-only) + The number of colour entries in each group of colours in the palette. +palette.groups (read-only) + The number of groups of colours in the palette. +palette.max_index (read-only) + The number of valid colour indices in the palette. +palette.black_entry (read-only) + The index of the special entry for the colour black. +palette.white_entry (read-only) + The index of the special entry for the colour white. +palette.brightness (write-only) + The overall brightness adjustment for the palette. This is a floating-point + number. +palette.contrast (write-only) + The overall contrast adjustment for the palette. This is a floating-point + number. +palette.gamma (write-only) + The overall gamma adjustment for the palette. This is a floating-point + number. + .. _luareference-render-bitmap: Bitmap ~~~~~~ -Wraps implementation of MAME’s ``bitmap_t`` and ``bitmap_specific`` classes, +Wraps implementations of MAME’s ``bitmap_t`` and ``bitmap_specific`` classes, which represent two-dimensional bitmaps stored in row-major order. Pixel coordinates are zero-based, increasing to the right and down. Several pixel formats are supported. @@ -2712,6 +2845,70 @@ formats are supported. Instantiation ^^^^^^^^^^^^^ +emu.bitmap_ind8(palette, [width, height], [xslop, yslop]) + Creates an 8-bit indexed bitmap. Each pixel is a zero-based, unsigned 8-bit + index into a :ref:`palette <luareference-render-palette>`. + + If no width and height are specified, they are assumed to be zero. If the + width is specified, the height must also be specified. The X and Y slop + values set the amount of extra storage in pixels to reserve at the + left/right of each row and top/bottom of each column, respectively. If an X + slop value is specified, a Y slop value must be specified as well. If no X + and Y slop values are specified, they are assumed to be zero (the storage + will be sized to fit the bitmap content). If the width and/or height is + less than or equal to zero, no storage will be allocated, irrespective of + the X and Y slop values, and the width and height of the bitmap will both be + set to zero. + + The initial clipping rectangle is set to the entirety of the bitmap. +emu.bitmap_ind16(palette, [width, height], [xslop, yslop]) + Creates a 16-bit indexed bitmap. Each pixel is a zero-based, unsigned + 16-bit index into a :ref:`palette <luareference-render-palette>`. + + If no width and height are specified, they are assumed to be zero. If the + width is specified, the height must also be specified. The X and Y slop + values set the amount of extra storage in pixels to reserve at the + left/right of each row and top/bottom of each column, respectively. If an X + slop value is specified, a Y slop value must be specified as well. If no X + and Y slop values are specified, they are assumed to be zero (the storage + will be sized to fit the bitmap content). If the width and/or height is + less than or equal to zero, no storage will be allocated, irrespective of + the X and Y slop values, and the width and height of the bitmap will both be + set to zero. + + The initial clipping rectangle is set to the entirety of the bitmap. +emu.bitmap_ind32(palette, [width, height], [xslop, yslop]) + Creates a 32-bit indexed bitmap. Each pixel is a zero-based, unsigned + 32-bit index into a :ref:`palette <luareference-render-palette>`. + + If no width and height are specified, they are assumed to be zero. If the + width is specified, the height must also be specified. The X and Y slop + values set the amount of extra storage in pixels to reserve at the + left/right of each row and top/bottom of each column, respectively. If an X + slop value is specified, a Y slop value must be specified as well. If no X + and Y slop values are specified, they are assumed to be zero (the storage + will be sized to fit the bitmap content). If the width and/or height is + less than or equal to zero, no storage will be allocated, irrespective of + the X and Y slop values, and the width and height of the bitmap will both be + set to zero. + + The initial clipping rectangle is set to the entirety of the bitmap. +emu.bitmap_ind64(palette, [width, height], [xslop, yslop]) + Creates a 64-bit indexed bitmap. Each pixel is a zero-based, unsigned + 64-bit index into a :ref:`palette <luareference-render-palette>`. + + If no width and height are specified, they are assumed to be zero. If the + width is specified, the height must also be specified. The X and Y slop + values set the amount of extra storage in pixels to reserve at the + left/right of each row and top/bottom of each column, respectively. If an X + slop value is specified, a Y slop value must be specified as well. If no X + and Y slop values are specified, they are assumed to be zero (the storage + will be sized to fit the bitmap content). If the width and/or height is + less than or equal to zero, no storage will be allocated, irrespective of + the X and Y slop values, and the width and height of the bitmap will both be + set to zero. + + The initial clipping rectangle is set to the entirety of the bitmap. emu.bitmap_yuy16([width, height], [xslop], yslop]) Creates a Y'CbCr format bitmap with 4:2:2 chroma subsampling (horizontal pairs of pixels have individual luma values but share chroma values). Each @@ -2775,6 +2972,70 @@ emu.bitmap_argb32([width, height], [xslop, yslop]) set to zero. The initial clipping rectangle is set to the entirety of the bitmap. +emu.bitmap_ind8(source, [x0, y0, x1, y1]) + Creates an 8-bit indexed bitmap representing a view of a portion of an + existing bitmap. The initial clipping rectangle is set to the bounds of the + view. The source bitmap will be locked, preventing resizing and + reallocation. + + If no coordinates are specified, the new bitmap will represent a view of the + source bitmap’s current clipping rectangle. If coordinates are specified, + the new bitmap will represent a view of the rectangle with top left corner + at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap. + Coordinates are in units of pixels. The bottom right coordinates are + inclusive. + + The source bitmap must be owned by the Lua script and must use the 8-bit + indexed format. Raises an error if coordinates are specified representing a + rectangle not fully contained within the source bitmap’s clipping rectangle. +emu.bitmap_ind16(source, [x0, y0, x1, y1]) + Creates a 16-bit indexed bitmap representing a view of a portion of an + existing bitmap. The initial clipping rectangle is set to the bounds of the + view. The source bitmap will be locked, preventing resizing and + reallocation. + + If no coordinates are specified, the new bitmap will represent a view of the + source bitmap’s current clipping rectangle. If coordinates are specified, + the new bitmap will represent a view of the rectangle with top left corner + at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap. + Coordinates are in units of pixels. The bottom right coordinates are + inclusive. + + The source bitmap must be owned by the Lua script and must use the 16-bit + indexed format. Raises an error if coordinates are specified representing a + rectangle not fully contained within the source bitmap’s clipping rectangle. +emu.bitmap_ind32(source, [x0, y0, x1, y1]) + Creates a 32-bit indexed bitmap representing a view of a portion of an + existing bitmap. The initial clipping rectangle is set to the bounds of the + view. The source bitmap will be locked, preventing resizing and + reallocation. + + If no coordinates are specified, the new bitmap will represent a view of the + source bitmap’s current clipping rectangle. If coordinates are specified, + the new bitmap will represent a view of the rectangle with top left corner + at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap. + Coordinates are in units of pixels. The bottom right coordinates are + inclusive. + + The source bitmap must be owned by the Lua script and must use the 32-bit + indexed format. Raises an error if coordinates are specified representing a + rectangle not fully contained within the source bitmap’s clipping rectangle. +emu.bitmap_ind64(source, [x0, y0, x1, y1]) + Creates a 64-bit indexed bitmap representing a view of a portion of an + existing bitmap. The initial clipping rectangle is set to the bounds of the + view. The source bitmap will be locked, preventing resizing and + reallocation. + + If no coordinates are specified, the new bitmap will represent a view of the + source bitmap’s current clipping rectangle. If coordinates are specified, + the new bitmap will represent a view of the rectangle with top left corner + at (x0, y0) and bottom right corner at (x1, y1) in the source bitmap. + Coordinates are in units of pixels. The bottom right coordinates are + inclusive. + + The source bitmap must be owned by the Lua script and must use the 64-bit + indexed format. Raises an error if coordinates are specified representing a + rectangle not fully contained within the source bitmap’s clipping rectangle. emu.bitmap_yuy16(source, [x0, y0, x1, y1]) Creates a Y'CbCr format bitmap with 4:2:2 chroma subsampling representing a view of a portion of an existing bitmap. The initial clipping rectangle is @@ -2827,6 +3088,10 @@ emu.bitmap_argb32(source, [x0, y0, x1, y1]) Methods ^^^^^^^ +bitmap:cliprect() + Returns the left, top, right and bottom coordinates of the bitmap’s clipping + rectangle. Coordinates are in units of pixels; the bottom and right + coordinates are inclusive. bitmap:reset() Sets the width and height to zero, and frees the pixel storage if the bitmap owns its own storage, or releases the source bitmap if the it represents a @@ -2898,6 +3163,17 @@ bitmap:wrap(source, [x0, y0, x1, y1]) bitmap:pix(x, y) Returns the colour value of the pixel at the specified location. Coordinates are zero-based in units of pixels. +bitmap:pixels([x0, y0, x1, y1]) + Returns the pixels, width and height of the portion of the bitmap with top + left corner at (x0, y0) and bottom right corner at (x1, y1). Coordinates + are in units of pixels. The bottom right coordinates are inclusive. If + coordinates are not specified, the bitmap’s clipping rectangle is used. + + Pixels are returned packed into a binary string in host Endian order. + Pixels are organised in row-major order, from left to right then top to + bottom. The size and format of the pixel values depends on the format of + the bitmap. Raises an error if coordinates are specified representing a + rectangle not fully contained within the bitmap’s clipping rectangle. bitmap:fill(color, [x0, y0, x1, y1]) Fills a portion of the bitmap with the specified colour value. If coordinates are not specified, the clipping rectangle is filled; if @@ -2916,6 +3192,10 @@ bitmap:plot_box(x, y, width, height, color) Properties ^^^^^^^^^^ +bitmap.palette (read/write) + The :ref:`palette <luareference-render-palette>` used to translate pixel + values to colours. Only applicable for bitmaps that use indexed pixel + formats. bitmap.width (read-only) Width of the bitmap in pixels. bitmap.height (read-only) @@ -2989,7 +3269,7 @@ Methods render:texture_alloc(bitmap) Creates a :ref:`render texture <luareference-render-texture>` based on a :ref:`bitmap <luareference-render-bitmap>`. The bitmap must be owned by the - Lua script, and must use the Y'CbCr, RGB or ARGB format. The bitmap’s + Lua script, and must use the Y'CbCr, RGB or ARGB pixel format. The bitmap’s storage will be locked, preventing resizing and reallocation. Render textures must be freed before the emulation session ends. diff --git a/docs/source/usingmame/mamemenus.rst b/docs/source/usingmame/mamemenus.rst index 297f3870a6d..819965f4964 100644 --- a/docs/source/usingmame/mamemenus.rst +++ b/docs/source/usingmame/mamemenus.rst @@ -280,4 +280,7 @@ each control is displayed on the left and its current state is shown on the right. When an analog axis control is highlighted, its state is also shown in graphical form below the menu. Digital control states are either zero (inactive) or one (active). Analog axis input states range from -65,536 to -65,536 with the neutral position at zero. +65,536 with the neutral position at zero. You can also select **Copy Device +ID** to copy the device’s ID to the clipboard. This is useful for setting up +:ref:`stable controller IDs <devicemap>` in :ref:`controller configuration files +<ctrlrcfg>`. |