Compare commits

...

6 Commits

Author SHA1 Message Date
Aryadev Chavali
925c5e0372 Add raylib 5.5 to our codebase and statically link with it
This way you won't need to install raylib as a dependency in order to
use it.  You'll still need its dependencies, like glfw, but this
should remove one layer of indirection.
2025-12-12 06:12:38 +00:00
Aryadev Chavali
82604480c0 Setup variable in build script for user to adjust thread timers 2025-12-12 05:42:13 +00:00
Aryadev Chavali
ca3bb64aae Allow compiler-level declarations for the thread timers
We use a #define here to set these up - if you define them via a -D
block yourself, you can adjust these as you require.
2025-12-12 05:42:10 +00:00
Aryadev Chavali
0cb14af26e Push THREAD_GENERAL_DELAY to 100ms 2025-12-12 05:16:01 +00:00
Aryadev Chavali
01484a65ec Add a camera to move around the numberline, add text for the bounds 2025-12-12 05:15:17 +00:00
Aryadev Chavali
8cd700a9e0 Delete old main 2025-12-12 04:42:16 +00:00
12 changed files with 12748 additions and 210 deletions

View File

@@ -3,23 +3,24 @@
set -xe
OUT="cw_tree.out"
GFLAGS="-Wall -Wextra -Wswitch-enum -std=c++17"
GFLAGS="-Wall -Wextra -Wswitch-enum -std=c++17 -Iraylib-5.5_linux_amd64/include"
LIBS="-Lraylib-5.5_linux_amd64/lib -l:libraylib.a" # link statically with raylib
VARFLAGS="-DTHREAD_PAUSE_MS=1000 -DTHREAD_GENERAL_MS=1"
DFLAGS="-ggdb -fsanitize=address -fsanitize=undefined"
RFLAGS="-O2"
CFLAGS="$GFLAGS $DFLAGS"
LIBS="-lraylib -lm"
build() {
c++ $CFLAGS -o $OUT src/node.cpp src/state.cpp src/worker.cpp src/main.cpp $LIBS
}
CFLAGS="$GFLAGS $VARFLAGS $DFLAGS"
if [ "$1" = "release" ]
then
CFLAGS="$GFLAGS $VARFLAGS $RFLAGS"
shift 1
elif [ "$1" = "debug" ]
then
shift 1
fi
c++ $CFLAGS -o $OUT src/node.cpp src/state.cpp src/worker.cpp src/main.cpp $LIBS
if [ "$1" = "run" ]
then
build && ./$OUT
elif [ "$1" = "release" ]
then
CFLAGS="$GFLAGS $RFLAGS"
build;
else
build;
./$OUT
fi

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,16 @@
Copyright (c) 2013-2024 Ramon Santamaria (@raysan5)
This software is provided "as-is", without any express or implied warranty. In no event
will the authors be held liable for any damages arising from the use of this software.
Permission is granted to anyone to use this software for any purpose, including commercial
applications, and to alter it and redistribute it freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not claim that you
wrote the original software. If you use this software in a product, an acknowledgment
in the product documentation would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be misrepresented
as being the original software.
3. This notice may not be removed or altered from any source distribution.

View File

