Rust bindings to the dos-like framework

Eduardo Pinho

Last update: Aug 25, 2022

Related tags

Overview

`dos-like` for Rust

This project provides access to Mattias Gustavsson's dos-like framework, so as to write DOS-like applications in Rust.

How to use

This crate is not a regular library. It defines a main function on its own. For the executable linking to work correctly, the main source file needs to declare no main and define an extern C function dosmain instead.

#![no_main]

#[no_mangle]
pub extern "C" fn dosmain() -> i32 {
    // your code here

    0
}

A utility macro is available as an alternative to declaring the function:

#![no_main]

dos_like_rs::dos_main! {
    // your code here
}

See the examples for a typical application structure, which are based on the original dos-like examples.

A C compiler needs to be available (uses cc). The dos-like framework is statically linked, just like in a C program.

Since the initiator is based on routines in C, this also means that panic unwinding will not work, so it is best to configure your project to abort on panic. In your Cargo.toml:

[profile.dev]
panic = "abort"

[profile.release]
panic = "abort"

Check out the dos-like README for additional requirements.

Cargo features

disable-screen-frame compiles dos-like so that the CRT screen frame around the viewport does not appear.

Platform support

These bindings have been tested on Linux and Windows. WebAssembly and Mac OS support is currently not guaranteed (but your assistance on this would be greatly appreciated!).

Building

When working on this project, ensure that the git submodule in dos-like-sys/dos-like was populated (either by cloning with --recurse-submodules or by calling git submodule update --init). Some of the examples do not work unless with this submodule checked out.

License and attribution notice

The Rust bindings are licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

The dos-like framework remains licensed as defined in the original LICENSE file.

Comments

Mouse functions

input::mouse_x() and input::mouse_y() underflow when the cursor is at the top or left edge of the virtual monitor.

It also seems that input::mouse_rel_x() and input::mouse_rel_y() always return 0 (at least on X11), and are also unsigned, which would cause wrong values for left/up movement.
bug

opened by Kapouett 2
Drawing functions should take signed positions

Drawing functions like line or draw_poly take u16 coordinates, breaking shapes that are partially off-screen. This behavior is not present in dos-like as it uses signed integer coordinates.

opened by Kapouett 1
Minor documentation improvements
add wait_vbl() in example which is typically called inside an app loop

clarify certain text functions that they only work in graphics mode

fix documentation of center_text_xy
opened by Enet4 0
Fix compilation under MacOS and make it easy to run the examples
This PR achieves two things:

it fixes compilation under x86-based MacOS (tested on MacOS 12.3.1, with dependencies installed according to the dos-like installation instructions)

it makes it easy to run the examples, by leveraging cargo. Simply cd examples/rotozoom && cargo run. Downside is that the example source code has been modified such that the examples search for their assets in a nested subdirectory of a parent directory (e.g. ../../dos-like-sys/dos-like/files/sound/soundcard.wav) which is arguably a little awkward.

Note that I have not verified that this does not break anything, and neither do I know if this works on ARM Macs. But "it works on my machine"!
opened by jorisvddonk 0
Use i32 in graphics coordinates

This changes all graphics functions to receive screen pixel coordinates as i32 instead of u16. Resolves #4.

In the process, I also clarified that some parameters are width and height (rectangle and bar), and fixed the functions draw_poly and fill_poly, which were just written incorrectly.
bug

opened by Enet4 0
Input key release support
update dos-like to the latest revision, which has support for key release events

add KeyEvent type

change read_keys so that it returns key events

add keyboard demo example

breaking change
opened by Enet4 0

Releases(v0.3.1)

v0.3.1(Jul 26, 2022)
Fixes and Enhancements

Fix compilation under MacOS (#7 @jorisvddonk)

Minor documentation improvements (#8)

Full Changelog: https://github.com/Enet4/dos-like-rs/compare/0.3.0...v0.3.1
Source code(tar.gz)
Source code(zip)
0.3.0(Mar 29, 2022)
What's Changed

swap_buffers was changed to no longer return a slice, so that it can be used without unsafe. For the function which also returns a slice, see swap_buffers_and_get. (#6)

Changed pixel coordinates to use i32 instead of u16. This also fixes draw_poly and fill_poly, which never really worked. (#5)

Fixed mouse functions to use i32 instead of u16. (#3 @Kapouett)

Full Changelog: https://github.com/Enet4/dos-like-rs/compare/0.2.3...0.3.0
Source code(tar.gz)
Source code(zip)
0.2.3(Mar 17, 2022)
Fixes

Added null pointer checks in create_sound, as passing invalid parameters returns a null pointer and attempting to use the Sound value could lead to undefined behavior. Instead, this function panics. try_create_sound was added, which returns an Option<_> instead.

Enhancements

Memory layout of resource types Sound, Music and Image were changed to take advantage of the fact that the raw pointer is never null.

Full Changelog: https://github.com/Enet4/dos-like-rs/compare/0.2.2...0.2.3
Source code(tar.gz)
Source code(zip)
0.2.2(Mar 17, 2022)
Fixes

Added null pointer checks in Music::create_mus. Attempting to use a Music value with a null pointer could lead to undefined behavior. Instead, this function panics if it could not load the music data from the slice.

Added Music::try_create_mus which does the same as above, but returns an Option<Music> instead (None if it could not load).

Enhancements

[dos-like-sys] Update dos-like revision from a676ea74 to 2bceb960 (2022-03-07).

Chores

Updated CI linux jobs to update packages before installing SDL2 and libGLEW (#1)

Full Changelog: https://github.com/Enet4/dos-like-rs/compare/0.2.1...0.2.2
Source code(tar.gz)
Source code(zip)
0.2.1(Mar 17, 2022)
Fixes

Adjusted dos-like-sys building process to skip compilation in docs.rs

Source code(tar.gz)
Source code(zip)
0.2.0(Mar 8, 2022)
New

All functions from the native dos-like API have now been covered in the high level crate!

Implementations were categorized in the following modules: video input, sound, and music.

Fixes and Enhancements

Significantly improved documentation.

Build script was tweaked to work on Windows.

Mac OS is untested; WebAssembly is not yet supported.

Reduced package size of dos-like-sys by excluding unneeded contents.

Full Changelog: https://github.com/Enet4/dos-like-rs/compare/0.1.0...0.2.0
Source code(tar.gz)
Source code(zip)
0.1.0(Mar 5, 2022)

Initial release, still very incomplete.
Source code(tar.gz)
Source code(zip)