{"id":13534327,"url":"https://github.com/0beqz/three-billboard-reflection","last_synced_at":"2025-03-16T20:31:49.776Z","repository":{"id":41983007,"uuid":"440545890","full_name":"0beqz/three-billboard-reflection","owner":"0beqz","description":"Performant plane reflections in three.js r139","archived":false,"fork":false,"pushed_at":"2022-04-20T17:46:40.000Z","size":27732,"stargazers_count":111,"open_issues_count":2,"forks_count":11,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-10T10:54:43.495Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0beqz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-12-21T14:32:06.000Z","updated_at":"2025-02-01T15:55:56.000Z","dependencies_parsed_at":"2022-09-18T12:02:51.697Z","dependency_job_id":null,"html_url":"https://github.com/0beqz/three-billboard-reflection","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/0beqz%2Fthree-billboard-reflection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0beqz%2Fthree-billboard-reflection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0beqz%2Fthree-billboard-reflection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0beqz%2Fthree-billboard-reflection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0beqz","download_url":"https://codeload.github.com/0beqz/three-billboard-reflection/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243830922,"owners_count":20354850,"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":[],"created_at":"2024-08-01T07:01:30.541Z","updated_at":"2025-03-16T20:31:46.355Z","avatar_url":"https://github.com/0beqz.png","language":"JavaScript","funding_links":[],"categories":["Libraries"],"sub_categories":["JavaScript"],"readme":"# Billboard Reflection\nImplements performant reflections for simple planes in three.js.\n\\\n\\\nThe name derives from billboards for which this technique can ideally be used\nas seen in the [Unreal Engine 3: Samaritan Demo](https://youtu.be/RSXyztq_0uM?t=12).\nThe benefit of this technique is that any mesh with any orientation can reflect these planes correctly.\n\\\n\\\n\u003cimg src=\"screenshots/social.jpg\" \u003e\n## Installation\nThe build (UMD and module version) is located in the [/dist](dist/) directory.\n\n## Usage\n```javascript\nimport BillboardReflection from \"./BillboardReflection\"\n\nlet billboardReflection = new BillboardReflection()\n\nbillboardReflection.create(billboardMesh)\nbillboardReflection.create(otherBillboardMesh, options)\n\nmesh.material.onBeforeCompile = shader =\u003e billboardReflection.enableReflection(shader)\n```\nThis will make `mesh` reflect `billboardMesh` and `otherBillboardMesh`.\n\n## Options\nOptions for \u003cb\u003eBillboardReflection.create(mesh, options)\u003c/b\u003e\n\nDefault values:\n```javascript\n{\n    rayFalloff: 0,\n    color: undefined, // will use reflecting mesh's color if undefined\n    opacity: undefined, // will use reflecting mesh's opacity if undefined\n    visible: undefined // will use reflecting mesh's visibility if undefined\n}\n```\nDescription:\n- `rayFalloff`: how much the ray falls off by distance, higher values will make it fade out faster\n- `color`: multiplies the reflection color with the given color, if it is undefined, the mesh's material color will be used\n- `opacity`: the opacity of the reflection, if it is undefined, the mesh's material opacity will be used\n- `visible`: whether the reflection is visible, if it is undefined, the mesh's visibility (namely its _visible_ property and its material's _visible_ property) will be used\n\n\u003cbr\u003e\nOptions for \u003cb\u003eBillboardReflection.enableReflection(shader, options)\u003c/b\u003e\n\nDefault values:\n```javascript\n{\n    roughnessMapBlur: true,\n    roughnessMapBlurIntensity: 0.85,\n\n    roughness: undefined, // will use reflecting mesh's roughness if undefined\n    envMapIntensity: undefined // will use reflecting mesh's envMapIntensity if undefined\n}\n```\n\nDescription:\n- `roughnessMapBlur`: whether to blur reflections using low-res mipmaps (see [Limitations](https://github.com/0beqz/three-billboard-reflection#roughness) section for more information)\n- `roughnessMapBlurIntensity`: if roughnessMapBlur is enabled, how much a material should be blurred for higher roughness values, higher values will blur a reflection more but will result in more artifacts\n- `roughness`: overwrite roughness value for a reflection, if it's undefined, the material's *roughness* value will be used\n- `envMapIntensity`: overwrite envMapIntensity value for a reflection, if it's undefined, the material's *envMapIntensity* value will be used\n\n\n## Reflection for just a texture and matrix\nIf your reflecting objects are not meshes (e.g. all billboards are batched into a single mesh)\nthen you can use a texture and a matrix to create reflections for each billboard:\n```javascript\nlet position = new Vector3(1, 0, 0)\nlet rotation = new Quaternion().setFromEuler(new Euler(0, 1, 0))\nlet scale = new Vector3(1, 1, 1)\n\nlet matrix = new Matrix4().compose(position, rotation, scale)\n\nbillboardReflection.createFromTextureAndMatrix(texture, matrix)\n```\nThis will give the same reflection as a mesh at the given position with the given rotation and scale.\n\n## Limitations\nThere are limitations regarding roughness and occlusion due to performance reasons.\n### Roughness\nProper roughness support is missing so reflections aren't blurred on rough surfaces but fade out.\nIf there's a roughness map then blur is achieved through using low-res mipmaps of a billboard texture\nfor rough spots which gives acceptable results when there aren't too many rough spots.\nThis does not work for video textures as these don't have mipmaps.\n\nIf your material has a roughness map but you don't want to use blur, then you can have it toggled off like so:\n```javascript\nmaterial.onBeforeCompile = shader =\u003e billboardReflection.enableReflection(shader, { roughnessMapBlur: false })\n```\nThis will now only make the reflection fade out for higher roughness values.\n\n### Occlusion\nThere's no occlusion check for reflections so they can be visible behind other meshes. This can\nbe counteracted by giving these meshes reflections too or increasing the reflection's `fallOff` value.\n\n## References\nPapers and articles\n- BBR algorithm: https://kola.opus.hbz-nrw.de/opus45-kola/frontdoor/deliver/index/docId/908/file/BA_GuidoSchmidt.pdf\n- Ray / triangle intersection: http://www.graphics.cornell.edu/pubs/1997/MT97.pdf\n- https://blog.selfshadow.com/publications/s2013-shading-course/karis/s2013_pbs_epic_notes_v2.pdf\n\nSlides\n- https://docs.unrealengine.com/udk/Three/rsrc/Three/DirectX11Rendering/MartinM_GDC11_DX11_presentation.pdf\n\n## Credits\n### Algorithm\n- [Guido Schmidt. Rendering view dependent reflections using the\ngraphics card](https://kola.opus.hbz-nrw.de/opus45-kola/frontdoor/deliver/index/docId/908/file/BA_GuidoSchmidt.pdf)\n\n### Demo Scene\n- Textures: https://ambientcg.com\n- HDR: https://polyhaven.com/hdris\n- Color Wheel Icon: https://www.freepik.com","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0beqz%2Fthree-billboard-reflection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0beqz%2Fthree-billboard-reflection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0beqz%2Fthree-billboard-reflection/lists"}