Object.cpp 14.9 KB
Newer Older
1
#include "Object.h"
Anakin's avatar
Anakin committed
2
#include <iostream>
Anakin's avatar
Anakin committed
3
4


Anakin's avatar
Anakin committed
5
#define PI (4.0*atan(1.0))
6
7
8
9
10


/////////////////////////////////////////////////////////////////////////
// public constructor/destructor

Anakin's avatar
Anakin committed
11
Object::Object(const char* path)
12
{
Anakin's avatar
Anakin committed
13
	// open file
14
	fsMesh.open(path, std::ios::in | std::ios::binary);
15

Anakin's avatar
Anakin committed
16
17
	if (!fsMesh.is_open())
		throw std::invalid_argument(std::string("file not found: ") += path);
18

19
20
	// jump to file size information
	fsMesh.seekg(4);
21

22
23
	std::uint32_t tempFileSize;
	std::list<ChunkHeader*> tempMainChunks;
24

25
26
27
	// get all chunks under HEDR
	fsMesh.read(reinterpret_cast<char*>(&tempFileSize), sizeof(tempFileSize));
	loadChunks(tempMainChunks, fsMesh.tellg(), tempFileSize);
28

Anakin's avatar
Anakin committed
29
	// evaluate HEDR subchunks (= find MSH2)
30
	for (std::list<ChunkHeader*>::iterator it = tempMainChunks.begin(); it != tempMainChunks.end(); it++)
31
	{
32
		if (!strcmp("MSH2", (*it)->name))
33
		{
Anakin's avatar
Anakin committed
34
			// get all subchunks
35
36
			std::list<ChunkHeader*> tempMsh2Chunks;
			loadChunks(tempMsh2Chunks, (*it)->position, (*it)->size);
Anakin's avatar
Anakin committed
37

38
39
40
41
42
			// evaluate MSH2 subchunks
			analyseMsh2Chunks(tempMsh2Chunks);

			// clean up
			while (!tempMsh2Chunks.empty())
Anakin's avatar
Anakin committed
43
			{
44
45
				ChunkHeader* tempCursor = tempMsh2Chunks.front();
				tempMsh2Chunks.pop_front();
Anakin's avatar
Anakin committed
46
47
				delete tempCursor;
			}
48
			continue;
49
50
		}
	}
51

52
53
54
55
56
57
58
59
	// clean up
	while (!tempMainChunks.empty())
	{
		ChunkHeader* tempCursor = tempMainChunks.front();
		tempMainChunks.pop_front();
		delete tempCursor;
	}

60
61
62
63
64
65
	// close file
	fsMesh.close();
}

Object::~Object()
{
Anakin's avatar
Anakin committed
66
67
68
69
70
	// clear texture list
	vTextures.clear();

	// clear Model list (don't delete the elements)
	vModls.clear();
71
}
72
73


74
75
/////////////////////////////////////////////////////////////////////////
// private functions
76

Anakin's avatar
Anakin committed
77
void Object::loadChunks(std::list<ChunkHeader*>& destination, std::streampos start, const std::uint32_t end)
78
{
79
	// jump to first chunk
80
	fsMesh.seekg(start);
81

Anakin's avatar
Anakin committed
82
83
	do
	{
Anakin's avatar
Anakin committed
84
		ChunkHeader* tempHeader = new ChunkHeader();
85

86
87
88
		fsMesh.read(reinterpret_cast<char*>(&tempHeader->name[0]), sizeof(tempHeader->name) - 1);
		fsMesh.read(reinterpret_cast<char*>(&tempHeader->size), sizeof(tempHeader->size));
		tempHeader->position = fsMesh.tellg();
89

90
		destination.push_back(tempHeader);
91

92
		fsMesh.seekg(tempHeader->size, std::ios_base::cur);
93

94
95
		// reached end
		if (fsMesh.tellg() - start == end)
Anakin's avatar
Anakin committed
96
			break;
97
98
99
100
101
102
103
104
105
106

		// error. Maybe the size information is corrupted
		if (!fsMesh.good())
		{
			std::cout << "WARNING: corrupted file. Trying to continue" << std::endl;
			fsMesh.clear();
			break;
		}

	} while (true);
107
108
}

