Programarea aplicației

Pentru a simplifica procesul de programare, vă recomandăm să utilizați Project Manager. Acesta poate fi folosit pentru a crea rapid o aplicație simplă cu un cod generic care este suficient pentru a încărca o scenă simplă și pentru a activa comenzile de bază ale obiectului Camera.

Structura codului aplicației

Procesul de inițializare și încărcare a unei aplicații este separat în mai multe etape, lucru care se reflectă în codul aplicației. Dacă utilizați Project Manager, un proiect nou creat de tip Copy sau Compile va include un fișier principal JS care va fi plasat în SDK. Calea către fișier poate arăta astfel:

./projects/PROJECT_NAME/PROJECT_NAME.js

Acest fișier conține cod generic în formă de modul. Modulul poate fi înregistrat utilizând o anumită structură:

b4w.register("my_module", function(exports, require) {

// module code

//...

}); 

Deci, codul unui modul este conținut într-o funcție care acceptă exporturile și necesită parametri.

1. este necesară metoda utilizată pentru încărcarea modulelor motorului. Exemplul generic menționat mai sus încarcă mai multe module: cele mai importante dintre acestea sunt modulele de aplicații și de date. Modulul app simplifică inițializarea aplicației, iar modulul de date conține metode API pentru încărcarea datelor din scena 3D.

Notă: Pentru a face denumirea modulului mai convenabilă, este adesea folosit prefixul m_ (m_app, m_data etc.) pentru a arăta că variabila este un modul al motorului.

2. exports este un obiect folosit pentru a obține accesul la funcțiile modulului din exterior (de exemplu, din alte module). În acest caz, a fost făcută externă numai funcția inițială:

b4w.register("my_module", function(exports, require) {

...

exports.init = function() {

m_app.init({

canvas_container_id: "main_canvas_container",

callback: init_cb,

show_fps: DEBUG,

console_verbose: DEBUG,

autoresize: true

});

}

...

});

Inițializarea aplicației începe cu această funcție și este apelată în afara modulului:

b4w.register("my_module", function(exports, require) {

...

exports.init = function() {

m_app.init({

canvas_container_id: "main_canvas_container",

callback: init_cb,

show_fps: DEBUG,

console_verbose: DEBUG,

autoresize: true

});

}

...

});

// import the app module and start the app by calling the init method

b4w.require("my_module").init();

Apoi, este apelată metoda app.init. Ea creează elementul Canvas HTML și efectuează toate acțiunile necesare inițializării WebGL. Această metodă are multe atribute diferite, dintre care cele mai importante sunt:

• canvas_container_id setează id-ul elementului HTML care acționează ca un container pentru elementul Canvas. În mod implicit, este utilizat un element cu ID-ul main_canvas_container (acest element este localizat în fișierul HTML principal al aplicației).

• callback este funcția apelată după terminarea inițializării.

Când se finalizează inițializarea aplicației, este apelată funcția init_cb setată de parametrul callback:

function init_cb(canvas_elem, success) {

if (!success) {

console.log("b4w init failure");

return;

}

m_preloader.create_preloader();

// ignore right-click on the canvas element

canvas_elem.oncontextmenu = function(e) {

e.preventDefault();

e.stopPropagation();

return false;

};

load();

}

Are următorii parametri:

• canvas_elem este elementul Canvas HTML creat care va fi utilizat pentru redarea conținutului 3D

• success este parametrul (flag) care indică succesul inițializării. Valoarea false înseamnă că aplicația nu poate funcționa din cauza erorilor de inițializare (de exemplu, WebGL nu este acceptat de dispozitiv).

Notă: Metodele app.init setează inițializarea ferestrei, a evenimentului onload, astfel ca funcția init_cb să aibă acces la întreaga structură DOM a documentului HTML.

Acum începe încărcarea scenei 3D. Încărcarea se face în funcția load, care este apelată de init_cb:

var APP_ASSETS_PATH = m_cfg.get_assets_path("my_project");

...

function load() {

m_data.load(APP_ASSETS_PATH + "my_project.json", load_cb, preloader_cb);

}

Metoda data.load este folosită la încărcarea datelor. Primul parametru al acestei metode este calea către un fișier de scenă 3D. Calea spre un fișier JSON trebuie să fie relativă la fișierul de aplicație HTML principal. Proiectele create în Project Manager au un folder de materiale dedicat și puteți obține cu ușurință calea către acesta. Acest lucru se face în exemplul generic de cod prin introducerea variabilei globale APP_ASSETS_PATH care este ulterior utilizată în data.load.

Al doilea parametru al metodei este funcția load_cb care este apelată după ce scena 3D este încărcată și pregătită pentru randare.

function load() {

m_data.load(APP_ASSETS_PATH + "my_project.json", load_cb, preloader_cb);

}

function load_cb(data_id, success) {

if (!success) {

console.log("b4w load failure");

return;

}

m_app.enable_camera_controls();

// place your code here

}

Apelarea acestei funcții înseamnă că aplicația s-a terminat de încărcat și începe randarea scenelor. Deoarece acesta este primul moment în care vor fi disponibile datele de scenă 3D, este un moment potrivit pentru inițierea și pregătirea a tot ceea ce este legat de scenă, obiect, animații și alte lucruri. De exemplu, comenzile standard ale camerei pot fi activate aici cu ajutorul metodei de activare a comenzilor camerei enable camera controls.

