From 9dc9b3342c6ab8004b3a4a6c5fd56e90c8159be9 Mon Sep 17 00:00:00 2001 From: Antoine BERNIER Date: Fri, 23 Aug 2024 10:06:51 +0200 Subject: [PATCH] docs: deprecated Hint (#3340) --- docs/API/canvas.mdx | 7 ++---- docs/API/events.mdx | 16 +++++--------- docs/API/hooks.mdx | 26 +++++++++-------------- docs/API/objects.mdx | 23 ++++++-------------- docs/advanced/scaling-performance.mdx | 16 +++++++------- docs/getting-started/installation.mdx | 6 ++---- docs/getting-started/your-first-scene.mdx | 16 ++++++-------- docs/tutorials/how-it-works.mdx | 3 ++- 8 files changed, 41 insertions(+), 72 deletions(-) diff --git a/docs/API/canvas.mdx b/docs/API/canvas.mdx index cdd71f4e0a..7dcb4dbd5e 100644 --- a/docs/API/canvas.mdx +++ b/docs/API/canvas.mdx @@ -96,11 +96,8 @@ function App() { } ``` - - -Ideally, and if possible, your fallback is a seamless, visual replacement for what the canvas would have otherwise rendered. - - +> [!NOTE] +> Ideally, and if possible, your fallback is a seamless, visual replacement for what the canvas would have otherwise rendered. ## Custom Canvas diff --git a/docs/API/events.mdx b/docs/API/events.mdx index 03eacb92e4..1286b16a11 100644 --- a/docs/API/events.mdx +++ b/docs/API/events.mdx @@ -47,21 +47,15 @@ Also notice the `onPointerMissed` on the canvas element, which fires on clicks t ### How the event-system works, bubbling and capture - +> [!NOTE] +> - `pointerenter` and `pointerleave` events work exactly the same as pointerover and pointerout. +> - `pointerenter` and `pointerleave` semantics are not implemented. -`pointerenter` and `pointerleave` events work exactly the same as pointerover and pointerout. -`pointerenter` and `pointerleave` semantics are not implemented. - - - - - -Some events (such as `pointerout`) happen when there is no intersection between `eventObject` and +> [!NOTE] +> Some events (such as `pointerout`) happen when there is no intersection between `eventObject` and the ray. When this happens, the event will contain intersection data from a previous event with this object. - - ### Event propagation (bubbling) Propagation works a bit differently to the DOM because objects can occlude each other in 3D. The `intersections` array in the event includes all objects intersecting the ray, not just the nearest. Only the first intersection with each object is included. diff --git a/docs/API/hooks.mdx b/docs/API/hooks.mdx index 5cba962dc2..281e0727da 100644 --- a/docs/API/hooks.mdx +++ b/docs/API/hooks.mdx @@ -6,7 +6,8 @@ nav: 7 Hooks allow you to tie or request specific information to your component. For instance, components that want to participate in the renderloop can use `useFrame`, components that need to be informed of three.js specifics can use `useThree` and so on. All hooks clean up after themselves once the component unmounts. -Hooks can only be used inside the Canvas element because they rely on context! +> [!NOTE] +> Hooks can only be used inside the Canvas element because they rely on context! ❌ You cannot expect something like this to work: @@ -123,10 +124,9 @@ function Foo() { }) ``` - - Be careful about what you do inside useFrame! You should never setState in there! Your calculations should be slim and +> [!CAUTION] +> Be careful about what you do inside useFrame! You should never setState in there! Your calculations should be slim and you should mind all the commonly known pitfalls when dealing with loops in general, like re-use of variables, etc. - ### Taking over the render-loop @@ -146,10 +146,8 @@ function RenderOnTop() { }, 2) ``` - - Callbacks will be executed in order of ascending priority values (lowest first, highest last.), similar to the DOM's - z-order. - +> [!NOTE] +> Callbacks will be executed in order of ascending priority values (lowest first, highest last.), similar to the DOM's z-order. ### Negative indices @@ -190,15 +188,11 @@ function App() { } ``` - - Assets loaded with useLoader are cached by default. The urls given serve as cache-keys. This allows you to re-use - loaded data everywhere in the component tree. - +> [!NOTE] +> Assets loaded with useLoader are cached by default. The urls given serve as cache-keys. This allows you to re-use loaded data everywhere in the component tree. - - Be very careful with mutating or disposing of loaded assets, especially when you plan to re-use them. Refer to the - automatic disposal section in the API. - +> [!NOTE] +> Be very careful with mutating or disposing of loaded assets, especially when you plan to re-use them. Refer to the automatic disposal section in the API. ### Loader extensions diff --git a/docs/API/objects.mdx b/docs/API/objects.mdx index e1a4bc04d2..0a0ee08932 100644 --- a/docs/API/objects.mdx +++ b/docs/API/objects.mdx @@ -49,12 +49,8 @@ All properties whose underlying object has a `.set()` method can directly receiv ``` - - If you do link up an existing object to a property, for instance a THREE.Vector3() to a position, be aware that this - will end up copying the object in most cases as it calls .copy() on the target. This only applies to objects that - expose both .set() and .copy() (Vectors, Eulers, Matrix, ...). If you link up an existing material or geometry on the - other hand, it will overwrite, because more these objects do not have a .set() method. - +> [!NOTE] +> If you do link up an existing object to a property, for instance a THREE.Vector3() to a position, be aware that this will end up copying the object in most cases as it calls .copy() on the target. This only applies to objects that expose both .set() and .copy() (Vectors, Eulers, Matrix, ...). If you link up an existing material or geometry on the other hand, it will overwrite, because more these objects do not have a .set() method. ### SetScalar @@ -91,12 +87,8 @@ The following attaches a material to the `material` property of a mesh and a geo ``` - - -All objects extending `THREE.Material` receive `attach="material"`, and all objects extending `THREE.BufferGeometry` receive -`attach="geometry"`. You do not have to type it out! - - +> [!NOTE] +> All objects extending `THREE.Material` receive `attach="material"`, and all objects extending `THREE.BufferGeometry` receive `attach="geometry"`. You do not have to type it out! ```jsx @@ -180,11 +172,8 @@ function Component() { return ``` - - -Scene objects can only ever be added once in Threejs. If you attempt to add one and the same object in two places Threejs will remove the first instance automatically. This will also happen with primitive! If you want to re-use an existing object, you must clone it first. - - +> [!NOTE] +> Scene objects can only ever be added once in Threejs. If you attempt to add one and the same object in two places Threejs will remove the first instance automatically. This will also happen with primitive! If you want to re-use an existing object, you must clone it first. ## Using 3rd-party objects declaratively diff --git a/docs/advanced/scaling-performance.mdx b/docs/advanced/scaling-performance.mdx index 45d8dc4ea0..3dba29f0a7 100644 --- a/docs/advanced/scaling-performance.mdx +++ b/docs/advanced/scaling-performance.mdx @@ -37,7 +37,8 @@ function Controls() { return ``` -Drei's controls do this automatically for you. +> [!NOTE] +> Drei's controls do this automatically for you. Generally you can call invalidate whenever you need to render: @@ -45,14 +46,11 @@ Generally you can call invalidate whenever you need to render: invalidate() ``` - - -Calling `invalidate()` will not render immediately, it merely requests a +> [!IMPORTANT] +> Calling `invalidate()` will not render immediately, it merely requests a new frame to be rendered out. Calling invalidate multiple times will not render multiple times. Think of it as a flag to tell the system that something has changed. - - ### Sync animations with on-demand-rendering and invalidate Since `invalidate()` is only a flag that schedules render, you might bump into syncing issues when you run animations that are synchronous (as in, they start immediately). By the time fiber renders the first frame the animation has already progressed which leads to a visible jump. In such cases you should pre-emptively schedule a render and then start the animation in the next frame. @@ -98,7 +96,8 @@ THREE.ColorManagement.legacyMode = false ### Caching with useLoader -Every resource that is loaded with useLoader is cached automatically! +> [!NOTE] +> Every resource that is loaded with useLoader is cached automatically! If you access a resource via useLoader with the same URL, throughout the component tree, then you will always refer to the same asset and thereby re-use it. This is especially useful if you run your GLTF assets through [GLTFJSX](https://github.com/pmndrs/gltfjsx) because it links up geometries and materials and thereby creates re-usable models. @@ -298,7 +297,8 @@ useEffect(() => { ### This is how you can respond to it -Mere calls to `regress()` will not change or affect anything! +> [!NOTE] +> Mere calls to `regress()` will not change or affect anything! Your app has to opt into performance scaling by listening to the performance `current`! The number itself will tell you what to do. 1 (max) means everything is ok, the default. Less than 1 (min) means a regression is requested and the number itself tells you how far you should go when scaling down. diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx index 0fefd0f737..a137ed65df 100644 --- a/docs/getting-started/installation.mdx +++ b/docs/getting-started/installation.mdx @@ -184,10 +184,8 @@ module.exports = { R3F's API is completely x-platform, so you can use [events](https://docs.pmnd.rs/react-three-fiber/api/events) and [hooks](https://docs.pmnd.rs/react-three-fiber/api/hooks) just as you would on the web. - - Make sure to import from `@react-three/fiber/native` or `@react-three/drei/native` for correct IntelliSense and - platform-specific abstractions. - +> [!NOTE] +> Make sure to import from `@react-three/fiber/native` or `@react-three/drei/native` for correct IntelliSense and platform-specific abstractions. ```jsx import { Suspense } from 'react' diff --git a/docs/getting-started/your-first-scene.mdx b/docs/getting-started/your-first-scene.mdx index 0cf27c7fac..1ecb7a461c 100644 --- a/docs/getting-started/your-first-scene.mdx +++ b/docs/getting-started/your-first-scene.mdx @@ -30,10 +30,8 @@ The Canvas component does some important setup work behind the scenes: - It sets up a **Scene** and a **Camera**, the basic building blocks necessary for rendering - It renders our scene every frame, you do not need a traditional render-loop - - Canvas is responsive to fit the parent node, so you can control how big it is by changing the parents width and - height, in this case #canvas-container. - +> [!NOTE] +> Canvas is responsive to fit the parent node, so you can control how big it is by changing the parents width and height, in this case #canvas-container. ## Adding a Mesh Component @@ -44,11 +42,8 @@ To actually see something in our scene, we'll add a lowercase `` native ``` - - Note that we don't need to import anything, All three.js objects will be treated as native JSX elements, just like you - can just write <div /> or <span /> in regular ReactDOM. The general rule is that Fiber components are - available under the camel-case version of their name in three.js. - +> [!NOTE] +> Note that we don't need to import anything, All three.js objects will be treated as native JSX elements, just like you can just write <div /> or <span /> in regular ReactDOM. The general rule is that Fiber components are available under the camel-case version of their name in three.js. A [`Mesh`](https://threejs.org/docs/#api/en/objects/Mesh) is a basic scene object in three.js, and it's used to hold the geometry and the material needed to represent a shape in 3D space. We'll create a new mesh using a **BoxGeometry** and a **MeshStandardMaterial** which [automatically attach](https://docs.pmnd.rs/react-three-fiber/api/objects#attach) to their parent. @@ -100,7 +95,8 @@ In order to do this in Fiber we use the `args` prop, which _always_ takes an arr ``` -Note that every time you change args, the object must be re-constructed! +> [!NOTE] +> Note that every time you change args, the object must be re-constructed! ## Adding lights diff --git a/docs/tutorials/how-it-works.mdx b/docs/tutorials/how-it-works.mdx index 8a8c344c0d..eb8ff5478a 100644 --- a/docs/tutorials/how-it-works.mdx +++ b/docs/tutorials/how-it-works.mdx @@ -75,7 +75,8 @@ Object creation is handled transparently by the Fiber renderer, the name of the ``` -Note that the object will be created only when first adding the component to the React tree! +> [!NOTE] +> Note that the object will be created only when first adding the component to the React tree! ## The `attach` props