{"id":26324610,"url":"https://github.com/StrandedKitty/three-csm","last_synced_at":"2025-03-15T18:20:09.643Z","repository":{"id":47197883,"uuid":"214514966","full_name":"StrandedKitty/three-csm","owner":"StrandedKitty","description":"☀️ Cascaded shadow maps (CSMs) implementation for Three.js","archived":false,"fork":false,"pushed_at":"2023-12-11T11:05:16.000Z","size":706,"stargazers_count":314,"open_issues_count":10,"forks_count":25,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-12T23:45:53.900Z","etag":null,"topics":["shaders","threejs","webgl"],"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/StrandedKitty.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-11T19:32:55.000Z","updated_at":"2025-03-04T08:59:55.000Z","dependencies_parsed_at":"2023-02-19T00:25:20.537Z","dependency_job_id":"18060797-5790-4e1c-8ad3-75bfe20c3012","html_url":"https://github.com/StrandedKitty/three-csm","commit_stats":null,"previous_names":["vthawk/three-csm"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StrandedKitty%2Fthree-csm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StrandedKitty%2Fthree-csm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StrandedKitty%2Fthree-csm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StrandedKitty%2Fthree-csm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StrandedKitty","download_url":"https://codeload.github.com/StrandedKitty/three-csm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243681063,"owners_count":20330156,"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":["shaders","threejs","webgl"],"created_at":"2025-03-15T18:20:08.578Z","updated_at":"2025-03-15T18:20:09.637Z","avatar_url":"https://github.com/StrandedKitty.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# three-csm\n\nCascaded shadow maps (CSMs) implementation for [Three.js](https://threejs.org/). This approach provides higher resolution of shadows near the camera and lower resolution far away by using several shadow maps. CSMs are usually used for shadows cast by the sun over a large terrain.\n\n## Examples\n\n- [Basic](http://strandedkitty.github.io/three-csm/examples/basic/)\n\n![Cascaded Shadow Maps](https://i.imgur.com/YSvYi2g.png)\n\n## Installation\n\n```html\n\u003cscript src=\"/build/three-csm.js\"\u003e\u003c/script\u003e\n```\n\nUsing CommonJS:\n\n```\nnpm i three-csm\n```\n\n```javascript\nconst THREE = require('three');\nTHREE.CSM = require('three-csm');\n```\n\nUsing ES6 modules:\n\n```javascript\nimport * as THREE from 'three';\nimport CSM from 'three-csm';\nTHREE.CSM = CSM;\n```\n\n## Basic usage\n\n```javascript\nlet camera = new THREE.PerspectiveCamera(70, window.innerWidth / window.innerHeight, 0.1, 1000);\nlet renderer = new THREE.WebGLRenderer();\n\nrenderer.shadowMap.enabled = true;\nrenderer.shadowMap.type = THREE.PCFSoftShadowMap; // or any other type of shadowmap\n\t\nlet csm = new THREE.CSM({\n\tmaxFar: camera.far,\n\tcascades: 4,\n\tshadowMapSize: 1024,\n\tlightDirection: new THREE.Vector3(1, -1, 1).normalize(),\n\tcamera: camera,\n\tparent: scene\n});\n\nlet material = new THREE.MeshPhongMaterial(); // works with Phong and Standard materials\ncsm.setupMaterial(material); // must be called to pass all CSM-related uniforms to the shader\n\nlet mesh = new THREE.Mesh(new THREE.BoxBufferGeometry(), material);\nmesh.castShadow = true;\nmesh.receiveShadow = true;\n\nscene.add(mesh);\n```\n\nFinally, in your update loop, call the update function before rendering:\n\n```javascript\ncsm.update(camera.matrix);\n```\n\n## API\n\n### `CSM`\n\n### `constructor(settings: CSMParams)`\n\n**Parameters**\n\n- `settings` — `Object` which contains all setting for CSMs.\n\t\n\t- `settings.camera` — Instance of `THREE.PerspectiveCamera` which is currently used for rendering.\n\t\n\t- `settings.parent` — Instance of `THREE.Object3D` that will contain all directional lights.\n\t\n\t- `settings.cascades` — Number of shadow cascades. Optional.\n\n\t- `settings.maxCascades` — Maximum number of shadow cascades. Should be greater or equal to `cascades`. Important if you want to change the number of shadow cascades at runtime using `CSM.updateCascades()` method. Optional.\n\n\t- `settings.maxFar` — Frustum far plane distance (i.e. shadows are not visible farther this distance from camera). May be smaller than `camera.far` value. Optional.\n\n\t- `settings.mode` — Defines a split scheme (how large frustum is splitted into smaller ones). Can be `uniform` (linear), `logarithmic`, `practical` or `custom`. For most cases `practical` may be the best choice. Equations used for each scheme can be found in [*GPU Gems 3. Chapter 10*](https://developer.nvidia.com/gpugems/GPUGems3/gpugems3_ch10.html). If mode is set to `custom`, you'll need to define your own `customSplitsCallback`. Optional.\n\n\t- `settings.practicalModeLambda` — Lambda parameter for `practical` mode.  Optional.`\n\n\t- `settings.customSplitsCallback` — A callback to compute custom cascade splits when mode is set to `custom`. Callback should accept three number parameters: `cascadeCount`, `nearDistance`, `farDistance` and return an array of split distances ranging from 0 to 1, where 0 is equal to `nearDistance` and 1 is equal to `farDistance`. Check out the official modes in CSM.js to learn how they work.\n\t\n\t- `settings.shadowMapSize` — Resolution of shadow maps (one per cascade). Optional.\n\t\n\t- `settings.shadowBias` — Serves the same purpose as [THREE.LightShadow.bias](https://threejs.org/docs/#api/en/lights/shadows/LightShadow.bias). Gets multiplied by the size of a shadow frustum. Optional.\n \n\t- `settings.shadowNormalBias` — Serves the same purpose as [THREE.LightShadow.normalBias](https://threejs.org/docs/#api/en/lights/shadows/LightShadow.normalBias). Gets multiplied by the size of a shadow frustum. Optional.\n\n\t- `settings.lightIntensity` — Same as [THREE.DirectionalLight.intensity](https://threejs.org/docs/#api/en/lights/DirectionalLight). Optional.\n\n\t- `settings.lightColor` — Same as [THREE.DirectionalLight.color](https://threejs.org/docs/#api/en/lights/DirectionalLight). Optional.\n\t\n\t- `settings.lightDirection` — Normalized `THREE.Vector3()`. Optional.\n\t\n\t- `settings.lightDirectionUp` — Up vector used for `settings.lightDirection`. Optional, defaults to [THREE.Object3D.DEFAULT_UP](https://threejs.org/docs/?q=object#api/en/core/Object3D.DEFAULT_UP).\n\t\n\t- `settings.lightMargin` — Defines how far shadow camera is moved along z axis in cascade frustum space. The larger is the value the more space `LightShadow` will be able to cover. Should be set to high values for scenes with large or tall shadow casters. Optional.\n\n\t- `settings.fade` — If `true`, enables smooth transition between cascades. Optional.\n\n\t- `settings.noLastCascadeCutOff` — If `true`, disables cutting off the last cascade for better shadow coverage. Optional.\n\n### `setupMaterial(material: THREE.Material)`\n\nUpdates defines and uniforms of passed material. Should be called for every material which must use CSMs.\n\n**Parameters**\n\n- `material` — Material to add uniforms and defines to.\n\n### `update()`\n\nUpdates positions of frustum splits in world space. Should be called before every frame before rendering.\n\n### `updateFrustums()`\n\nRecalculates frustums for shadow cascades. Must be called after changing the camera projection matrix, split mode, `maxFar` or `shadowBias` settings.\n\n### `updateCascades(cascades: number)`\n\nUpdates number of shadow cascades, automatically recompiles all materials previously passed to `setupMaterial()`.\n\n**Parameters**\n\n- `cascades` — New number of shadow cascades.\n\n### `updateShadowMapSize(size: number)`\n\nUpdates shadow map size for all directional lights used by `CSM` instance.\n\n**Parameters**\n\n- `size` — New shadow map size.\n\n### `dispose()`\n\nRemoves and disposes all directional lights used by `CSM` instance.\n\n\n## Contributing\n\nFeel free to contribute. Use `npm run dev` to run a dev server.\n\n## References\n\n1. [Rouslan Dimitrov. *Cascaded ShadowMaps*](https://developer.download.nvidia.com/SDK/10.5/opengl/src/cascaded_shadow_maps/doc/cascaded_shadow_maps.pdf)\n2. [*Cascaded Shadow Maps* on Windows Dev Center](https://docs.microsoft.com/en-us/windows/win32/dxtecharts/cascaded-shadow-maps)\n3. [*3D Game Development with LWJGL 3. Cascaded Shadow Maps*](https://ahbejarano.gitbook.io/lwjglgamedev/chapter26)\n4. [*GPU Gems 3. Chapter 10*](https://developer.nvidia.com/gpugems/GPUGems3/gpugems3_ch10.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStrandedKitty%2Fthree-csm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FStrandedKitty%2Fthree-csm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStrandedKitty%2Fthree-csm/lists"}