109
110
111
112
113
114
void Object::analyseMsh2Chunks(std::list<ChunkHeader*>& chunkList)
{
	for (std::list<ChunkHeader*>::iterator it = chunkList.begin(); it != chunkList.end(); it++)
	{
		if (!strcmp("MATL", (*it)->name))
		{
115
116
117
118
119
			// "useless" information how many MATD follow
			fsMesh.seekg((*it)->position);
			std::uint32_t tempMatdCount;
			fsMesh.read(reinterpret_cast<char*>(&tempMatdCount), sizeof(std::uint32_t));

Anakin's avatar
Anakin committed
120
121
			// get all MATD from MATL list
			std::list<ChunkHeader*> tempMatlChunks;
122
			loadChunks(tempMatlChunks, fsMesh.tellg(), (*it)->size - 4);
Anakin's avatar
Anakin committed
123
124
125
126
127
128
129
130
131
132
133

			// evaluate MATL subchunks
			for (std::list<ChunkHeader*>::iterator it = tempMatlChunks.begin(); it != tempMatlChunks.end(); it++)
			{
				// This shouldn't be anything else than MATD
				if (!strcmp("MATD", (*it)->name))
				{
					// get all subchunks from MATD
					std::list<ChunkHeader*> tempMatdChunks;
					loadChunks(tempMatdChunks, (*it)->position, (*it)->size);

134
135
					vTextures.push_back("");

Anakin's avatar
Anakin committed
136
					// analyse MATD subchunks
Anakin's avatar
Anakin committed
137
					analyseMatdChunks(tempMatdChunks);
Anakin's avatar
Anakin committed
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

					// clean up
					while (!tempMatdChunks.empty())
					{
						ChunkHeader* tempCursor = tempMatdChunks.front();
						tempMatdChunks.pop_front();
						delete tempCursor;
					}
				}
			}

			// clean up
			while (!tempMatlChunks.empty())
			{
				ChunkHeader* tempCursor = tempMatlChunks.front();
				tempMatlChunks.pop_front();
				delete tempCursor;
			}
156
157
158
159
160
161

			continue;
		}

		if (!strcmp("MODL", (*it)->name))
		{
Anakin's avatar
Anakin committed
162
163
			Modl* tempModl = new Modl;

164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
			// get all subchunks
			std::list<ChunkHeader*> tempChunks;
			loadChunks(tempChunks, (*it)->position, (*it)->size);

			// evaluate MODL subchunks
			analyseModlChunks(tempModl, tempChunks);

			//clean up
			while (!tempChunks.empty())
			{
				ChunkHeader* tempCursor = tempChunks.front();
				tempChunks.pop_front();
				delete tempCursor;
			}

Anakin's avatar
Anakin committed
179
			// save Model data
Anakin's avatar
Anakin committed
180
			vModls.push_back(tempModl);
Anakin's avatar
Anakin committed
181

Anakin's avatar
Anakin committed
182
183
184
185
			continue;
		}
	}
}
186

Anakin's avatar
Anakin committed
187
void Object::analyseMatdChunks(std::list<ChunkHeader*>& chunkList)
Anakin's avatar
Anakin committed
188
189
190
191
192
193
194
195
196
197
{
	for (std::list<ChunkHeader*>::iterator it = chunkList.begin(); it != chunkList.end(); it++)
	{
		//TX1D, TX2D, TX3D
		if (!strcmp("TX0D", (*it)->name))
		{
			fsMesh.seekg((*it)->position);
			char* buffer = new char[(*it)->size + 1];
			*buffer = { 0 };
			fsMesh.read(buffer, (*it)->size);
198
			vTextures.back() = buffer;
Anakin's avatar
Anakin committed
199
			delete buffer;
200
201
202
203
204
			continue;
		}
	}
}

