<commit_before>* Micros, a playground for demos

This repository is a minimalistic playground for writing demos against
OSX or Windows, with an emphasis on making it possible to collaborate
easily between multiple individuals.

What it is not: a framework, a graphic/audio library.

The build system is self-contained, it enforces a strict coding
standard with warnings all activated and automatically formatting the
code for you.

It standardizes on C++11 and OpenGL 3.2 and targets Darwin/OSX past
10.7 (Lion) and NT/Windows 7 and beyond.

It’s all on github ready to be forked or downloaded:
    http://github.com/uucidl/uu.micros

** Specs

- shell script build (clean + rebuild + test + run)
- host system with =OpenGL 3.2= core context and 48khz stereo audio
- source only libraries accepted
- =C++11= only supported

Personal comment:
- To avoid arguing about code style, putting in the "artistic style" code formatter.

* Using

You have two options

** Forking uu.micros

Fork uu.micros; then compose your demo in any number of .cpp files
under [[./src/]]

Use [[./src/main.cpp/]] as an inspiration

** Using uu.micros as a submodule

A little bit more involved; this method allows you to upgrade
uu.micros later more easily, preserving the history of your piece.

Import uu.micros as a submodule of your git repository. For example:

#+BEGIN_SRC sh
$ mkdir modules
$ git submodule add --name uu.micros https://github.com/uucidl/uu.micros.git modules/uu.micros
#+END_SRC

Then put your .cpp files wherever you want (for example ./src/) and run:

#+BEGIN_SRC sh
modules/uu.micros/build --src-dir ./src --output-dir ./builds
#+END_SRC

** API
:PROPERTIES:
:mkdirp: yes
:END:

Using our experience to define the most minimal and useful hooks to
code a demo we come with the following:

#+begin_src c++ :mkdir yes :tangle include/micros/api.h
  #include <cstdint>

  /// initialize runtime (and start the demo)
  extern void runtime_init();

  /// current time in microseconds
  extern uint64_t now_micros();

  /**
   * entry point: called for each new video frame.
   *
   * It will be called in strict time order by the runtime.
   *
   * @param time_micros scheduling time for the frame
   */
  extern void render_next_gl3(uint64_t time_micros);

  /**
   * entry point: called for each new audio frame.
   *
   * It will be called in strict time order by the runtime
   *
   * @param time_micros scheduling time for the first sample of the frame
   * @param sample_count count of stereo audio sample to fill
   * @param left buffer of audio samples for the left channel
   * @param right buffer of audio samples for the right channel
   */
  extern void render_next_2chn_48khz_audio(uint64_t time_micros,
                  int const sample_count, double left[/*sample_count*/],
                  double right[/*sample_count*/]);
#+end_src


* History

changes can be found in [[./Changelog]]

** Origin

I decided to write this playground when reading <NAME>' idea about
doing "round robin" demo projects:

https://twitter.com/mmalex/status/403818676224544768
#+begin_example
<mmalex> Been wondering about doing an async 'chain' collab demo for years: rules: c++/GL only, 1 week work then pass it on... Repeat until deadline
<javiercampos> @mmalex Isn't that the exact opposite to async? :-)
<gpakosz> @mmalex on top of existing ground work demo system or from scratch?
<mmalex> @javiercampos heh :) I guess you're right! What's the right word...
<LiaSae> @mmalex The technical term for this in the cross-stitch word is round-robin :) Could apply as well!
<LiaSae> @mmalex Make that "world", d'oh.
<kamidphish> @mmalex Is that like the old C64 demos?<commit_msg>update header documentation in README<commit_after>* Micros, a playground for demos

This repository is a minimalistic playground for writing demos against
OSX or Windows, with an emphasis on making it possible to collaborate
easily between multiple individuals.

What it is not: a framework, a graphic/audio library.

The build system is self-contained, it enforces a strict coding
standard with warnings all activated and automatically formatting the
code for you.

It standardizes on C++11 and OpenGL 3.2 and targets Darwin/OSX past
10.7 (Lion) and NT/Windows 7 and beyond.

It’s all on github ready to be forked or downloaded:
    http://github.com/uucidl/uu.micros

** Specs

- shell script build (clean + rebuild + test + run)
- host system with =OpenGL 3.2= core context and 48khz stereo audio
- source only libraries accepted
- =C++11= only supported

Personal comment:
- To avoid arguing about code style, putting in the "artistic style" code formatter.

* Using

You have two options

** Forking uu.micros

Fork uu.micros; then compose your demo in any number of .cpp files
under [[./src/]]

Use [[./src/main.cpp/]] as an inspiration

** Using uu.micros as a submodule

A little bit more involved; this method allows you to upgrade
uu.micros later more easily, preserving the history of your piece.

Import uu.micros as a submodule of your git repository. For example:

#+BEGIN_SRC sh
$ mkdir modules
$ git submodule add --name uu.micros https://github.com/uucidl/uu.micros.git modules/uu.micros
#+END_SRC

Then put your .cpp files wherever you want (for example ./src/) and run:

#+BEGIN_SRC sh
modules/uu.micros/build --src-dir ./src --output-dir ./builds
#+END_SRC

** API
:PROPERTIES:
:mkdirp: yes
:END:

Using our experience to define the most minimal and useful hooks to
code a demo we come with the following:

#+begin_src c++ :mkdir yes :tangle include/micros/api.h
#pragma once

#include <cstdint>

/// initialize runtime (and start the demo)
extern void runtime_init();

/// current time in microseconds
extern uint64_t now_micros();

/// information about a display
struct Display {
        // the dimensions of the display's framebuffer in pixels
        uint32_t framebuffer_width_px;
        uint32_t framebuffer_height_px;
};

/**
 ,* entry point: called for each new video frame.
 ,*
 ,* It will be called in strict time order by the runtime.
 ,*
 ,* @param time_micros scheduling time for the frame
 ,*/
extern void render_next_gl3(uint64_t time_micros,
                            struct Display display);

/**
 ,* entry point: called for each new audio frame.
 ,*
 ,* It will be called in strict time order by the runtime
 ,*
 ,* @param time_micros scheduling time for the first sample of the frame
 ,* @param sample_count count of stereo audio sample to fill
 ,* @param left buffer of audio samples for the left channel
 ,* @param right buffer of audio samples for the right channel
 ,*/
extern void render_next_2chn_48khz_audio(uint64_t time_micros,
                int const sample_count, double left[/*sample_count*/],
                double right[/*sample_count*/]);

#+end_src


* History

changes can be found in [[./Changelog]]

** Origin

I decided to write this playground when reading <NAME>' idea about
doing "round robin" demo projects:

https://twitter.com/mmalex/status/403818676224544768
#+begin_example
<mmalex> Been wondering about doing an async 'chain' collab demo for years: rules: c++/GL only, 1 week work then pass it on... Repeat until deadline
<javiercampos> @mmalex Isn't that the exact opposite to async? :-)
<gpakosz> @mmalex on top of existing ground work demo system or from scratch?
<mmalex> @javiercampos heh :) I guess you're right! What's the right word...
<LiaSae> @mmalex The technical term for this in the cross-stitch word is round-robin :) Could apply as well!
<LiaSae> @mmalex Make that "world", d'oh.
<kamidphish> @mmalex Is that like the old C64 demos?
{'fraction_non_alphanumeric': 0.08347597103357472, 'fraction_numerical': 0.01237656352863726, 'mean_word_length': 3.7773584905660376, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 21, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5055682', 'n_tokens_mistral': 2385, 'n_tokens_neox': 2243, 'n_words': 1016}