{"id":22120767,"url":"https://github.com/grz0zrg/mammoth3d","last_synced_at":"2025-10-12T07:30:25.266Z","repository":{"id":4836260,"uuid":"5990394","full_name":"grz0zrg/Mammoth3D","owner":"grz0zrg","description":"Simple 3D framework to make demos and stuff.","archived":false,"fork":false,"pushed_at":"2015-08-22T21:55:41.000Z","size":23840,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-01T14:36:02.037Z","etag":null,"topics":["3d-engine","3d-framework","assimp","c-plus-plus","demo","demomaking","framework","glsl-shaders","renoise","shaders"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"jjethwa/rundeck","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grz0zrg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-09-28T00:00:18.000Z","updated_at":"2024-10-04T18:37:42.000Z","dependencies_parsed_at":"2022-09-05T23:21:22.733Z","dependency_job_id":null,"html_url":"https://github.com/grz0zrg/Mammoth3D","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grz0zrg%2FMammoth3D","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grz0zrg%2FMammoth3D/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grz0zrg%2FMammoth3D/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grz0zrg%2FMammoth3D/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grz0zrg","download_url":"https://codeload.github.com/grz0zrg/Mammoth3D/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236178219,"owners_count":19107660,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-engine","3d-framework","assimp","c-plus-plus","demo","demomaking","framework","glsl-shaders","renoise","shaders"],"created_at":"2024-12-01T14:29:51.554Z","updated_at":"2025-10-12T07:30:17.650Z","avatar_url":"https://github.com/grz0zrg.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"Mammoth3D\r\n=========\r\n\r\n### OpenGL 3.3+ demos framework ###\r\n\r\nTo use the entire framework just include \"mammoth3d.hpp\".\r\n\r\nMade it to do [demos](http://en.wikipedia.org/wiki/Demoscene) and to experiment\r\n\r\nThis framework use C++11 features to bypass the boring stuff\r\n\r\n### Usage ###\r\n\r\nThere is a sample project in the \"project\" folder, this can be used as a starting point.\r\n\r\nThe sample project should compile easily on Windows/Linux using the [codelite](http://www.codelite.org/) .workspace, there is configurations for Windows and Linux.\r\n\r\nThe \"lib\" folder contain all the libraries the engine use, some are mingw32 x86 pre-compiled so it compile easily under Windows\r\n\r\nThis framework is specifically made for demos; texture, shader, geometry etc can (and should) be created through a general purpose loader, with the \"loader\" there is no need to explicitely create any objects and releasing the memory, all stuff needed for a demo can be created this way, anything used from the framework does not need to be released explicitely or created.\r\n\r\n### Step by step guide ###\r\n\r\nOpening a window (set false to true for fullscreen, last argument is MSAA level)\r\n\r\n```cpp\r\nauto app = window::Window::getInstance();\r\napp-\u003eopen(\"example\", 800, 600, false, 2);\r\n```\r\n\t\r\n*By default the mouse cursor will be hidden and vsync will be requested*\r\n\r\nLoading GLSL files and compiling a program:\r\n\t\r\n```cpp\r\nauto program = loader::Loader::getInstance()-\u003egetProgram(\"simple.vert\", \"simple.frag\");\r\n```\r\n\t\r\nCreating a texture from an image file (only the PNG image format is supported):\r\n\r\n```cpp\r\nauto texture = loader::Loader::getInstance()-\u003egetTexture(\"image.png\");\r\n```\r\n\t\r\nCreating a quad with the texture on the first slot (all textures assignated will be registered as t[id] in the shader (thus `uniform sampler2D t0;` to access the texture within the shader for this example):\r\n\r\n```cpp\r\nauto quad = loader::Loader::getInstance()-\u003egetNewQuad({{texture, 0}});\r\n```\r\n\t\r\nCreating a purple BitmapText mesh from a bitmap font file:\r\n\r\n```cpp\r\nauto ldr = loader::Loader::getInstance();\r\nauto text = ldr-\u003egetNewBitmapText(\"font.png\", \"Hello World!\", 255, 0, 255, 0.25f); // last argument is the alpha treshold, increasing this value make the characters bolder, decreasing it make it thinner\r\ntext-\u003esetScreenAlign(true); // set this to false to manipulate the text quad, to allow for rotations, scaling etc otherwise by default it is true and the text will be screen aligned, always visible\r\n```\r\n\t\r\n*The text, color, treshold, screen alignment can be updated in real-time.*\r\n\r\nCreating a camera and setting up its position/target:\r\n\r\n```cpp\r\nauto camera = loader::Loader::getInstance()-\u003egetNewCamera(camera::PERSPECTIVE, 75, screenWidth / screenHeight);\r\ncamera-\u003elookAt(0, 0, -100.0f, 0, 0, 0, 0, 1, 0);\r\n```\r\n\t\r\nUsing the camera and adding the quad and text to the scene:\r\n\r\n```cpp\r\nauto renderer = renderer::Renderer::getInstance();\r\nrenderer-\u003esetCamera(camera);\r\nrenderer-\u003eadd(quad);\r\nrenderer-\u003eadd(text);\r\n```\r\n\t\r\nMain loop:\r\n\r\n```cpp\r\ndo {\r\n    renderer-\u003erender();\r\n\t\t\r\n    app-\u003eswapBuffers();\r\n} while(app-\u003erunning() \u0026\u0026 !audio-\u003eisMusicFinished()); // see below for audio setup\r\n```\r\n\r\n#### Audio -\u003e Visual synchronization ####\r\n\r\nThere is a built-in synctracker (value/event sequencer) which can be used in real-time with a gamepad or similar device to control any aspects of a demo (with chunk looping/backward/forward feature), it is possible to animate an entire demo that way in real-time without any code, generally the sync data will be imported first from an existing song but it is not necessary, there is a tool to convert [Renoise](http://www.renoise.com/) XRNS Song.xml data to allow perfect synchronization (with additional real-time edits needed, because it generate a \"blank\" event per note) of a song made in Renoise with the visuals.\r\n\t\r\nLoading an audio file and playing it (only the OGG format is supported):\r\n\r\n```cpp\r\nauto audio = audio::Audio::getInstance()\r\naudio-\u003eloadMusic(\"audio_track.ogg\");\r\naudio-\u003eplayMusic(true, 0.5f); // loop play, volume halved\r\n```\r\n\r\nSetting up the synctracker:\r\n\r\n```cpp\r\nauto synctracker = sync::SyncTracker::getInstance();\r\n// the XRNS song.xml converter is needed to get a \".mms\" sync file from a song\r\nsynctracker-\u003eload(\"sync.mms\");\r\n// those two lines is only needed if there is a need to adjust the bpm/lpb because no sync file is used, otherwise the .mms set them when it is loaded\r\nsynctracker-\u003esetBpm(115);\r\nsynctracker-\u003esetLpb(4);\r\n\t\r\n// setup the synchronized values, one track for each values, it will also create a track if the track name is not found\r\nfloat sync_value = 0.0f;\r\nint sync_value2 = 0;\r\nsynctracker-\u003esetTracks({{\"track_name_1\", \u0026sync_value}, {\"track_name_2\", \u0026sync_value2}});\r\n\t\r\n// if you want to edit the sync in real-time with a gamepad (or similar device)\r\nauto synctracker_controller = sync::SyncTrackerController::getInstance();\r\n```\r\n\r\nNow, in the main loop:\r\n\r\n```cpp\r\n// use sync_value and sync_value2 as you wish\r\n\t\r\ndouble song_time = audio-\u003egetMusicTime();\r\nsynctracker-\u003eupdate(song_time);\r\n\t\r\nsynctracker_controller-\u003eupdate();\r\n```\r\n\t\r\n*There is no graphical interface to edit the synctracker data but there is still text output in the console reflecting any actions you do.*\r\n\r\n### More stuff ###\r\n\r\nIt is easy to pass stuff to a shader program using uniform blocks:\r\n\r\n```cpp\r\nauto ublock = loader::Loader::getInstance()-\u003egetNewUniformBlock(\"BlockName\", {{\"r\", 1.0f}, {\"g\", 1.0f}, {\"b\", 1.0f}, {\"a\", 1.0f}, {\"stuff\", 1.0f}}, program);\r\n```\r\n\t\r\n*There is only \"float\" uniform type available at the moment.*\r\n\t\r\nThen in the GLSL shader (name does not matter here):\r\n\t\r\n```glsl\r\nlayout (std140) uniform BlockName {\r\n    vec4 color;\r\n    float stuff;\r\n};\r\n```\r\n\t\r\nOr you can pass large set of data using a TBO:\r\n\r\n```cpp\r\nauto texture_buffer = loader::Loader::getInstance()-\u003egetNewTextureBuffer(std::vector\u003cfloat\u003e {1.0f, 0.0f, 0.0f, 0.0f});\r\nmesh-\u003esetTexture(texture_buffer, 1);\r\n```\r\n\t\r\nIf you need to modify the TBO data you will need to call `ldr-\u003egetNewTbo` to get the TBO object then passing the pointer to `getNewTextureBuffer` and use `tbo-\u003eupdateData` function to update the data\r\n\t\r\nThen in the GLSL shader:\r\n\r\n```glsl\r\nuniform samplerBuffer t1; // access data using texelFetch function\r\n```\r\n\t\r\nIt is easy to do instancing, example if you want a huge amount of objects of the same type:\r\n\r\n```cpp\r\nauto ldr = loader::Loader::getInstance();\r\nauto particle_texture = ldr-\u003egetTexture(\"particle.png\");\r\nauto particle = ldr-\u003egetNewQuad({{particle_texture, 0}});\r\nauto particles = particle-\u003eenableInstancing(1000); // 1000 objects will be drawn in a single call, particles is a vector of Mesh, you can change individual attributes from it for each mesh (note: only transform attributes are passed per instance right now)\r\n```\r\n\t\t\r\n*An attribute location for instances transform matrix should be specified in the vertex shader as `layout(location = 4) in mat4 imvp;`*\r\n\r\n*Then in the vertex shader you can use `gl_InstanceID` to get the object id, combine it with a TBO and texelFetch function in the shader for any more per instance stuff like colors, uvs...*\r\n\r\nThere is also a fast way to display huge amount of static objects by merging geometries, it will be difficult to apply effects on each of them but may be faster than instancing:\r\n\r\n```cpp\r\nunsigned int object_count = 1000;\r\n\t\r\nauto geom = ldr-\u003egetNewGeometry();\r\nfor (unsigned int i = 0; i \u003c object_count; i++) {\r\n    auto quad = new object::Quad();\r\n    // setup object position, rotation, scale here\r\n    core::geometryutils::merge(geom, quad);\r\n    delete quad;\r\n}\r\ngeom-\u003eupdate();\r\n\t\r\nauto ldr = loader::Loader::getInstance();\r\nauto quad_mesh = ldr-\u003egetNewMesh(geom, ldr-\u003egetNewMaterial());\r\n\t\r\n// rendering quad_mesh will be very fast now\r\n```\r\n\r\n### Tools ###\r\n\r\nThe engine use a binary format to load scenes/meshes, converters are available in the \"tools\" folder\r\n\r\nassimp2bin load and convert any meshes files that the [Assimp](http://assimp.sourceforge.net/) library support\r\n\r\ndae2bin is deprecated, export Collada (.dae) only and only the geometry (UV/normal export is buggy)\r\n\r\n### Others platforms ###\r\n\r\nJust look at the .project settings in the project folder, the framework require: [PortAudio](http://www.portaudio.com/) [libogg/libvorbis](http://xiph.org/downloads) [glfw3](http://www.glfw.org/download.html)\r\n\r\nAdditionally some others libraries ([GLM](http://glm.g-truc.net), [lodepng](http://lodev.org/lodepng/), [GLEW](http://glew.sourceforge.net/), [tinyxml2](http://www.grinninglizard.com/tinyxml2/)) are provided and used, they can be found in the \"lib\" or \"include\" ([GLM](http://glm.g-truc.net)) folder, they can be compiled with the project\r\n\r\nThe assimp2bin tool require the [Assimp](http://assimp.sourceforge.net/) library\r\n\r\n### License ###\r\n\r\nDo what you want.\r\n\r\n### Screenshots from experiments ###\r\n\r\n![Alt text](http://garzul.tonsite.biz/mammoth3d/05_08_2013_small.png \"mammoth3d\")\r\n\r\n![Alt text](http://garzul.tonsite.biz/mammoth3d/30_07_2013.png \"mammoth3d\")\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrz0zrg%2Fmammoth3d","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrz0zrg%2Fmammoth3d","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrz0zrg%2Fmammoth3d/lists"}