@@ -0,0 +1,150 @@
<img align="left" style="width:260px" src="https://github.com/raysan5/raylib/blob/master/logo/raylib_logo_animation.gif" width="288px">
**raylib is a simple and easy-to-use library to enjoy videogames programming.**
raylib is highly inspired by Borland BGI graphics lib and by XNA framework and it's especially well suited for prototyping, tooling, graphical applications, embedded systems and education.
*NOTE for ADVENTURERS: raylib is a programming library to enjoy videogames programming; no fancy interface, no visual helpers, no debug button... just coding in the most pure spartan-programmers way.*
Ready to learn? Jump to [code examples!](https://www.raylib.com/examples.html)
---
<br>
[![GitHub Releases Downloads](https://img.shields.io/github/downloads/raysan5/raylib/total)](https://github.com/raysan5/raylib/releases)
[![GitHub Stars](https://img.shields.io/github/stars/raysan5/raylib?style=flat&label=stars)](https://github.com/raysan5/raylib/stargazers)
[![GitHub commits since tagged version](https://img.shields.io/github/commits-since/raysan5/raylib/5.0)](https://github.com/raysan5/raylib/commits/master)
[![GitHub Sponsors](https://img.shields.io/github/sponsors/raysan5?label=sponsors)](https://github.com/sponsors/raysan5)
[![Packaging Status](https://repology.org/badge/tiny-repos/raylib.svg)](https://repology.org/project/raylib/versions)
[![License](https://img.shields.io/badge/license-zlib%2Flibpng-blue.svg)](LICENSE)
[![Discord Members](https://img.shields.io/discord/426912293134270465.svg?label=Discord&logo=discord)](https://discord.gg/raylib)
[![Reddit Static Badge](https://img.shields.io/badge/-r%2Fraylib-red?style=flat&logo=reddit&label=reddit)](https://www.reddit.com/r/raylib/)
[![Youtube Subscribers](https://img.shields.io/youtube/channel/subscribers/UC8WIBkhYb5sBNqXO1mZ7WSQ?style=flat&label=Youtube&logo=youtube)](https://www.youtube.com/c/raylib)
[![Twitch Status](https://img.shields.io/twitch/status/raysan5?style=flat&label=Twitch&logo=twitch)](https://www.twitch.tv/raysan5)
[![Windows](https://github.com/raysan5/raylib/workflows/Windows/badge.svg)](https://github.com/raysan5/raylib/actions?query=workflow%3AWindows)
[![Linux](https://github.com/raysan5/raylib/workflows/Linux/badge.svg)](https://github.com/raysan5/raylib/actions?query=workflow%3ALinux)
[![macOS](https://github.com/raysan5/raylib/workflows/macOS/badge.svg)](https://github.com/raysan5/raylib/actions?query=workflow%3AmacOS)
[![WebAssembly](https://github.com/raysan5/raylib/workflows/WebAssembly/badge.svg)](https://github.com/raysan5/raylib/actions?query=workflow%3AWebAssembly)
[![CMakeBuilds](https://github.com/raysan5/raylib/workflows/CMakeBuilds/badge.svg)](https://github.com/raysan5/raylib/actions?query=workflow%3ACMakeBuilds)
[![Windows Examples](https://github.com/raysan5/raylib/actions/workflows/windows_examples.yml/badge.svg)](https://github.com/raysan5/raylib/actions/workflows/windows_examples.yml)
[![Linux Examples](https://github.com/raysan5/raylib/actions/workflows/linux_examples.yml/badge.svg)](https://github.com/raysan5/raylib/actions/workflows/linux_examples.yml)
features
--------
- **NO external dependencies**, all required libraries are [bundled into raylib](https://github.com/raysan5/raylib/tree/master/src/external)
- Multiple platforms supported: **Windows, Linux, MacOS, RPI, Android, HTML5... and more!**
- Written in plain C code (C99) using PascalCase/camelCase notation
- Hardware accelerated with OpenGL (**1.1, 2.1, 3.3, 4.3, ES 2.0, ES 3.0**)
- **Unique OpenGL abstraction layer** (usable as standalone module): [rlgl](https://github.com/raysan5/raylib/blob/master/src/rlgl.h)
- Multiple **Fonts** formats supported (TTF, OTF, FNT, BDF, sprite fonts)
- Multiple texture formats supported, including **compressed formats** (DXT, ETC, ASTC)
- **Full 3D support**, including 3D Shapes, Models, Billboards, Heightmaps and more!
- Flexible Materials system, supporting classic maps and **PBR maps**
- **Animated 3D models** supported (skeletal bones animation) (IQM, M3D, glTF)
- Shaders support, including model shaders and **postprocessing** shaders
- **Powerful math module** for Vector, Matrix and Quaternion operations: [raymath](https://github.com/raysan5/raylib/blob/master/src/raymath.h)
- Audio loading and playing with streaming support (WAV, QOA, OGG, MP3, FLAC, XM, MOD)
- **VR stereo rendering** support with configurable HMD device parameters
- Huge examples collection with [+140 code examples](https://github.com/raysan5/raylib/tree/master/examples)!
- Bindings to [+70 programming languages](https://github.com/raysan5/raylib/blob/master/BINDINGS.md)!
- **Free and open source**
basic example
--------------
This is a basic raylib example, it creates a window and draws the text `"Congrats! You created your first window!"` in the middle of the screen. Check this example [running live on web here](https://www.raylib.com/examples/core/loader.html?name=core_basic_window).
```c
#include "raylib.h"
int main(void)
{
InitWindow(800, 450, "raylib [core] example - basic window");
while (!WindowShouldClose())
{
BeginDrawing();
ClearBackground(RAYWHITE);
DrawText("Congrats! You created your first window!", 190, 200, 20, LIGHTGRAY);
EndDrawing();
}
CloseWindow();
return 0;
}
```
build and installation
----------------------
raylib binary releases for Windows, Linux, macOS, Android and HTML5 are available at the [Github Releases page](https://github.com/raysan5/raylib/releases).
raylib is also available via multiple package managers on multiple OS distributions.
#### Installing and building raylib on multiple platforms
[raylib Wiki](https://github.com/raysan5/raylib/wiki#development-platforms) contains detailed instructions on building and usage on multiple platforms.
- [Working on Windows](https://github.com/raysan5/raylib/wiki/Working-on-Windows)
- [Working on macOS](https://github.com/raysan5/raylib/wiki/Working-on-macOS)
- [Working on GNU Linux](https://github.com/raysan5/raylib/wiki/Working-on-GNU-Linux)
- [Working on Chrome OS](https://github.com/raysan5/raylib/wiki/Working-on-Chrome-OS)
- [Working on FreeBSD](https://github.com/raysan5/raylib/wiki/Working-on-FreeBSD)
- [Working on Raspberry Pi](https://github.com/raysan5/raylib/wiki/Working-on-Raspberry-Pi)
- [Working for Android](https://github.com/raysan5/raylib/wiki/Working-for-Android)
- [Working for Web (HTML5)](https://github.com/raysan5/raylib/wiki/Working-for-Web-(HTML5))
- [Working anywhere with CMake](https://github.com/raysan5/raylib/wiki/Working-with-CMake)
*Note that the Wiki is open for edit, if you find some issues while building raylib for your target platform, feel free to edit the Wiki or open an issue related to it.*
#### Setup raylib with multiple IDEs
raylib has been developed on Windows platform using [Notepad++](https://notepad-plus-plus.org/) and [MinGW GCC](https://www.mingw-w64.org/) compiler but it can be used with other IDEs on multiple platforms.
[Projects directory](https://github.com/raysan5/raylib/tree/master/projects) contains several ready-to-use **project templates** to build raylib and code examples with multiple IDEs.
*Note that there are lots of IDEs supported, some of the provided templates could require some review, so please, if you find some issue with a template or you think they could be improved, feel free to send a PR or open a related issue.*
learning and docs
------------------
raylib is designed to be learned using [the examples](https://github.com/raysan5/raylib/tree/master/examples) as the main reference. There is no standard API documentation but there is a [**cheatsheet**](https://www.raylib.com/cheatsheet/cheatsheet.html) containing all the functions available on the library a short description of each one of them, input parameters and result value names should be intuitive enough to understand how each function works.
Some additional documentation about raylib design can be found in [raylib GitHub Wiki](https://github.com/raysan5/raylib/wiki). Here are the relevant links:
- [raylib cheatsheet](https://www.raylib.com/cheatsheet/cheatsheet.html)
- [raylib architecture](https://github.com/raysan5/raylib/wiki/raylib-architecture)
- [raylib library design](https://github.com/raysan5/raylib/wiki)
- [raylib examples collection](https://github.com/raysan5/raylib/tree/master/examples)
- [raylib games collection](https://github.com/raysan5/raylib-games)
contact and networks
---------------------
raylib is present in several networks and raylib community is growing everyday. If you are using raylib and enjoying it, feel free to join us in any of these networks. The most active network is our [Discord server](https://discord.gg/raylib)! :)
- Webpage: [https://www.raylib.com](https://www.raylib.com)
- Discord: [https://discord.gg/raylib](https://discord.gg/raylib)
- Twitter: [https://www.twitter.com/raysan5](https://www.twitter.com/raysan5)
- Twitch: [https://www.twitch.tv/raysan5](https://www.twitch.tv/raysan5)
- Reddit: [https://www.reddit.com/r/raylib](https://www.reddit.com/r/raylib)
- Patreon: [https://www.patreon.com/raylib](https://www.patreon.com/raylib)
- YouTube: [https://www.youtube.com/channel/raylib](https://www.youtube.com/c/raylib)
contributors
------------
<a href="https://github.com/raysan5/raylib/graphs/contributors">
<img src="https://contrib.rocks/image?repo=raysan5/raylib&max=500&columns=20&anon=1" />
</a>
license
-------
raylib is licensed under an unmodified zlib/libpng license, which is an OSI-certified, BSD-like license that allows static linking with closed source software. Check [LICENSE](LICENSE) for further details.
raylib uses internally some libraries for window/graphics/inputs management and also to support different file formats loading, all those libraries are embedded with and are available in [src/external](https://github.com/raysan5/raylib/tree/master/src/external) directory. Check [raylib dependencies LICENSES](https://github.com/raysan5/raylib/wiki/raylib-dependencies) on [raylib Wiki](https://github.com/raysan5/raylib/wiki) for details.

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

Binary file not shown.

View File

@@ -15,17 +15,19 @@
#include <tuple>
#include <raylib.h>
#include <raymath.h>
#include "base.hpp"
#include "node.hpp"
#include "worker.hpp"
#define WIDTH 1024
#define HEIGHT 1024
#define HEIGHT 800
#define FONT_SIZE 20
#define CIRCLE_SIZE 2
#define LINE_TOP (7 * HEIGHT / 16)
#define LINE_BOTTOM (9 * HEIGHT / 16)
#define N_THREADS 15
using cw::state::DrawState;
using cw::state::State;
@@ -46,23 +48,12 @@ void draw_fraction(cw::node::Fraction f, u64 x, u64 y)
DrawText(s.c_str(), x - width / 2, y - FONT_SIZE, FONT_SIZE, WHITE);
}
constexpr u64 clamp_to_width(const DrawState &ds, f64 val)
{
return (WIDTH / (ds.bounds.upper_val - ds.bounds.lower_val)) *
(val - ds.bounds.lower_val);
}
void draw_tree(DrawState &ds, State &state)
{
// Number line
DrawLine(0, HEIGHT / 2, WIDTH, HEIGHT / 2, WHITE);
// Bounds
u64 lower_x = clamp_to_width(ds, ds.bounds.leftmost.value.norm);
u64 upper_x = clamp_to_width(ds, ds.bounds.rightmost.value.norm);
DrawLine(lower_x, LINE_TOP, lower_x, LINE_BOTTOM, WHITE);
DrawLine(upper_x, LINE_TOP, upper_x, LINE_BOTTOM, WHITE);
state.mutex.lock();
std::stack<std::pair<u64, f64>> stack;
cw::node::Node n = state.allocator.get_val(0);
@@ -73,7 +64,7 @@ void draw_tree(DrawState &ds, State &state)
f64 norm;
std::tie(node_index, norm) = stack.top();
stack.pop();
u64 x = clamp_to_width(ds, norm);
u64 x = Remap(norm, ds.bounds.lower_val, ds.bounds.upper_val, 0, WIDTH);
DrawLine(x, LINE_TOP, x, LINE_BOTTOM, RED);
cw::node::Node n = state.allocator.get_val(node_index);
@@ -89,6 +80,14 @@ void draw_tree(DrawState &ds, State &state)
}
}
state.mutex.unlock();
DrawLine(0, LINE_TOP, 0, LINE_BOTTOM, WHITE);
DrawText("0", 0, LINE_TOP - FONT_SIZE, FONT_SIZE, WHITE);
DrawLine(WIDTH, LINE_TOP, WIDTH, LINE_BOTTOM, WHITE);
char buffer[64];
sprintf(buffer, "%d", (int)ds.bounds.upper_val);
DrawText(buffer, WIDTH - (FONT_SIZE / 2), LINE_TOP - FONT_SIZE, FONT_SIZE,
WHITE);
}
using Clock = std::chrono::steady_clock;
@@ -116,10 +115,9 @@ int main(void)
std::string format_str;
u64 format_str_width = 0;
// Init threads
#define THREADS 15
std::thread threads[THREADS];
for (auto i = 0; i < THREADS; ++i)
// Init threads
std::thread threads[N_THREADS];
for (auto i = 0; i < N_THREADS; ++i)
{
threads[i] = std::move(std::thread(cw::worker::worker, std::ref(state)));
}
@@ -128,6 +126,13 @@ int main(void)
InitWindow(WIDTH, HEIGHT, "Calkin-Wilf tree");
SetTargetFPS(60);
// setup camera
Camera2D camera;
camera.target = {.x = 0, .y = 0};
camera.offset = {.x = WIDTH / 16, .y = 0};
camera.rotation = 0.0f;
camera.zoom = 0.8f;
while (!WindowShouldClose())
{
// Update
@@ -155,17 +160,33 @@ int main(void)
}
if (IsKeyPressed(KEY_SPACE))
{
state.pause_work = !state.pause_work;
if (IsMouseButtonDown(MOUSE_BUTTON_LEFT))
{
Vector2 delta = GetMouseDelta();
delta = Vector2Scale(delta, -1.0f / camera.zoom);
camera.target = Vector2Add(camera.target, delta);
}
float wheel = GetMouseWheelMove();
if (wheel != 0)
{
Vector2 mouse_to_world = GetScreenToWorld2D(GetMousePosition(), camera);
camera.offset = GetMousePosition();
camera.target = mouse_to_world;
camera.zoom = Clamp(camera.zoom + (wheel * 0.1f), 0.125, 64);
printf("%lf\n", camera.zoom);
}
// Draw
ClearBackground(BLACK);
BeginDrawing();
BeginMode2D(camera);
draw_tree(draw_state, state);
DrawText(format_str.c_str(), WIDTH / 2 - format_str_width / 2, HEIGHT / 8,
FONT_SIZE, WHITE);
EndMode2D();
DrawText(format_str.c_str(), (31 * WIDTH / 32) - format_str_width / 2,
HEIGHT / 32, FONT_SIZE, WHITE);
EndDrawing();
}
@@ -179,178 +200,6 @@ int main(void)
return 0;
}
#if 0
struct State
{
NodeAllocator allocator;
std::queue<word_t> iteration_queue;
word_t root;
struct Bounds
{
Node leftmost, rightmost;
long double lower, upper;
} bounds;
struct Iteration
{
Fraction left, centre, right;
} iteration;
State(const Fraction start) : allocator{256}
{
root = allocator.alloc(start);
iteration_queue.push(root);
bounds.leftmost = allocator.getVal(root);
bounds.rightmost = allocator.getVal(root);
compute_bounds();
}
void do_iteration(void)
{
std::tie(iteration.left, iteration.centre, iteration.right) =
iterate(iteration_queue, allocator);
compute_bound_nodes();
compute_bounds();
}
void compute_bounds()
{
bounds.lower = std::floorl(bounds.leftmost.value.norm);
bounds.upper = std::ceill(bounds.rightmost.value.norm);
}
void compute_bound_nodes()
{
bounds.leftmost = allocator.getVal(0);
while (bounds.leftmost.left.has_value())
bounds.leftmost = allocator.getVal(bounds.leftmost.left.value());
bounds.rightmost = allocator.getVal(0);
while (bounds.rightmost.right.has_value())
bounds.rightmost = allocator.getVal(bounds.rightmost.right.value());
}
constexpr word_t clamp_to_width(long double value)
{
return (WIDTH / (bounds.upper - bounds.lower)) * (value - bounds.lower);
}
void draw_bounds()
{
word_t lower_x = clamp_to_width(bounds.leftmost.value.norm);
word_t upper_x = clamp_to_width(bounds.rightmost.value.norm);
DrawLine(lower_x, LINE_TOP, lower_x, LINE_BOTTOM, WHITE);
DrawLine(upper_x, LINE_TOP, upper_x, LINE_BOTTOM, WHITE);
}
void draw_nodes()
{
std::stack<Node> stack;
stack.push(allocator.getVal(0));
while (!stack.empty())
{
Node n = stack.top();
stack.pop();
word_t x = clamp_to_width(n.value.norm);
DrawLine(x, LINE_TOP, x, LINE_BOTTOM, RED);
if (n.left.has_value())
stack.push(allocator.getVal(n.left.value()));
if (n.right.has_value())
stack.push(allocator.getVal(n.right.value()));
}
}
void draw_iteration_nodes()
{
word_t x_left = clamp_to_width(iteration.left.norm);
word_t x_centre = clamp_to_width(iteration.centre.norm);
word_t x_right = clamp_to_width(iteration.right.norm);
DrawLine(x_left, LINE_TOP, x_left, LINE_BOTTOM, BLUE);
DrawLine(x_right, LINE_TOP, x_right, LINE_BOTTOM, BLUE);
DrawLine(x_centre, LINE_TOP, x_centre, LINE_BOTTOM, GREEN);
}
};
using Clock = std::chrono::steady_clock;
using Ms = std::chrono::milliseconds;
int main(void)
{
// Setup state
State state{{1, 1}};
// Setup meta text (counter, iterations, etc)
word_t count = 1, prev_count = 0;
std::stringstream format_stream;
std::string format_str;
word_t format_str_width = 0;
// Setup timer
bool is_playing = false;
auto time_current = Clock::now();
auto time_previous = time_current;
constexpr auto time_delta = 1;
InitWindow(WIDTH, HEIGHT, "Calkin-Wilf Tree");
while (!WindowShouldClose())
{
// timer logic
time_current = Clock::now();
if (is_playing &&
std::chrono::duration_cast<Ms>(time_current - time_previous).count() >=
time_delta)
{
time_previous = time_current;
state.do_iteration();
count += 2;
}
// Input logic
if (IsKeyDown(KEY_SPACE))
{
is_playing = true;
}
else if (IsKeyUp(KEY_SPACE))
{
is_playing = false;
}
if (IsKeyPressed(KEY_PERIOD))
{
state.do_iteration();
count += 2;
}
// Meta text logic
if (prev_count != count)
{
prev_count = count;
format_stream << "Count=" << count << "\n\n"
<< "Iterations=" << (count - 1) / 2 << "\n\n"
<< "Lower=" << to_string(state.bounds.leftmost.value)
<< "\n\n"
<< "Upper=" << to_string(state.bounds.rightmost.value);
format_str = format_stream.str();
format_stream.str("");
format_str_width = MeasureText(format_str.c_str(), FONT_SIZE * 2);
}
ClearBackground(BLACK);
BeginDrawing();
DrawLine(0, HEIGHT / 2, WIDTH, HEIGHT / 2, WHITE);
state.draw_nodes();
state.draw_bounds();
state.draw_iteration_nodes();
DrawText(format_str.c_str(), WIDTH / 2 - format_str_width / 2, HEIGHT / 8,
FONT_SIZE, WHITE);
EndDrawing();
}
CloseWindow();
return 0;
}
#endif
/* Copyright (C) 2024, 2025 Aryadev Chavali
* This program is distributed in the hope that it will be useful, but WITHOUT

View File

@@ -22,7 +22,6 @@ namespace cw::state
bounds.rightmost = state.allocator.get_val(bounds.rightmost.right);
state.mutex.unlock();
bounds.lower_val = std::floorl(bounds.leftmost.value.norm);
bounds.upper_val = std::ceill(bounds.rightmost.value.norm);
}
} // namespace cw::state

View File

@@ -36,7 +36,11 @@ namespace cw::state
f64 lower_val, upper_val;
} bounds;
DrawState(State &state) : state{state} {};
DrawState(State &state) : state{state}
{
// lim n -> -∞
bounds.lower_val = 0;
};
void compute_bounds(void);
};

View File

@@ -13,12 +13,21 @@
#include "state.hpp"
#ifndef THREAD_PAUSE_MS
#define THREAD_PAUSE_MS 1000
#endif
#ifndef THREAD_GENERAL_MS
#define THREAD_GENERAL_MS 10
#endif
namespace cw::worker
{
using cw::node::NodeAllocator;
using cw::state::State;
constexpr auto THREAD_PAUSE_DELAY = std::chrono::milliseconds(1000);
constexpr auto THREAD_GENERAL_DELAY = std::chrono::milliseconds(1);
constexpr auto THREAD_PAUSE_DELAY =
std::chrono::milliseconds(THREAD_PAUSE_MS);
constexpr auto THREAD_GENERAL_DELAY =
std::chrono::milliseconds(THREAD_GENERAL_MS);
// Performs a single iteration which consists of the following:
// 1) pop an index off the iteration queue