holodepth

Framework entegrasyonları · React Three Fiber

Canvas & Kök Sözleşme: Sahnenin Gümrük Kapısı

<Canvas> bir mesheden önce gelen kök sözleşmedir: WebGL bağlamını kim açar, boyut ve DPR kim yazar, kare ritmi kim onaylar, unmount'ta kim temizler. Bu sayfa JSX veya hook temeli öğretmez; React varsayılır · kapı kilidini anlatır.

Holodepth bu yaprağı «hello cube» turu veya React Vitae'nin bileşen dilinin tekrarı olarak yazmaz. Bakış açısı: imperatif Three kökü ile R3F Canvas'ının diplomatik farkı. Mesh / materyal / buffer teorisi Three.js ve WebGL omurgasındadır; kare milisaniye SLA'sı Platform · FPS mantığı yaprağındadır. JSX ile sahne grafı yazmak sonraki R3F yaprağındadır. glTF paket şeması veya loader sözleşmesi bu kapının konusu değildir.

Sayfayı bitirdiğinizde şu cümleyi kurabilmelisiniz: «Canvas, React ağacı ile GPU bağlamı arasındaki tek gümrük kapısıdır. Boyut ve DPR CSS kutusundan ayrı yazılır. frameloop ürün politikasıdır. gl bayrakları renderer imzasını mühürler. İkinci Canvas ikinci context demektir. Mount/unmount bağlam ömrünü yönetir. Sonraki kapı deklaratif sahne grafıdır.»

Bu sayfanın sınırı · komşu konularla ayrım

Bu sayfa R3F'de Canvas kök sözleşmesini anlatır:

  • Context tekelliği · host DOM yerleşimi
  • size / dpr · frameloop
  • gl imzası · güvenli mount / unmount
  • Üç kök profili (vitrin / panel / tam ekran)

Bilinçli olarak dışarıda bırakılan konular:

Kısa ayrım: Bu sayfa «kapı nasıl mühürlenir?» · Deklaratif graf «kapının arkasında ne yazılır?» · useFrame «kapı açıkken kim tik atar?» · Platform FPS «tik'in ms bütçesi».

Kök sözleşme: gümrük kapısı

Imperatif Three'de çoğu ekip new WebGLRenderer({ canvas }), bir Scene, bir Camera ve kendi requestAnimationFrame döngüsünü elle bağlar. R3F'de bu torba <Canvas> altına toplanır: React çocukları Three nesnelerine çevrilmeden önce bağlam, boyut, döngü ve olay kökü mühürlenir.

Kapı metaforu bilinçlidir. Mesh'i yanlış yazmak sahneyi bozar; kökü yanlış mühürlemek ise tüm oturumu bozar: bulanık çıktı, çift context, sessiz kare durması, unmount sonrası sızıntı. Holodepth: önce kapı, sonra kargo.

Sahne grafı yük taşır; kök sözleşme gümrük mührüdür.

Imperatif kök ile Canvas diplomasi

İkisi de aynı GPU API'ye yaslanır. Fark, yetki dağılımıdır: imperatif kökte resize, pixel ratio, tone mapping ve dispose sizin elinizdedir; Canvas'ta varsayılanlar R3F'nin kök imzasından gelir ve prop'larla bilinçli olarak ezilir. «Sihir» yoktur: ezmediğiniz her şey varsayılandır; varsayılan ürün değildir.

Holodepth üretiminde karar cümlesi şudur: R3F kullanıyorsanız kök davranışını Canvas prop'larında yazın; imperatif kaçış sonraki yaprakta konuşulur. İkisini de yarıda bırakmak («biraz R3F, biraz elle setSize») çift kaynaktan beslenen kırılgan bir köprü üretir.

React'e özel dil (props drilling, Context Provider temeli) buranın dersi değildir. Buranın dersi: hangi API yüzeyi kök imzasını taşır?

Tek context · çok Canvas tuzağı