Anakin's avatar
Anakin committed
205
206
207
208
209
210
211
212
213
214
void Object::analyseModlChunks(Modl* dataDestination, std::list<ChunkHeader*>& chunkList)
{
	for (std::list<ChunkHeader*>::iterator it = chunkList.begin(); it != chunkList.end(); it++)
	{
		if (!strcmp("MTYP", (*it)->name))
		{
			fsMesh.seekg((*it)->position);
			std::uint32_t tempType;
			fsMesh.read(reinterpret_cast<char*>(&tempType), sizeof(tempType));
			dataDestination->type = (Mtyp)tempType;
Anakin's avatar
Anakin committed
215
			continue;
Anakin's avatar
Anakin committed
216
217
218
219
220
		}

		if (!strcmp("PRNT", (*it)->name))
		{
			fsMesh.seekg((*it)->position);
221
			char* buffer = new char[(*it)->size];
Anakin's avatar
Anakin committed
222
			*buffer = { 0 };
223
224
225
			fsMesh.read(buffer, (*it)->size); 
			dataDestination->parent = buffer;
			delete buffer;
Anakin's avatar
Anakin committed
226
			continue;
Anakin's avatar
Anakin committed
227
228
229
230
231
		}

		if (!strcmp("NAME", (*it)->name))
		{
			fsMesh.seekg((*it)->position);
232
			char* buffer = new char[(*it)->size];
Anakin's avatar
Anakin committed
233
			*buffer = { 0 };
234
235
			fsMesh.read(buffer, (*it)->size);
			dataDestination->name = buffer;
236
			delete buffer;
Anakin's avatar
Anakin committed
237
			continue;
Anakin's avatar
Anakin committed
238
239
240
241
242
243
		}

		if (!strcmp("FLGS", (*it)->name))
		{
			fsMesh.seekg((*it)->position);
			fsMesh.read(reinterpret_cast<char*>(&dataDestination->renderFlags), sizeof(dataDestination->renderFlags));
Anakin's avatar
Anakin committed
244
			continue;
Anakin's avatar
Anakin committed
245
246
247
248
		}

		if (!strcmp("TRAN", (*it)->name))
		{
Anakin's avatar
Anakin committed
249
250
251
252
			float tempScale[3];
			float tempRotation[4];
			float tempTrans[3];

Anakin's avatar
Anakin committed
253
			fsMesh.seekg((*it)->position);
Anakin's avatar
Anakin committed
254
255
256
257
258
259
260
261
262
263

			fsMesh.read(reinterpret_cast<char*>(&tempScale[0]), sizeof(float));
			fsMesh.read(reinterpret_cast<char*>(&tempScale[1]), sizeof(float));
			fsMesh.read(reinterpret_cast<char*>(&tempScale[2]), sizeof(float));

			fsMesh.read(reinterpret_cast<char*>(&tempRotation[0]), sizeof(float));
			fsMesh.read(reinterpret_cast<char*>(&tempRotation[1]), sizeof(float));
			fsMesh.read(reinterpret_cast<char*>(&tempRotation[2]), sizeof(float));
			fsMesh.read(reinterpret_cast<char*>(&tempRotation[3]), sizeof(float));

Anakin's avatar
Anakin committed
264
265
266
267
268
269
270
			//calculate x,y,z rotation
			tempRotation[0] = atan2(2 * (tempRotation[0] * tempRotation[1] + tempRotation[2] * tempRotation[3]),
									1 - 2 * (pow(tempRotation[1], 2) + pow(tempRotation[2], 2)));
			tempRotation[1] = asin(2 * (tempRotation[0] * tempRotation[2] - tempRotation[3] * tempRotation[1]));
			tempRotation[2] = atan2(2 * (tempRotation[0] * tempRotation[3] + tempRotation[1] * tempRotation[2]),
									1 - 2 * (pow(tempRotation[2], 2) + pow(tempRotation[3], 2))) - PI;

Anakin's avatar
Anakin committed
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
			fsMesh.read(reinterpret_cast<char*>(&tempTrans[0]), sizeof(float));
			fsMesh.read(reinterpret_cast<char*>(&tempTrans[1]), sizeof(float));
			fsMesh.read(reinterpret_cast<char*>(&tempTrans[2]), sizeof(float));

			dataDestination->m4x4Translation = glm::scale(
				dataDestination->m4x4Translation,
				glm::vec3(tempScale[0], tempScale[1], tempScale[2])
			);

			dataDestination->m4x4Translation = glm::translate(
				dataDestination->m4x4Translation,
				glm::vec3(tempTrans[0], tempTrans[1], tempTrans[2])
			);

			dataDestination->m4x4Translation = glm::rotate(
				dataDestination->m4x4Translation,
				tempRotation[0],
				glm::vec3(1, 0, 0)
			);

			dataDestination->m4x4Translation = glm::rotate(
				dataDestination->m4x4Translation,
				tempRotation[1],
				glm::vec3(0, 1, 0)
			);

			dataDestination->m4x4Translation = glm::rotate(
				dataDestination->m4x4Translation,
				tempRotation[2],
				glm::vec3(0, 0, 1)
			);

Anakin's avatar
Anakin committed
303
			continue;
Anakin's avatar
Anakin committed
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
		}

		if (!strcmp("GEOM", (*it)->name))
		{
			// get all subchunks
			std::list<ChunkHeader*> tempGeomChunks;
			loadChunks(tempGeomChunks, (*it)->position, (*it)->size);

			// evaluate GEOM subchunks
			analyseGeomChunks(dataDestination, tempGeomChunks);

			// clean up
			while (!tempGeomChunks.empty())
			{
				ChunkHeader* tempCursor = tempGeomChunks.front();
				tempGeomChunks.pop_front();
				delete tempCursor;
			}
Anakin's avatar
Anakin committed
322
323

			continue;
Anakin's avatar
Anakin committed
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
		}
	}
}