Scrierea logicii aplicației

După inițializarea și încărcarea scenei 3D, aplicația va continua să funcționeze conform logicii stabilite de programator, cum ar fi interacțiunea cu dispozitivele de intrare, manipularea obiectelor de scenă, controlul comportamentului camerei și așa mai departe.

Observând procesul de încărcare a aplicației, putem determina mai multe locuri potrivite pentru efectuarea diferitelor sarcini.

1. Metoda app.init folosită pentru pentru pornirea inițializării acceptă parametrii de configurare a motorului. Deci, puteți configura motorul înainte de a apela această metodă folosind atributele URL ca bază:

b4w.register("my_module", function(exports, require) {

...

exports.init = function() {

var url_params = m_app.get_url_params();

if (url_params && "show_fps" in url_params)

var show_fps = true;

else

var show_fps = false;

m_app.init({

canvas_container_id: "main_canvas_container",

callback: init_cb,

autoresize: true

show_fps: show_fps

});

}

...

});

b4w.require("my_module").init();

2. Inițializarea este pornită de către fereastră, acțiunea de încărcare onload, ceea ce înseamnă că după ce este terminată, funcția init_cb va avea acces la întregul arbore DOM. În acest moment, puteți efectua deja unele pregătiri, cum ar fi crearea și configurarea elementelor de interfață. Cu toate acestea, scena 3D în sine nu este încă încărcată, iar obiectele acesteia nu sunt încă disponibile.

3. După încărcarea scenei 3D, este apelată funcția load_cb. În acest moment, toate obiectele din scenă devin disponibile, astfel încât orice acțiune care le privește poate fi implementată în această funcție. Unele exemple pot fi găsite în aplicația Code Snippets.

Logica poate fi adăugată la aplicație utilizând fie browserul, fie API-ul motorului:

1. Introducerea de bază a datelor de intrare folosind tastatura / mouse-ul / gamepad-ul poate fi implementată cu manipulatoare standard de eveniment (standard event handlers) folosind metoda addEventListener. În cazuri mai complexe puteți utiliza modulul API input. Motorul include, de asemenea, metoda add_click_listener care înregistrează clicurile de mouse și evenimentele pe ecranul tactil, lucru care o face utilă la realizarea aplicațiilor compatibile atât pe dispozitive desktop cât și pe dispozitive mobile.

2. Evenimentele care au loc în timp și care trebuie efectuate la fiecare cadru (animație procedurală, de exemplu) pot fi implementate cu metode cum ar fi set_render_callback, append_loop_cb, animate și set_timeout.

Pot fi utilizate și metodele Standard setTimeout și setInterval.

3. Pentru logica complexă care ia în considerare atât acțiunile utilizatorilor, cât și starea scenei 3D se poate folosi modelul motorului bazat pe evenimente care se bazează pe sistemul de senzori.

Sistem modular

Motorul Blend4Web este construit pe baza unei structuri modulare: toate metodele API ale motorului sunt separate în mai multe module. Dacă este necesar, un modul poate fi conectat la aplicație cu ajutorul metodei necesare. Vă recomandăm să structurați codul aplicației actuale și în module.

1. Înregistrarea modulelor

Un modul este în esență un bloc de coduri inclus într-o structură specifică utilizată pentru înregistrarea acestuia:

b4w.register("my_module1", function(exports, require) {

// module code

...

});

b4w.register("my_module2", function(exports, require) {

// module code

...

});

... 

Metoda register este utilizată pentru înregistrarea modulelor. Puteți înregistra module personalizate numai dacă numele lor nu coincid cu modulele API obișnuite. Dacă este necesar, folosiți metoda module_check pentru a verifica dacă există un modul cu un nume dat:

if (b4w.module_check("my_module"))

throw "Failed to register module: my_module";

b4w.register("my_module", function(exports, require) {

// module code

...

});

2. Încărcarea modulelor

Modulele personalizate, la fel ca cele obișnuite, pot fi conectate prin metoda necesară:

b4w.register("my_module1", function(exports, require) {

var mod2 = require("my_module2")

...

});

3. Inițializarea aplicației

Inițializarea aplicației în Blend4Web se face de obicei cu un apel ca acesta:

b4w.require("my_module").init();

Aici, modulul personalizat my_module și funcția sa externă init acționează, într-un anumit sens, ca punct de intrare în aplicație.

Notă: Pentru ca modulul să aibă vizibilitate globală, el poate fi încărcat cu aceeași metodă require folosită și de obiectul global b4w: b4w.require("MODULE_NAME").

4. Utilizarea modulelor multiple

După ce un proiect este creat în Managerul de proiect, aplicația generică JS-file va conține un singur modul. Cu toate acestea, în timp ce dezvoltați aplicația, este posibil să aveți nevoie să separați codul în mai multe părți logice. În acest caz, puteți crea mai multe module în interiorul unui fișier sau puteți crea mai multe fișiere, fiecare dintre ele conținând câte un modul.

Dacă aplicația dvs. folosește mai multe module, rețineți că fiecare dintre ele trebuie să fie înregistrat corespunzător înainte de începerea inițializării, altfel veți avea o eroare de motor dacă încercați să apelați un modul care nu este încă înregistrat. Dacă utilizați mai multe fișiere JS, scriptul care inițiază inițializarea (conține punctul de intrare al aplicației) ar trebui să fie conectat ultimul în fișierul principal de aplicație HTML.