Her <Canvas> tipik olarak kendi WebGLRenderer / WebGL bağlamını açar. Sayfada üç küçük vitrin = üç context; mobil GPU'da bu, ürün kararından önce bütçe felaketidir. Holodepth kuralı: mümkün olduğunca tek canlı Canvas; ikinci kök ancak bilinçli ürün ihtiyacıysa (ör. ayrı HUD ile tam ayrı GPU oturumu) açılır.

Alternatifler kök sözleşmenin parçasıdır: tek Canvas içinde birden fazla kamera / katman; veya UI'yi DOM'da tutup 3D'yi tek panoya bağlamak. «Her kart kendi Canvas'ı» pazarlama demosunda hoş, üretimde pahalıdır.

  • Paylaşılan doku / FBO: ikinci kökten daha zor ama çoğu zaman daha ucuz (derinlik Three/WebGL omurgasında).
  • Gizli sekme: arka planda boşta dönen ikinci Canvas, pil ve termal bütçeyi yer.
  • SSR / hydration: kök yalnızca istemcide açılmalı; sunucuda WebGL yoktur (React SSR stratejisi Vitae'ye aittir; burada yalnızca «Canvas client-only» kuralı mühürlenir).

Boyut ve DPR: iki defter

CSS kutusu (layout px) ile çizim tamponu (backing store) aynı şey değildir. Retina / yüksek DPI'de devicePixelRatio 2 veya 3 olabilir; tamponu sınırsız şişirmek fill-rate'i yakar. R3F dpr prop'u bu diplomasiyi mühürler: çoğu ürün dpr={[1, 2]} gibi bir tavan yazar.

size / yeniden boyut: Canvas host'unun layout'u değişince renderer setSize yoluna düşer. Host'u height: 0 veya yüzde/flex hatasında bırakmak «siyah kutu» veya 1×1 tampon üretir. Holodepth: host'a açık yükseklik sözleşmesi verin; sonra Canvas'ın boyut gözlemcisinin çalışmasına izin verin.

İki defter · karıştırmayın
Defter Ne ölçer? Kök kararı
CSS / layout Host kutunun ekrandaki yeri Flex/grid · min-height · aspect
Backing store Gerçek piksel tamponu dpr tavanı · setSize
Görsel keskinlik Kullanıcının algıladığı netlik DPR ↑ maliyeti ↑; tavan ürün kararı

Platform FPS yaprağı ms bütçesini anlatır; burada yalnızca şunu mühürleriz: kökte yanlış DPR, bütçeyi daha semptom görmeden yakar.

frameloop: her zaman mı, talepte mi?

Varsayılan sürekli döngü vitrinde doğaldır; dashboard paneli veya durağan ürün görselinde israftır. R3F frameloop kök politikasıdır:

  • always: sürekli tik · animasyon / orbit canlılığı
  • demand: yalnızca geçersizkılınca çizer · invalidate() ile uyanır
  • never: elle yönetilen uç senaryo · nadiren ürün varsayılanı

Holodepth: panelli UI + seyrek güncellemede demand varsayılan adayıdır; sürekli motion'ta always. Bu seçim useFrame yazmayı öğretmez (sonraki yaprak); kökte hangi metronomun çalışacağını seçer. Ms SLA ve jank politikası Platform FPS yaprağındadır.

Boşta dönen Canvas, sessizce yanan bir bütçedir.

gl kapısı: renderer imzası

gl prop'u (veya eşdeğeri kök ayarları) antialiasing, powerPreference, alpha, preserveDrawingBuffer gibi bağlam oluşturma kararlarını taşır. Tone mapping / outputColorSpace gibi renderer imza alanları da kökte bilinçli mühürlenmelidir; aksi hâlde her sahne «neden gri / neden yanık?» tartışmasına düşer.

Holodepth kuralı: renk uzayı ve tone mapping'i ürün sabitleri gibi kökte yazın; her mesh'te rastgele değiştirmek yerine tek kapıdan geçirin. Shader/PBR teorisi WebGL ve materyal omurgasındadır; burada yalnızca imzanın nerede mühürlendiği netleşir.

shadows, flat, linear gibi kök bayrakları da aynı diplomasiye aittir: varsayılanı ezmeden «neden gölge yok?» demek, kapıyı okumamaktır.

Host DOM: Canvas'ın oturduğu kutu

Canvas bir React çocuğu olarak bir host'a yerleşir. Host'un position, overflow, aspect-ratio ve pointer-events politikası, 3D olay kökünün çalışıp çalışmayacağını belirler. Host
display: none iken boyut sıfırlanır; tekrar görünür olduğunda resize yolunun tetiklenmesi gerekir.

Layout thrashing: stil değişiminde her karede host ölçüsü okuyup yazmak ana iş parçacığını yer. Kök yerleşimi mümkün olduğunca kararlı tutun; animasyonu Three tarafında (sonraki yapraklar) veya CSS transform ile host'u sürekli ölçtürmeden taşıyın.

Erişilebilirlik ve odak: 3D vitrin çoğu zaman fare/dokunmatik odaklıdır; klavye ve azaltılmış hareket tercihleri ürün politikasına aittir. Holodepth: kök host'a anlamlı bir etiket / rol stratejisi düşünün; «kör tuval» üretmeyin. Pointer picking derinliği ayrı R3F yaprağındadır.

Güvenli kök: simüle mühür

Aşağıdaki örnekler öğretim amaçlı, güncel R3F yüzeyine yaslanan simüle kalıplardır. Sürüm API'si değişebilir; projede paket sürümünüzü doğrulayın. React kurulumu, Vite iskeleti veya hook temeli anlatılmaz.

Simüle · vitrin kökü (sürekli döngü + DPR tavanı). children, host kutusu ve Canvas önceden ürün ağacına bağlanmış kabul edilir. 

import { Canvas } from '@react-three/fiber'

export function ProductStage({ children }) {
  return (
    <div className="r3f-host" style={{ width: '100%', height: '100%', minHeight: 360 }}>
      <Canvas
        dpr={[1, 2]}
        frameloop="always"
        gl={{
          antialias: true,
          alpha: false,
          powerPreference: 'high-performance',
          // Eğitim notu: preserveDrawingBuffer yalnızca ekran görüntüsü ihtiyacında.
          preserveDrawingBuffer: false,
        }}
        camera={{ position: [0, 1.4, 4], fov: 42, near: 0.1, far: 200 }}
        onCreated={({ gl }) => {
          // Kök imza: renk uzayı / tone mapping ürün sabitine bağlanır.
          gl.outputColorSpace = 'srgb'
          gl.toneMapping = 4 // THREE.ACESFilmicToneMapping (sürüme göre import edin)
        }}
      >
        {children}
      </Canvas>
    </div>
  )
}

Simüle · panel kökü (demand · boşta çizme). Veri seed değişince kök invalidate ile uyanır. 

import { Canvas, useThree } from '@react-three/fiber'
import { useEffect } from 'react'

function WakeOnProp({ seed }) {
  const invalidate = useThree((s) => s.invalidate)
  useEffect(() => {
    invalidate()
  }, [seed, invalidate])
  return null
}

export function DashboardPanel({ seed, children }) {
  return (
    <div className="r3f-host r3f-host--panel" style={{ height: 240 }}>
      <Canvas
        dpr={[1, 1.5]}
        frameloop="demand"
        gl={{ antialias: true, alpha: true, powerPreference: 'default' }}
        orthographic
        camera={{ position: [0, 0, 10], zoom: 48 }}
      >
        <WakeOnProp seed={seed} />
        {children}
      </Canvas>
    </div>
  )
}

Unmount: rota değişiminde Canvas ağaçtan düşer; R3F renderer'ı ve GL kaynaklarını salmaya çalışır. Yine de kök dışında elle eklediğiniz listener / worker / paylaşılmış texture referansları sizin borcunuzdur. «loseContext» ve sekme gizleme politikası ürün kontrol listesine yazılır.

Güvenlik notu: kullanıcıya açık URL'den shader / model çekmek kök sözleşmenin değil asset borusunun işidir; yine de Canvas host'unda CORS ve crossOrigin hataları siyah ekran üretebilir. Loader derinliği yükleme yaprağındadır.

Üç kök profili

Aynı Canvas API'si üç farklı mühür ister. Profil seçmeden «best practice» ezberlemek kırılganlık üretir.

  • 01 · Kök

    Vitrin / ürün sahnesi

    frameloop
    always (canlı orbit / idle motion)
    dpr
    [1, 2] · keskinlik öncelikli
    Risk
    İkinci Canvas ile kart ızgarası
  • 02 · Kök

    Dashboard paneli

    frameloop
    demand + veri değişince invalidate
    dpr
    [1, 1.5] · dolgu maliyeti düşük
    Risk
    Boşta always bırakmak
  • 03 · Kök

    Tam ekran deneyim

    Host
    Viewport kilidi · sabit min-height
    gl
    high-performance · alpha bilinçli
    Risk
    DPR 3 sınırsız · termal boğulma

Varsayılan kamera ve ışık: imza mı yük mü?

Canvas çoğu kurulumda bir kamera (ve isteğe bağlı ışık yardımcıları) ile ayağa kalkar. Holodepth: varsayılan kamerayı «geçici iskele» kabul edin; ürün kamerasını kökte veya sahne grafında bilinçli yazın. İki aktif kamera çakışması sessiz kırılmalara yol açar.

Işık: kökte «her şeyi aydınlatan» varsayılan ile sahne içi ışık hiyerarşisini karıştırmayın. PBR ve ışık teorisi Three/WebGL yapraklarındadır; burada yalnızca şunu mühürleriz: görünürlük politikası kökte mi, sahnede mi yazılacak? Cevabı ürün sözleşmesine tek satır olarak koyun.

Holodepth perspektifleri

Önce kapı, sonra kargo

Mesh optimize etmek, kötü mühürlü kökün üstüne parfümdür. Context, DPR, frameloop ve host önce gelir.

Bir Canvas varsayılan, ikinci istisna

İkinci kökü «kolay» diye açmayın; GPU kontenjanı üründür.

İki defteri ayırın

Layout px ile backing store px aynı cümlede konuşulmamalı; DPR tavanı ürün sabitidir.

Teşhis maddeleri

  1. Sayfada kaç canlı Canvas var? Her biri gerekçeli mi?
  2. Host'un min-height / aspect sözleşmesi yazılı mı?
  3. dpr tavanı var mı, yoksa device sınırsız mı?
  4. frameloop ürün profiline uyuyor mu?
  5. gl / colorSpace / tone mapping kökte mühürlü mü?
  6. preserveDrawingBuffer bilinçli mi, yoksa tesadüf mü?
  7. Unmount'ta kök dışı dinleyiciler temizleniyor mu?
  8. React temeli veya glTF şeması bu sayfaya sızmış mı?

Holodepth içgörüsü

«Canvas koydum çalışmadı» çoğu zaman mesh hatası değil, kök sözleşmesi hatasıdır: sıfır yükseklik, çift context, yanlış frameloop veya mühürlenmemiş renk imzası. Kapıyı okuyun.

Sonraki kapı: deklaratif sahne grafı

Kök mühürlendikten sonra soru şudur: JSX çocukları Three nesnelerine nasıl bağlanır, prop hangi constructor / hangi runtime alanına gider? Sonraki sayfa Deklaratif sahne grafı bu haritayı anlatır. useFrame, yükleme ve picking sonraki yapraklardadır.