void Object::analyseGeomChunks(Modl * dataDestination, std::list<ChunkHeader*>& chunkList)
{
	for (std::list<ChunkHeader*>::iterator it = chunkList.begin(); it != chunkList.end(); it++)
	{
		if (!strcmp("SEGM", (*it)->name))
		{
			// get all subchunks
			std::list<ChunkHeader*> tempSegmChunks;
			loadChunks(tempSegmChunks, (*it)->position, (*it)->size);

			// evaluate SEGM subchunks
			analyseSegmChunks(dataDestination, tempSegmChunks);

			// clean up
			while (!tempSegmChunks.empty())
			{
				ChunkHeader* tempCursor = tempSegmChunks.front();
				tempSegmChunks.pop_front();
				delete tempCursor;
			}
Anakin's avatar
Anakin committed
348
			continue;
Anakin's avatar
Anakin committed
349
		}
Anakin's avatar
Anakin committed
350
351
		
		if (!strcmp("CLTH", (*it)->name))
Anakin's avatar
Anakin committed
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
		{
			// get all subchunks
			std::list<ChunkHeader*> tempClthChunks;
			loadChunks(tempClthChunks, (*it)->position, (*it)->size);

			// evaluate CLTH subchunks
			analyseClthChunks(dataDestination, tempClthChunks);

			// clean up
			while (!tempClthChunks.empty())
			{
				ChunkHeader* tempCursor = tempClthChunks.front();
				tempClthChunks.pop_front();
				delete tempCursor;
			}
Anakin's avatar
Anakin committed
367
			continue;
Anakin's avatar
Anakin committed
368
369
370
371
372
373
		}
	}
}

