Merge commit '0132cbcf33a3ae568c361751a42ff53c41e08f68' as 'external/pure_doom/PureDOOM'
This commit is contained in:
266
external/pure_doom/PureDOOM/README.md
vendored
Normal file
266
external/pure_doom/PureDOOM/README.md
vendored
Normal file
@@ -0,0 +1,266 @@
|
||||
|
||||
|
||||
# Pure DOOM
|
||||
Header only, no dependencies DOOM source port. Designed to run on any devices.
|
||||
|
||||
Primarily of interest to people that want to "run DOOM on their microwave".
|
||||
|
||||
## LICENSE
|
||||
See end of file for license information.
|
||||
|
||||
## Main Features:
|
||||
- Single header
|
||||
- Pure-C, No includes dependencies: no stdlib, stdio, etc.
|
||||
- Supports 32 bits and 64 bits
|
||||
|
||||
## Other Features:
|
||||
- Menu option to disable mouse move Forward/Backward
|
||||
- Crosshair option
|
||||
- Always-Run option
|
||||
|
||||
## TODOs
|
||||
- Custom resolution
|
||||
- Remove exit and have update return 0 on quit. Add doom_get_exit_code()
|
||||
- Implement Sockets and Multiplayer
|
||||
- Print message when discovered a secret
|
||||
|
||||
## Cool TODOs to have
|
||||
- Rebindable keys
|
||||
- Unlocked FPS
|
||||
- Release mouse in menus and use it for clicking
|
||||
- Wipe screen freezes menu
|
||||
- Use floats instead of fixed_t
|
||||
- French and german
|
||||
- Full color mode (Don't use COLORMAPS, use full 24 bits RGB)
|
||||
|
||||
## Usage
|
||||
Call `doom_init()`, then call `doom_update()` every frame, or as often as you can. This will run DOOM, without any video, inputs, sounds or music.
|
||||
|
||||
```c
|
||||
#define DOOM_IMPLEMENTATION
|
||||
#include "PureDOOM.h"
|
||||
|
||||
int main(int argc, char** argv)
|
||||
{
|
||||
doom_init(argc, argv, 0);
|
||||
while (true)
|
||||
{
|
||||
doom_update();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Enable features
|
||||
Most standard headers are available on most platforms. Define these preprocessors to toggle these features.
|
||||
|
||||
- `DOOM_IMPLEMENT_PRINT`. Allows printf, requires `<stdio.h>`
|
||||
- `DOOM_IMPLEMENT_MALLOC`. Allows malloc/free, requires `<stdlib.h>`
|
||||
- `DOOM_IMPLEMENT_FILE_IO`. Allows FILE, requires `<stdio.h>`
|
||||
- `DOOM_IMPLEMENT_GETTIME`. Requires `<sys/time.h>` or `<winsock.h>`
|
||||
- `DOOM_IMPLEMENT_EXIT`. Allows exit(), requires `<stdlib.h>`
|
||||
- `DOOM_IMPLEMENT_GETENV`. Requires `<stdlib.h>`
|
||||
|
||||
If your microwave doesn't have these headers, you can override their default implementations:
|
||||
|
||||
```c
|
||||
void doom_set_print(doom_print_fn print_fn);
|
||||
void doom_set_malloc(doom_malloc_fn malloc_fn, doom_free_fn free_fn);
|
||||
void doom_set_file_io(doom_open_fn open_fn,
|
||||
doom_close_fn close_fn,
|
||||
doom_read_fn read_fn,
|
||||
doom_write_fn write_fn,
|
||||
doom_seek_fn seek_fn,
|
||||
doom_tell_fn tell_fn,
|
||||
doom_eof_fn eof_fn);
|
||||
void doom_set_gettime(doom_gettime_fn gettime_fn);
|
||||
void doom_set_exit(doom_exit_fn exit_fn);
|
||||
void doom_set_getenv(doom_getenv_fn getenv_fn);
|
||||
```
|
||||
|
||||
## Video
|
||||
Every frame, after having called `doom_update()`, you can get the screen pixels with `doom_get_framebuffer` and display it as you please.
|
||||
|
||||
```c
|
||||
while (true)
|
||||
{
|
||||
doom_update();
|
||||
uint8_t* framebuffer = doom_get_framebuffer(4 /* RGBA */);
|
||||
// ... Display framebuffer
|
||||
}
|
||||
```
|
||||
|
||||
## Inputs
|
||||
When you receive input events from your microwave touch pad, simply call one of the DOOM input events:
|
||||
|
||||
```c
|
||||
void doom_key_down(doom_key_t key);
|
||||
void doom_key_up(doom_key_t key);
|
||||
void doom_button_down(doom_button_t button);
|
||||
void doom_button_up(doom_button_t button);
|
||||
void doom_mouse_move(int delta_x, int delta_y);
|
||||
```
|
||||
|
||||
## Sounds
|
||||
Create a sound thread that outputs at 11025hz (`DOOM_SAMPLERATE`), 512 samples, 16 bits, stereo. Then in your sound callback, call `doom_get_sound_buffer` to update and get the current DOOM's sound output. Make sure to add synchronization primitives around this and `doom_update` if your sound loop is in a thread.
|
||||
|
||||
Here is a quick example using SDL audio callback:
|
||||
```c
|
||||
void sdl_audio_callback(void* userdata, Uint8* stream, int len)
|
||||
{
|
||||
SDL_LockAudio();
|
||||
int16_t* buffer = doom_get_sound_buffer(len);
|
||||
SDL_UnlockAudio();
|
||||
|
||||
memcpy(stream, buffer, len);
|
||||
}
|
||||
```
|
||||
|
||||
You can use different bitrate, but make sure to resample because DOOM will always be 11025hz, 512 samples, 16 bits, 2 channels. For a total for 2048 bytes per buffer.
|
||||
|
||||
## Music
|
||||
Set a timer in your application that runs at 140hz. In the timer's callback, tick DOOM's music as long as there are MIDI messages to send.
|
||||
|
||||
Here is an example using Window's MultiMedia to play MIDI events, using an SDL timer.
|
||||
```c
|
||||
Uint32 tick_music(Uint32 interval, void *param)
|
||||
{
|
||||
uint32_t midi_msg;
|
||||
|
||||
SDL_LockAudio();
|
||||
|
||||
while (midi_msg = doom_tick_midi())
|
||||
midiOutShortMsg(midi_out_handle, midi_msg);
|
||||
|
||||
SDL_UnlockAudio();
|
||||
|
||||
return 1000 / DOOM_MIDI_RATE /* 140 */;
|
||||
}
|
||||
```
|
||||
|
||||
## Change default settings
|
||||
Default input setup in DOOM's source is not modern. It uses Arrows to move and `','` / `'.'` to strafe. You can call `doom_set_default_int` and `doom_set_default_str` to change them:
|
||||
|
||||
```c
|
||||
// Change default bindings to modern mapping
|
||||
doom_set_default_int("key_up", DOOM_KEY_W);
|
||||
doom_set_default_int("key_down", DOOM_KEY_S);
|
||||
doom_set_default_int("key_strafeleft", DOOM_KEY_A);
|
||||
doom_set_default_int("key_straferight", DOOM_KEY_D);
|
||||
doom_set_default_int("key_use", DOOM_KEY_E);
|
||||
doom_set_default_int("mouse_move", 0); // Mouse will not move forward
|
||||
```
|
||||
|
||||
Refer to the defaults in `m_misc.cpp` for the complete list.
|
||||
|
||||
## Working SDL Example
|
||||
See the file `src/sdl_example.c` for a complete SDL example.
|
||||
|
||||
# DOOM LICENSE
|
||||
```
|
||||
LIMITED USE SOFTWARE LICENSE AGREEMENT
|
||||
|
||||
This Limited Use Software License Agreement (the "Agreement")
|
||||
is a legal agreement between you, the end-user, and Id Software, Inc.
|
||||
("ID"). By downloading or purchasing the software material, which
|
||||
includes source code (the "Source Code"), artwork data, music and
|
||||
software tools (collectively, the "Software"), you are agreeing to
|
||||
be bound by the terms of this Agreement. If you do not agree to the
|
||||
terms of this Agreement, promptly destroy the Software you may have
|
||||
downloaded or copied.
|
||||
|
||||
ID SOFTWARE LICENSE
|
||||
|
||||
1. Grant of License. ID grants to you the right to use the
|
||||
Software. You have no ownership or proprietary rights in or to the
|
||||
Software, or the Trademark. For purposes of this section, "use" means
|
||||
loading the Software into RAM, as well as installation on a hard disk
|
||||
or other storage device. The Software, together with any archive copy
|
||||
thereof, shall be destroyed when no longer used in accordance with
|
||||
this Agreement, or when the right to use the Software is terminated.
|
||||
You agree that the Software will not be shipped, transferred or
|
||||
exported into any country in violation of the U.S. Export
|
||||
Administration Act (or any other law governing such matters) and that
|
||||
you will not utilize, in any other manner, the Software in violation
|
||||
of any applicable law.
|
||||
|
||||
2. Permitted Uses. For educational purposes only, you, the
|
||||
end-user, may use portions of the Source Code, such as particular
|
||||
routines, to develop your own software, but may not duplicate the
|
||||
Source Code, except as noted in paragraph 4. The limited right
|
||||
referenced in the preceding sentence is hereinafter referred to as
|
||||
"Educational Use." By so exercising the Educational Use right you
|
||||
shall not obtain any ownership, copyright, proprietary or other
|
||||
interest in or to the Source Code, or any portion of the Source
|
||||
Code. You may dispose of your own software in your sole discretion.
|
||||
With the exception of the Educational Use right, you may not
|
||||
otherwise use the Software, or an portion of the Software, which
|
||||
includes the Source Code, for commercial gain.
|
||||
|
||||
3. Prohibited Uses: Under no circumstances shall you, the
|
||||
end-user, be permitted, allowed or authorized to commercially exploit
|
||||
the Software. Neither you nor anyone at your direction shall do any
|
||||
of the following acts with regard to the Software, or any portion
|
||||
thereof:
|
||||
|
||||
Rent;
|
||||
|
||||
Sell;
|
||||
|
||||
Lease;
|
||||
|
||||
Offer on a pay-per-play basis;
|
||||
|
||||
Distribute for money or any other consideration; or
|
||||
|
||||
In any other manner and through any medium whatsoever
|
||||
commercially exploit or use for any commercial purpose.
|
||||
|
||||
Notwithstanding the foregoing prohibitions, you may commercially
|
||||
exploit the software you develop by exercising the Educational Use
|
||||
right, referenced in paragraph 2. hereinabove.
|
||||
|
||||
4. Copyright. The Software and all copyrights related thereto
|
||||
(including all characters and other images generated by the Software
|
||||
or depicted in the Software) are owned by ID and is protected by
|
||||
United States copyright laws and international treaty provisions.
|
||||
Id shall retain exclusive ownership and copyright in and to the
|
||||
Software and all portions of the Software and you shall have no
|
||||
ownership or other proprietary interest in such materials. You must
|
||||
treat the Software like any other copyrighted material. You may not
|
||||
otherwise reproduce, copy or disclose to others, in whole or in any
|
||||
part, the Software. You may not copy the written materials
|
||||
accompanying the Software. You agree to use your best efforts to
|
||||
see that any user of the Software licensed hereunder complies with
|
||||
this Agreement.
|
||||
|
||||
5. NO WARRANTIES. ID DISCLAIMS ALL WARRANTIES, BOTH EXPRESS
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
|
||||
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE WITH RESPECT
|
||||
TO THE SOFTWARE. THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL
|
||||
RIGHTS. YOU MAY HAVE OTHER RIGHTS WHICH VARY FROM JURISDICTION TO
|
||||
JURISDICTION. ID DOES NOT WARRANT THAT THE OPERATION OF THE SOFTWARE
|
||||
WILL BE UNINTERRUPTED, ERROR FREE OR MEET YOUR SPECIFIC REQUIREMENTS.
|
||||
THE WARRANTY SET FORTH ABOVE IS IN LIEU OF ALL OTHER EXPRESS
|
||||
WARRANTIES WHETHER ORAL OR WRITTEN. THE AGENTS, EMPLOYEES,
|
||||
DISTRIBUTORS, AND DEALERS OF ID ARE NOT AUTHORIZED TO MAKE
|
||||
MODIFICATIONS TO THIS WARRANTY, OR ADDITIONAL WARRANTIES ON BEHALF
|
||||
OF ID.
|
||||
|
||||
Exclusive Remedies. The Software is being offered to you
|
||||
free of any charge. You agree that you have no remedy against ID, its
|
||||
affiliates, contractors, suppliers, and agents for loss or damage
|
||||
caused by any defect or failure in the Software regardless of the form
|
||||
of action, whether in contract, tort, includinegligence, strict
|
||||
liability or otherwise, with regard to the Software. This Agreement
|
||||
shall be construed in accordance with and governed by the laws of the
|
||||
State of Texas. Copyright and other proprietary matters will be
|
||||
governed by United States laws and international treaties. IN ANY
|
||||
CASE, ID SHALL NOT BE LIABLE FOR LOSS OF DATA, LOSS OF PROFITS, LOST
|
||||
SAVINGS, SPECIAL, INCIDENTAL, CONSEQUENTIAL, INDIRECT OR OTHER
|
||||
SIMILAR DAMAGES ARISING FROM BREACH OF WARRANTY, BREACH OF CONTRACT,
|
||||
NEGLIGENCE, OR OTHER LEGAL THEORY EVEN IF ID OR ITS AGENT HAS BEEN
|
||||
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY
|
||||
OTHER PARTY. Some jurisdictions do not allow the exclusion or
|
||||
limitation of incidental or consequential damages, so the above
|
||||
limitation or exclusion may not apply to you.
|
||||
```
|
||||
Reference in New Issue
Block a user