void Object::analyseSegmChunks(Modl * dataDestination, std::list<ChunkHeader*>& chunkList)
{
Anakin's avatar
Anakin committed
374
375
	Segment* tempData = new Segment;

Anakin's avatar
Anakin committed
376
377
378
379
380
	for (std::list<ChunkHeader*>::iterator it = chunkList.begin(); it != chunkList.end(); it++)
	{
		if (!strcmp("MATI", (*it)->name))
		{
			fsMesh.seekg((*it)->position);
Anakin's avatar
Anakin committed
381
			fsMesh.read(reinterpret_cast<char*>(&tempData->textureIndex), sizeof(tempData->textureIndex));
Anakin's avatar
Anakin committed
382
			continue;
Anakin's avatar
Anakin committed
383
384
385
386
		}

		if (!strcmp("POSL", (*it)->name))
		{
Anakin's avatar
Anakin committed
387
			readVertex(tempData, (*it)->position);
Anakin's avatar
Anakin committed
388
			continue;
Anakin's avatar
Anakin committed
389
390
		}

391
		/*if (!strcmp("NRML", (*it)->name))
Anakin's avatar
Anakin committed
392
393
		{
			fsMesh.seekg((*it)->position);
394
395
			std::uint32_t tempSize;
			fsMesh.read(reinterpret_cast<char*>(&tempSize), sizeof(tempSize));
Anakin's avatar
Anakin committed
396
397
398
			// List of normals
			// long int - 4 - number of normal vectores stored in this list
			// float[3][] - 12 each - UVW vector for each vertex
Anakin's avatar
Anakin committed
399
			continue;
400
		}*/
Anakin's avatar
Anakin committed
401
402
403

		if (!strcmp("UV0L", (*it)->name))
		{
Anakin's avatar
Anakin committed
404
			readUV(tempData, (*it)->position);
Anakin's avatar
Anakin committed
405
			continue;
Anakin's avatar
Anakin committed
406
407
		}

408
409
		if (!strcmp("STRP", (*it)->name))
		{
410
411
412
413
414
415
			// don't get null, bone, shadowMesh and hidden mesh indices
			if (dataDestination->type == null ||
				dataDestination->type == bone ||
				dataDestination->type == shadowMesh ||
				dataDestination->renderFlags == 1)
				continue;
416
417

			// jump to the data section and read the size;
418
			std::uint32_t tempSize;
419
			fsMesh.seekg((*it)->position);
420
			fsMesh.read(reinterpret_cast<char*>(&tempSize), sizeof(tempSize));
421
422
423
424

			int highBitCount(0);
			std::vector<uint32_t>* tempPoly = new std::vector<uint32_t>;
			
425
			for (unsigned int i = 0; i < tempSize; i++)
426
427
428
429
430
431
432
433
434
435
436
437
438
439
			{
				// ReadData
				std::uint16_t tempValue;
				fsMesh.read(reinterpret_cast<char*>(&tempValue), sizeof(std::uint16_t));

				// Check for highbit
				if (tempValue >> 15)
				{
					highBitCount++;
					tempValue = (std::uint16_t(tempValue << 1) >> 1);
				}

				tempPoly->push_back((std::uint32_t)tempValue);

440
				// new Polygon found
441
442
443
				if (highBitCount == 2)
				{
					// reset highBitCount
Anakin's avatar
Anakin committed
444
					highBitCount = 0;
445
446
447
448
449

					// remove the last two values..
					std::uint32_t saveData[2];
					for (int i = 0; i < 2; i++)
					{
450
						saveData[i] = tempPoly->back();
451
452
453
454
455
456
457
458
459
						tempPoly->pop_back();
					}

					// ..and save them in the new vector
					std::vector<uint32_t>* newPointer = new std::vector<uint32_t>;
					for (int i = 1; i >= 0; i--)
						newPointer->push_back(saveData[i]);

					// save the old vector and set the pointer to the new one
460
					tempData->meshIndices.push_back(tempPoly);
461
462
463
464
					tempPoly = newPointer;
				}	// if high bit set
				
			}	// for all values
465

466
			// save the last values (where no 2 high bits follow);
467
468
469
470
			tempData->meshIndices.push_back(tempPoly);

			// kick the first element, it's empty as a reason of the algo above;
			tempData->meshIndices.erase(tempData->meshIndices.begin());
471
472
			continue;
		}
Anakin's avatar
Anakin committed
473
	}
Anakin's avatar
Anakin committed
474
	dataDestination->segmLst.push_back(tempData);
Anakin's avatar
Anakin committed
475
476
477
478
}

void Object::analyseClthChunks(Modl * dataDestination, std::list<ChunkHeader*>& chunkList)
{
Anakin's avatar
Anakin committed
479
480
	Segment* tempData = new Segment;

Anakin's avatar
Anakin committed
481
482
483
484
485
	for (std::list<ChunkHeader*>::iterator it = chunkList.begin(); it != chunkList.end(); it++)
	{
		if (!strcmp("CTEX", (*it)->name))
		{
			fsMesh.seekg((*it)->position);
486
			char* buffer = new char[(*it)->size];
Anakin's avatar
Anakin committed
487
			*buffer = { 0 };
488
			fsMesh.read(buffer, (*it)->size);
Anakin's avatar
Anakin committed
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507

			bool tempFound(false);

			for (unsigned int index = 0; index < vTextures.size(); index++)
			{
				if (!strcmp(buffer, vTextures[index].c_str()))
				{
					tempData->textureIndex = index;
					tempFound = true;
					break;
				}
			}

			if (!tempFound)
			{
				vTextures.push_back(std::string(buffer));
				tempData->textureIndex = vTextures.size() - 1;
			}

508
			delete buffer;
Anakin's avatar
Anakin committed
509
			continue;
Anakin's avatar
Anakin committed
510
511
512
		}

		if (!strcmp("CPOS", (*it)->name))
Anakin's avatar
Anakin committed
513
		{
Anakin's avatar
Anakin committed
514
			readVertex(tempData, (*it)->position);
Anakin's avatar
Anakin committed
515
516
			continue;
		}
Anakin's avatar
Anakin committed
517
518

		if (!strcmp("CUV0", (*it)->name))
Anakin's avatar
Anakin committed
519
		{
Anakin's avatar
Anakin committed
520
			readUV(tempData, (*it)->position);
Anakin's avatar
Anakin committed
521
522
			continue;
		}
Anakin's avatar
Anakin committed
523
524

		if (!strcmp("CMSH", (*it)->name))
Anakin's avatar
Anakin committed
525
		{
526
527
			// jump to the data section and read the size;
			std::uint32_t tempSize;
Anakin's avatar
Anakin committed
528
			fsMesh.seekg((*it)->position);
529
			fsMesh.read(reinterpret_cast<char*>(&tempSize), sizeof(tempSize));
Anakin's avatar
Anakin committed
530

531
			std::vector<uint32_t>* tempPoly;
Anakin's avatar
Anakin committed
532

533
534
			// for every triangle..
			for (unsigned int i = 0; i < tempSize; i += 3)
Anakin's avatar
Anakin committed
535
			{
536
537
538
539
540
541
542
543
544
545
				tempPoly = new std::vector<uint32_t>;

				// ..get the 3 indices and save them
				for (int j = 0; j < 3; j++)
				{
					std::uint32_t tempValue;
					fsMesh.read(reinterpret_cast<char*>(&tempValue), sizeof(std::uint32_t));
					tempPoly->push_back(tempValue);
				}
				tempData->meshIndices.push_back(tempPoly);
Anakin's avatar
Anakin committed
546
547
548
			}
			continue;
		}
549
	}
Anakin's avatar
Anakin committed
550
	dataDestination->segmLst.push_back(tempData);
551
552
}

Anakin's avatar
Anakin committed
553
void Object::readVertex(Segment* dataDestination, std::streampos position)
554
555
556
557
558
559
560
{
	std::uint32_t tempSize;
	fsMesh.seekg(position);
	fsMesh.read(reinterpret_cast<char*>(&tempSize), sizeof(tempSize));

	dataDestination->vertex = new float[tempSize * 3];

Anakin's avatar
Anakin committed
561
	for (unsigned int i = 0; i < tempSize * 3; i++)
562
563
564
		fsMesh.read(reinterpret_cast<char*>(&dataDestination->vertex[i]), sizeof(float));
}

Anakin's avatar
Anakin committed
565
void Object::readUV(Segment* dataDestination, std::streampos position)
566
567
568
569
570
571
572
{
	std::uint32_t tempSize;
	fsMesh.seekg(position);
	fsMesh.read(reinterpret_cast<char*>(&tempSize), sizeof(tempSize));

	dataDestination->uv = new float[tempSize * 2];

Anakin's avatar
Anakin committed
573
	for (unsigned int i = 0; i < tempSize * 2; i++)
574
		fsMesh.read(reinterpret_cast<char*>(&dataDestination->uv[i]), sizeof(float));
Anakin's avatar
Anakin committed
575
576
}

577

Anakin's avatar
Anakin committed
578
579
/////////////////////////////////////////////////////////////////////////
// public getter
580

Anakin's avatar
Anakin committed
581
582
583
584
585
std::vector<Modl*> Object::getModels() const
{
	return vModls;
}

Anakin's avatar
Anakin committed
586
587
588
589
590
std::vector<std::string> Object::getTextureList() const
{
	return vTextures;
}

591
592
593
594

/////////////////////////////////////////////////////////////////////////
// public functions