Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kApiDef.h
Go to the documentation of this file.
1 /**
2 * @file kApiDef.h
3 * @brief Essential API declarations.
4 *
5 * @internal
6 * Copyright (C) 2005-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_API_DEF_H
11 #define K_API_API_DEF_H
12
13 #include <kApi/kApiCfg.h>
14
15 kBeginHeader()
16
17 #define kCall kxCall ///< kApi standard function calling convention.
18 #define kDlCall kxDlCall ///< kApi dynamic load function calling convention.
19
20 #if defined(K_EMIT)
21 # define kFx(TYPE) kExportFx(TYPE) ///< kApi function declaration helper.
22 # define kDx(TYPE) kExportDx(TYPE) ///< kApi data declaration helper.
23 #else
24 # define kFx(TYPE) kImportFx(TYPE)
25 # define kDx(TYPE) kImportDx(TYPE)
26 #endif
27
28 typedef void (kCall* kFunction)(); ///< Generic pointer to function.
29
30 /**
31 * @struct k8u
32 * @extends kValue
33 * @ingroup kApi
34 * @brief Represents an 8-bit unsigned integer.
35 * @see k8U_MIN, k8U_MAX, k8U_NULL
36 */
37 typedef kx8u k8u;
38
39 #define k8U_MIN (0) ///< k8u minimum value.
40 #define k8U_MAX (255U) ///< k8u maximum value.
41 #define k8U_NULL (k8U_MAX) ///< k8u invalid value.
42
43 /**
44 * @struct k16u
45 * @extends kValue
46 * @ingroup kApi
47 * @brief Represents a 16-bit unsigned integer.
48 * @see k16U_MIN, k16U_MAX, k16U_NULL
49 */
50 typedef kx16u k16u;
51
52 #define k16U_MIN (0) ///< k16u minimum value.
53 #define k16U_MAX (65535U) ///< k16u maximum value.
54 #define k16U_NULL (k16U_MAX) ///< k16u invalid value.
55
56 /**
57 * @struct k32u
58 * @extends kValue
59 * @ingroup kApi
60 * @brief Represents a 32-bit unsigned integer.
61 * @see k32U_MIN, k32U_MAX, k32U_NULL
62 */
63 typedef kx32u k32u;
64
65 #define k32U_MIN (0) ///< k32u minimum value.
66 #define k32U_MAX (4294967295U) ///< k32u maximum value.
67 #define k32U_NULL (k32U_MAX) ///< k32u invalid value.
68
69 /**
70 * @struct k64u
71 * @extends kValue
72 * @ingroup kApi
73 * @brief Represents a 64-bit unsigned integer.
74 * @see k64U_MIN, k64U_MAX, k64U_NULL
75 */
76 typedef kx64u k64u;
77
78 #define k64U(CONST) kx64U(CONST) ///< Declares a 64-bit unsigned integer literal.
79 #define k64U_MIN k64U(0) ///< k64u minimum value.
80 #define k64U_MAX k64U(18446744073709551615) ///< k64u maximum value.
81 #define k64U_NULL (k64U_MAX) ///< k64u invalid value.
82 #define kINFINITE k64U_MAX ///< Infinity (used for k64u timeouts).
83
84 /**
85 * @struct k8s
86 * @extends kValue
87 * @ingroup kApi
88 * @brief Represents an 8-bit signed integer.
89 * @see k8S_MIN, k8S_MAX, k8S_NULL
90 */
91 typedef kx8s k8s;
92
93 #define k8S_MAX (127) ///< k8s maximum value.
94 #define k8S_MIN (-k8S_MAX -1) ///< k8s minimum value.
95 #define k8S_NULL (k8S_MIN) ///< k8s invalid value.
96
97 /**
98 * @struct k16s
99 * @extends kValue
100 * @ingroup kApi
101 * @brief Represents a 16-bit signed integer.
102 * @see k16S_MIN, k16S_MAX, k16S_NULL
103 */
104 typedef kx16s k16s;
105
106 #define k16S_MAX (32767) ///< k16s maximum value.
107 #define k16S_MIN (-k16S_MAX -1) ///< k16s minimum value.
108 #define k16S_NULL (k16S_MIN) ///< k16s invalid value.
109
110 /**
111 * @struct k32s
112 * @extends kValue
113 * @ingroup kApi
114 * @brief Represents a 32-bit signed integer.
115 * @see k32S_MIN, k32S_MAX, k32S_NULL
116 */
117 typedef kx32s k32s;
118
119 #define k32S_MAX (2147483647) ///< k32s maximum value.
120 #define k32S_MIN (-k32S_MAX -1) ///< k32s minimum value.
121 #define k32S_NULL (k32S_MIN) ///< k32s invalid value.
122
123 /**
124 * @struct k64s
125 * @extends kValue
126 * @ingroup kApi
127 * @brief Represents a 64-bit signed integer.
128 * @see k64S_MIN, k64S_MAX, k64S_NULL
129 */
130 typedef kx64s k64s;
131
132 #define k64S(CONST) kx64S(CONST) ///< Declares a 64-bit signed integer literal.
133 #define k64S_MAX k64S(9223372036854775807) ///< k64s maximum value.
134 #define k64S_MIN (-k64S_MAX -1) ///< k64s minimum value.
135 #define k64S_NULL (k64S_MIN) ///< k64s invalid value.
136
137 /**
138 * @struct k32f
139 * @extends kValue
140 * @ingroup kApi
141 * @brief Represents a 32-bit floating-point number.
142 * @see k32F_MIN, k32F_MAX, k32F_NULL
143 */
144 typedef kx32f k32f;
145
146 #define k32F_MIN (1.175494351e-38F) ///< k32f smallest positive value.
147 #define k32F_MAX (3.402823466e+38F) ///< k32f largest positive value.
148 #define k32F_NULL (-k32F_MAX) ///< k32f invalid value.
149
150 /**
151 * @struct k64f
152 * @extends kValue
153 * @ingroup kApi
154 * @brief Represents a 64-bit floating-point number.
155 * @see k64F_MIN, k64F_MAX, k64F_NULL
156 */
157 typedef kx64f k64f;
158
159 #define k64F_MIN (2.2250738585072014e-308) ///< k64f smallest positive value.
160 #define k64F_MAX (1.7976931348623157e+308) ///< k64f largest positive value.
161 #define k64F_NULL (-k64F_MAX) ///< k64f invalid value.
162
163 /**
164 * @struct kByte
165 * @extends kValue
166 * @ingroup kApi
167 * @brief Represents a byte on the current platform.
168 */
169 typedef kxByte kByte;
170
171 /**
172 * @struct kSize
173 * @extends kValue
174 * @ingroup kApi
175 * @brief Represents an unsigned integer that can store a pointer address.
176 * @see kSIZE_MAX
177 */
178 typedef kxSize kSize;
179
180 #define kSIZE_MAX kxSIZE_MAX ///< Maximum value contained by kSize.
181 #define kSIZE_NULL kSIZE_MAX ///< Invalid size value.
182
183 /**
184 * @struct kSSize
185 * @extends kValue
186 * @ingroup kApi
187 * @brief Represents a signed integer that can store a pointer address.
188 * @see kSSIZE_MIN, kSSIZE_MAX
189 */
190 typedef kxSSize kSSize;
191
192 #define kSSIZE_MIN kxSSIZE_MIN ///< Minimum value contained by kSSize.
193 #define kSSIZE_MAX kxSSIZE_MAX ///< Maximum value contained by kSSize.
194 #define kSSIZE_NULL kSSIZE_MIN ///< Invalid kSSize value.
195
196 /**
197 * @struct kPointer
198 * @extends kValue
199 * @ingroup kApi
200 * @brief Represents a void pointer.
201 * @see kNULL, kIsNull
202 */
203 typedef void* kPointer;
204
205 #define kNULL (0) ///< Null pointer.
206
207 /**
208 * Tests for equality with null pointer.
209 *
210 * @param POINTER Pointer to be compared with null.
211 * @return kTRUE if the argument is equal to null; kFALSE otherwise.
212 */
213 #define kIsNull(POINTER) kIsNull_(POINTER)
214
215 /**
216 * @struct kBool
217 * @extends kValue
218 * @ingroup kApi
219 * @brief Represents a boolean value.
220 * @see kTRUE, kFALSE
221 */
222 typedef k32s kBool;
223
224 #define kFALSE (0) ///< Boolean false.
225 #define kTRUE (1) ///< Boolean true.
226
227 /**
228 * @struct kChar
229 * @extends kValue
230 * @ingroup kApi
231 * @brief Represents a single unit (byte) in a UTF-8 character.
232 */
233 typedef kxChar kChar;
234
235 /**
236 * @struct kText16
237 * @extends kValue
238 * @ingroup kApi
239 * @brief Represents a 16-unit, null-terminated, kChar sequence.
240 */
241 typedef kChar kText16[16];
242
243 /**
244 * @struct kText32
245 * @extends kValue
246 * @ingroup kApi
247 * @brief Represents a 32-unit, null-terminated, kChar sequence.
248 */
249 typedef kChar kText32[32];
250
251 /**
252 * @struct kText64
253 * @extends kValue
254 * @ingroup kApi
255 * @brief Represents a 64-unit, null-terminated, kChar sequence.
256 */
257 typedef kChar kText64[64];
258
259 /**
260 * @struct kText128
261 * @extends kValue
262 * @ingroup kApi
263 * @brief Represents a 128-unit, null-terminated, kChar sequence.
264 */
265 typedef kChar kText128[128];
266
267 /**
268 * @struct kText256
269 * @extends kValue
270 * @ingroup kApi
271 * @brief Represents a 256-unit, null-terminated, kChar sequence.
272 */
273 typedef kChar kText256[256];
274
275 /**
276 * @struct kStatus
277 * @extends kValue
278 * @ingroup kApi
279 * @brief Represents an enumeration of error codes.
280 *
281 * The following enumerators are defined:
282 * - #kERROR_STATE
283 * - #kERROR_NOT_FOUND
284 * - #kERROR_COMMAND
285 * - #kERROR_PARAMETER
286 * - #kERROR_UNIMPLEMENTED
287 * - #kERROR_MEMORY
288 * - #kERROR_TIMEOUT
289 * - #kERROR_INCOMPLETE
290 * - #kERROR_STREAM
291 * - #kERROR_CLOSED
292 * - #kERROR_VERSION
293 * - #kERROR_ABORT
294 * - #kERROR_ALREADY_EXISTS
295 * - #kERROR_NETWORK
296 * - #kERROR_HEAP
297 * - #kERROR_FORMAT
298 * - #kERROR_READ_ONLY
299 * - #kERROR_WRITE_ONLY
300 * - #kERROR_BUSY
301 * - #kERROR_CONFLICT
302 * - #kERROR_OS
303 * - #kERROR_DEVICE
304 * - #kERROR_FULL
305 * - #kERROR_IN_PROGRESS
306 * - #kERROR
307 * - #kOK
308 */
309 typedef k32s kStatus;
310
311 #define kERROR_STATE (-1000) ///< Invalid state.
312 #define kERROR_NOT_FOUND (-999) ///< Item is not found.
313 #define kERROR_COMMAND (-998) ///< Command not recognized.
314 #define kERROR_PARAMETER (-997) ///< Parameter is invalid.
315 #define kERROR_UNIMPLEMENTED (-996) ///< Feature not implemented.
316 #define kERROR_MEMORY (-994) ///< Out of memory.
317 #define kERROR_TIMEOUT (-993) ///< Action timed out.
318 #define kERROR_INCOMPLETE (-992) ///< Buffer insufficient for data.
319 #define kERROR_STREAM (-991) ///< Error in stream.
320 #define kERROR_CLOSED (-990) ///< Resource is no longer available.
321 #define kERROR_VERSION (-989) ///< Incompatible version.
322 #define kERROR_ABORT (-988) ///< Operation aborted.
323 #define kERROR_ALREADY_EXISTS (-987) ///< Conflicts with existing item.
324 #define kERROR_NETWORK (-986) ///< Network setup/resource error.
325 #define kERROR_HEAP (-985) ///< Heap error (leak/double-free).
326 #define kERROR_FORMAT (-984) ///< Data parsing/formatting error.
327 #define kERROR_READ_ONLY (-983) ///< Object is read-only (cannot be written).
328 #define kERROR_WRITE_ONLY (-982) ///< Object is write-only (cannot be read).
329 #define kERROR_BUSY (-981) ///< Agent is busy (cannot service request).
330 #define kERROR_CONFLICT (-980) ///< State conflicts with another object.
331 #define kERROR_OS (-979) ///< Generic error reported by underlying OS.
332 #define kERROR_DEVICE (-978) ///< Hardware device error.
333 #define kERROR_FULL (-977) ///< Resource is already fully utilized.
334 #define kERROR_IN_PROGRESS (-976) ///< Operation is in progress, but not yet complete.
335 #define kERROR (0) ///< General error.
336 #define kOK (1) ///< Operation successful.
337
338 /**
339 * Returns a text string representing the name of a status code (e.g. "kERROR_STATE").
340 *
341 * This function returns a pointer to statically-allocated memory; do not attempt to free the memory.
342 *
343 * @public @memberof kStatus
344 * @param status Status code.
345 * @return Null-terminated character sequence.
346 */
347 kFx(const kChar*) kStatus_Name(kStatus status);
348
349 /**
350 * Returns kTRUE if the given status value is not kOK.
351 *
352 * This macro is guaranteed to evaluate its arguments only once.
353 *
354 * @param EXPRESSION Expression that evaluates to a kStatus value.
355 * @return kTRUE if the argument is not equal to kOK; kFALSE otherwise.
356 * @see @ref error-handling
357 */
358 #define kIsError(EXPRESSION) kIsError_(EXPRESSION)
359
360 /**
361 * Returns kTRUE if the given expression value is kOK.
362 *
363 * This macro is guaranteed to evaluate its arguments only once.
364 *
365 * @param EXPRESSION Expression that evaluates to a kStatus value.
366 * @return kTRUE if the argument is equal to kOK; kFALSE otherwise.
367 * @see @ref error-handling
368 */
369 #define kSuccess(EXPRESSION) kSuccess_(EXPRESSION)
370
371 /**
372 * Executes a <em>return</em> statement if the given expression is not kOK.
373 *
374 * If the expression result is not kOK, the current function will return the expression result.
375 *
376 * This macro is guaranteed to evaluate its arguments only once.
377 *
378 * @param EXPRESSION Expression that evaluates to a kStatus value.
379 * @see @ref error-handling
380 */
381 #define kCheck(EXPRESSION) kCheck_(EXPRESSION)
382
383 /**
384 * Executes a <em>return</em> statement if the given expression is not kTRUE.
385 *
386 * If the expression result is kFALSE, the current function will return kERROR_PARAMETER.
387 *
388 * This macro is guaranteed to evaluate its arguments only once.
389 *
390 * @param EXPRESSION Expression that evaluates to a kBool value.
391 * @see @ref error-handling
392 */
393 #define kCheckArgs(EXPRESSION) kCheckArgs_(EXPRESSION)
394
395 /**
396 * Executes a <em>return</em> statement if the given expression is not kTRUE.
397 *
398 * If the expression result is kFALSE, the current function will return kERROR_STATE.
399 *
400 * This macro is guaranteed to evaluate its arguments only once.
401 *
402 * @param EXPRESSION Expression that evaluates to a kBool value.
403 * @see @ref error-handling
404 */
405 #define kCheckState(EXPRESSION) kCheckState_(EXPRESSION)
406
407 /**
408 * Opens a kTry error-checking block.
409 *
410 * @see @ref error-handling
411 */
412 #define kTry kTry_
413
414 /**
415 * Used within a kTry block to jump to the first error handling block (e.g. kCatch).
416 *
417 * This macro is guaranteed to evaluate its arguments only once.
418 *
419 * @param EXPRESSION Expression that evaluates to a kStatus value.
420 * @see @ref error-handling
421 */
422 #define kThrow(EXPRESSION) kThrow_(EXPRESSION)
423
424 /**
425 * Used within a kTry block to conditionally jump to the first error handling block (e.g. kCatch).
426 *
427 * If the EXPRESSION argument does not evaluate to kOK, the result of the expression
428 * is passed to an error-handling block. Otherwise, execution continues at the next statement.
429 *
430 * This macro is guaranteed to evaluate its arguments only once.
431 *
432 * @param EXPRESSION Expression that evaluates to a kStatus value.
433 * @see @ref error-handling
434 */
435 #define kTest(EXPRESSION) kTest_(EXPRESSION)
436
437 /**
438 * Within a kTry block, throws kERROR_PARAMETER if the expression result is kFALSE.
439 *
440 * If the EXPRESSION argument does not evaluate to kTRUE, kERROR_PARAMETER is passed to an
441 * error-handling block. Otherwise, execution continues at the next statement.
442 *
443 * This macro is guaranteed to evaluate its arguments only once.
444 *
445 * @param EXPRESSION Expression that evaluates to a kBool value.
446 * @see @ref error-handling
447 */
448 #define kTestArgs(EXPRESSION) kTestArgs_(EXPRESSION)
449
450 /**
451 * Within a kTry block, throws kERROR_STATE if the expression result is kFALSE.
452 *
453 * If the EXPRESSION argument does not evaluate to kTRUE, kERROR_STATE is passed to an
454 * error-handling block. Otherwise, execution continues at the next statement.
455 *
456 * This macro is guaranteed to evaluate its arguments only once.
457 *
458 * @param EXPRESSION Expression that evaluates to a kBool value.
459 * @see @ref error-handling
460 */
461 #define kTestState(EXPRESSION) kTestState_(EXPRESSION)
462
463 /**
464 * Closes a kTry block and opens a kCatch error-handling block.
465 *
466 * This macro is guaranteed to evaluate its arguments only once.
467 *
468 * @param STATUS_POINTER Receives the exception code.
469 * @see @ref error-handling
470 */
471 #define kCatch(STATUS_POINTER) kCatch_(STATUS_POINTER)
472
473 /**
474 * Closes a kCatch block.
475 *
476 * If the STATUS argument is not kOK, the current function returns STATUS.
477 *
478 * This macro is guaranteed to evaluate its arguments only once.
479 *
480 * @param STATUS Result of the kCatch block.
481 * @see @ref error-handling
482 */
483 #define kEndCatch(STATUS) kEndCatch_(STATUS)
484
485 /**
486 * Closes a kTry block and opens a kFinally block.
487 *
488 * @see @ref error-handling
489 */
490 #define kFinally kFinally_
491
492 /**
493 * Closes a kFinally block.
494 *
495 * If the kTry block produced an exception, the current function returns the exception code.
496 * Otherwise, execution continues after the kFinally block.
497 *
498 * @see @ref error-handling
499 */
500 #define kEndFinally() kEndFinally_()
501
502 /**
503 * Closes a kTry block and opens a kCatchEx error-handling block.
504 *
505 * This macro is guaranteed to evaluate its arguments only once.
506 *
507 * @param STATUS_POINTER Receives the exception code.
508 * @see @ref error-handling
509 */
510 #define kCatchEx(STATUS_POINTER) kCatchEx_(STATUS_POINTER)
511
512 /**
513 * Closes a kCatchEx block.
514 *
515 * The exception state is set to the value of the STATUS argument. If the exception state is
516 * not kOK, the kFinallyEx block will return the exception code to the caller when kFinallyEndEx
517 * is reached.
518 *
519 * This macro is guaranteed to evaluate its arguments only once.
520 *
521 * @param STATUS Result of the kCatchEx block.
522 * @see @ref error-handling
523 */
524 #define kEndCatchEx(STATUS) kEndCatchEx_(STATUS)
525
526 /**
527 * Opens a kFinallyEx block.
528 *
529 * @see @ref error-handling
530 */
531 #define kFinallyEx kFinallyEx_
532
533 /**
534 * Closes a kFinallyEx block.
535 *
536 * If the exception state passed by kEndCatchEx is not kOK, the current function returns the
537 * exception code. Otherwise, execution continues after the kFinallyEx block.
538 *
539 * @see @ref error-handling
540 */
541 #define kEndFinallyEx() kEndFinallyEx_()
542
543 /**
544 * Aborts execution if EXPRESSION is kFALSE.
545 *
546 * kAssert statements are omitted if neither K_DEBUG nor K_ASSERT is defined.
547 *
548 * @param EXPRESSION Expression that evaluates to a kBool value.
549 */
550 #define kAssert(EXPRESSION) kAssert_(EXPRESSION)
551
552 /**
553 * Aborts execution if the type of the OBJECT argument is not equivalent to kTypeOf(SYMBOL).
554 *
555 * Type is equivalence is determined using kObject_Is.
556 *
557 * kAssertType statements are omitted if neither K_DEBUG nor K_ASSERT is defined.
558 *
559 * @param OBJECT Expression that evaluates to a kType value.
560 * @param SYMBOL Type symbol, such as <em>kArrayList</em>.
561 */
562 #define kAssertType(OBJECT, SYMBOL) kAssertType_(OBJECT, SYMBOL)
563
564 /**
565 * Generates a trace event using the given tag (string literals only).
566 *
567 * Type is equivalence is determined using kObject_Is.
568 *
569 * kTrace statements are omitted if K_NO_TRACE is defined.
570 *
571 * @param TAG String literal passed to the trace handler.
572 */
573 #define kTrace(TAG) kTrace_(TAG)
574
575 /**
576 * @struct kVersion
577 * @extends kValue
578 * @ingroup kApi
579 * @brief Represents a version number.
580 */
581 typedef k32u kVersion;
582
583 /**
584 * Creates a version value from its constituent parts.
585 *
586 * @public @memberof kVersion
587 * @param major Major version part.
588 * @param minor Minor version part.
589 * @param release Release version part.
590 * @param build Build version part.
591 * @return Version value.
592 */
593 kFx(kVersion) kVersion_Create(k32u major, k32u minor, k32u release, k32u build);
594
595 /**
596 * Parses a version from a formatted string.
597 *
598 * @public @memberof kVersion
599 * @param version Receives the parsed version.
600 * @param buffer Formatted string (e.g. "1.2.3.4").
601 * @return Operation status.
602 */
603 kFx(kStatus) kVersion_Parse(kVersion* version, const kChar* buffer);
604
605 /**
606 * Formats a version to a string buffer.
607 *
608 * @public @memberof kVersion
609 * @param version Version.
610 * @param buffer Receives formatted string (e.g. "1.2.3.4").
611 * @param capacity Buffer capacity.
612 * @return Operation status.
613 */
614 kFx(kStatus) kVersion_Format(kVersion version, kChar* buffer, kSize capacity);
615
616 /**
617 * Returns an integral value indicating the relationship between the versions.
618 * A zero value represents both versions are equal. A positive value indicates
619 * that version2 is greater than version1; a negative value indicates the
620 * opposite.
621 *
622 * @public @memberof kVersion
623 * @param version1 Version1.
624 * @param version2 Version2.
625 * @return Operation status.
626 */
627 kFx(k32s) kVersion_Compare(kVersion version1, kVersion version2);
628
629 /**
630 * Returns the major part of a version number.
631 *
632 * @public @memberof kVersion
633 * @param version Version number.
634 * @return Major version.
635 */
636 kFx(k8u) kVersion_Major(kVersion version);
637
638 /**
639 * Returns the minor part of a version number.
640 *
641 * @public @memberof kVersion
642 * @param version Version number.
643 * @return Minor version.
644 */
645 kFx(k8u) kVersion_Minor(kVersion version);
646
647 /**
648 * Returns the release part of a version number.
649 *
650 * @public @memberof kVersion
651 * @param version Version number.
652 * @return Release version.
653 */
654 kFx(k8u) kVersion_Release(kVersion version);
655
656 /**
657 * Returns the build part of a version number.
658 *
659 * @public @memberof kVersion
660 * @param version Version number.
661 * @return Build version.
662 */
663 kFx(k8u) kVersion_Build(kVersion version);
664
665 /**
666 * @struct kPoint16s
667 * @extends kValue
668 * @ingroup kApi-Data
669 * @brief 2D point structure with 16-bit signed integer fields.
670 */
671 typedef struct kPoint16s
672 {
673 k16s x; ///< X-coordinate value.
674 k16s y; ///< Y-coordinate value.
675 } kPoint16s;
676
677 /**
678 * @struct kPoint16s
679 * @extends kValue
680 * @ingroup kApi-Data
681 * @brief 2D point structure with 32-bit signed integer fields.
682 */
683 typedef struct kPoint32s
684 {
685 k32s x; ///< X-coordinate value.
686 k32s y; ///< Y-coordinate value.
687 } kPoint32s;
688
689 /**
690 * @struct kPoint16s
691 * @extends kValue
692 * @ingroup kApi-Data
693 * @brief 2D point structure with 32-bit floating-point fields.
694 */
695 typedef struct kPoint32f
696 {
697 k32f x; ///< X-coordinate value.
698 k32f y; ///< Y-coordinate value.
699 } kPoint32f;
700
701 /**
702 * @struct kPoint16s
703 * @extends kValue
704 * @ingroup kApi-Data
705 * @brief 2D point structure with 64-bit floating-point fields.
706 */
707 typedef struct kPoint64f
708 {
709 k64f x; ///< X-coordinate value.
710 k64f y; ///< Y-coordinate value.
711 } kPoint64f;
712
713 /**
714 * Initializes a point structure.
715 *
716 * @param POINT Pointer to a point structure.
717 * @param X x field value.
718 * @param Y y field value.
719 */
720 #define kPoint_Init_(POINT, X, Y) kxPoint_Init_(POINT, X, Y)
721
722 /**
723 * @struct kPoint3d16s
724 * @extends kValue
725 * @ingroup kApi-Data
726 * @brief 3D point structure with 16-bit signed integer fields.
727 */
728 typedef struct kPoint3d16s
729 {
730 k16s x; ///< X-coordinate value.
731 k16s y; ///< Y-coordinate value.
732 k16s z; ///< Z-coordinate value.
733 } kPoint3d16s;
734
735 /**
736 * @struct kPoint16s
737 * @extends kValue
738 * @ingroup kApi-Data
739 * @brief 3D point structure with 32-bit signed integer fields.
740 */
741 typedef struct kPoint3d32s
742 {
743 k32s x; ///< X-coordinate value.
744 k32s y; ///< Y-coordinate value.
745 k32s z; ///< Z-coordinate value.
746 } kPoint3d32s;
747
748 /**
749 * @struct kPoint3d32f
750 * @extends kValue
751 * @ingroup kApi-Data
752 * @brief 3D point structure with 32-bit floating-point fields.
753 */
754 typedef struct kPoint3d32f
755 {
756 k32f x; ///< X-coordinate value.
757 k32f y; ///< Y-coordinate value.
758 k32f z; ///< Z-coordinate value.
759 } kPoint3d32f;
760
761 /**
762 * @struct kPoint3d64f
763 * @extends kValue
764 * @ingroup kApi-Data
765 * @brief 3D point structure with 64-bit floating-point fields.
766 */
767 typedef struct kPoint3d64f
768 {
769 k64f x; ///< X-coordinate value.
770 k64f y; ///< Y-coordinate value.
771 k64f z; ///< Z-coordinate value.
772 } kPoint3d64f;
773
774 /**
775 * Initializes a 3d point structure.
776 *
777 * @param POINT Pointer to a 3d point structure.
778 * @param X x field value.
779 * @param Y y field value.
780 * @param Z z field value.
781 */
782 #define kPoint3d_Init_(POINT, X, Y, Z) kxPoint3d_Init_(POINT, X, Y, Z)
783
784 /**
785 * @struct kRect16s
786 * @extends kValue
787 * @ingroup kApi-Data
788 * @brief Rectangle structure with 16-bit signed integer fields.
789 */
790 typedef struct kRect16s
791 {
792 k16s x; ///< X-coordinate of the origin.
793 k16s y; ///< Y-coordinate of the origin.
794 k16s width; ///< Width of the rectangle.
795 k16s height; ///< Height of the rectangle.
796 } kRect16s;
797
798 /**
799 * @struct kRect32s
800 * @extends kValue
801 * @ingroup kApi-Data
802 * @brief Rectangle structure with 32-bit signed integer fields.
803 */
804 typedef struct kRect32s
805 {
806 k32s x; ///< X-coordinate of the origin.
807 k32s y; ///< Y-coordinate of the origin.
808 k32s width; ///< Width of the rectangle.
809 k32s height; ///< Height of the rectangle.
810 } kRect32s;
811
812 /**
813 * @struct kRect32f
814 * @extends kValue
815 * @ingroup kApi-Data
816 * @brief Rectangle structure with 32-bit floating-point fields.
817 */
818 typedef struct kRect32f
819 {
820 k32f x; ///< X-coordinate of the origin.
821 k32f y; ///< Y-coordinate of the origin.
822 k32f width; ///< Width of the rectangle.
823 k32f height; ///< Height of the rectangle.
824 } kRect32f;
825
826 /**
827 * @struct kRect64f
828 * @extends kValue
829 * @ingroup kApi-Data
830 * @brief Rectangle structure with 64-bit floating-point fields.
831 */
832 typedef struct kRect64f
833 {
834 k64f x; ///< X-coordinate of the origin.
835 k64f y; ///< Y-coordinate of the origin.
836 k64f width; ///< Width of the rectangle.
837 k64f height; ///< Height of the rectangle.
838 } kRect64f;
839
840 /**
841 * Initializes a rectangle structure.
842 *
843 * @param RECT Pointer to a rectangle structure.
844 * @param X x field value.
845 * @param Y y field value.
846 * @param W width field value.
847 * @param H height field value.
848 */
849 #define kRect_Init_(RECT, X, Y, W, H) kxRect_Init_(RECT, X, Y, W, H)
850
851 /**
852 * @struct kRotatedRect32s
853 * @extends kValue
854 * @ingroup kApi-Data
855 * @brief Rotated rectangle structure with 32-bit signed integer fields.
856 */
857 typedef struct kRotatedRect32s
858 {
859 k32s xc; ///< X-coordinate of the rectangle center.
860 k32s yc; ///< Y-coordinate of the rectangle center.
861 k32s width; ///< Width of the rectangle.
862 k32s height; ///< Height of the rectangle.
863 k32s angle; ///< Rotation angle of the rectangle.
864 } kRotatedRect32s;
865
866 /**
867 * @struct kRotatedRect32f
868 * @extends kValue
869 * @ingroup kApi-Data
870 * @brief Rotated rectangle structure with 32-bit floating-point fields.
871 */
872 typedef struct kRotatedRect32f
873 {
874 k32f xc; ///< X-coordinate of the rectangle center.
875 k32f yc; ///< Y-coordinate of the rectangle center.
876 k32f width; ///< Width of the rectangle.
877 k32f height; ///< Height of the rectangle.
878 k32f angle; ///< Rotation angle of the rectangle.
879 } kRotatedRect32f;
880
881 /**
882 * Initializes a rotated rectangle structure.
883 *
884 * @param RECT Pointer to a rotated rectangle structure.
885 * @param XC xc field value.
886 * @param YC yc field value.
887 * @param W width field value.
888 * @param H height field value.
889 * @param A angle field value.
890 */
891 #define kRotatedRect_Init_(RECT, XC, YC, W, H, A) kxRotatedRect_Init_(RECT, XC, YC, W, H, A)
892
893 /**
894 * @struct kPixelFormat
895 * @extends kValue
896 * @ingroup kApi-Data
897 * @brief Pixel format descriptor enumeration.
898 *
899 * The following enumerators are defined:
900 * - #kPIXEL_FORMAT_NULL
901 * - #kPIXEL_FORMAT_8BPP_GREYSCALE
902 * - #kPIXEL_FORMAT_8BPP_CFA
903 * - #kPIXEL_FORMAT_8BPC_BGRX
904 */
905 typedef k32s kPixelFormat;
906
907 #define kPIXEL_FORMAT_NULL (0) ///< Unknown pixel format.
908 #define kPIXEL_FORMAT_8BPP_GREYSCALE (1) ///< 8-bit greyscale (k8u)
909 #define kPIXEL_FORMAT_8BPP_CFA (2) ///< 8-bit color filter array (k8u)
910 #define kPIXEL_FORMAT_8BPC_BGRX (3) ///< 8-bits-per-channel color with 4 channels (blue/green/red/unused)(kRgb)
911
912 /**
913 * @struct kCfa
914 * @extends kValue
915 * @ingroup kApi-Data
916 * @brief Image color filter array enumeration.
917 *
918 * The following enumerators are defined:
919 * - #kCFA_NONE
920 * - #kCFA_BAYER_BGGR
921 * - #kCFA_BAYER_GBRG
922 * - #kCFA_BAYER_RGGB
923 * - #kCFA_BAYER_GRBG
924 */
925 typedef k32s kCfa;
926
927 #define kCFA_NONE (0) ///< No color filter.
928 #define kCFA_BAYER_BGGR (1) ///< Bayer filter: BG/GR.
929 #define kCFA_BAYER_GBRG (2) ///< Bayer filter: GB/RG.
930 #define kCFA_BAYER_RGGB (3) ///< Bayer filter: RG/GB.
931 #define kCFA_BAYER_GRBG (4) ///< Bayer filter: GR/BG.
932
933 /**
934 * @struct kRgb
935 * @extends kValue
936 * @ingroup kApi-Data
937 * @brief RGB color pixel structure.
938 */
939 typedef struct kRgb
940 {
941 k8u b; ///< Blue component value.
942 k8u g; ///< Green component value.
943 k8u r; ///< Red component value.
944 k8u x; ///< Undefined.
945 } kRgb;
946
947 /**
948 * Initializes a kRgb structure.
949 *
950 * @param RGB Pointer to a kRgb structure.
951 * @param R r field value.
952 * @param G g field value.
953 * @param B b field value.
954 */
955 #define kRgb_Init_(RGB, R, G, B) kxRgb_Init_(RGB, R, G, B)
956
957 /**
958 * @struct kArgb
959 * @extends kValue
960 * @ingroup kApi-Data
961 * @brief ARGB color pixel structure.
962 */
963 typedef struct kArgb
964 {
965 k8u b; ///< Blue component value.
966 k8u g; ///< Green component value.
967 k8u r; ///< Red component value.
968 k8u a; ///< Alpha component value.
969 } kArgb;
970
971 /**
972 * Initializes a kArgb structure.
973 *
974 * @param ARGB Pointer to a kArgb structure.
975 * @param A a field value.
976 * @param R r field value.
977 * @param G g field value.
978 * @param B b field value.
979 */
980 #define kArgb_Init_(ARGB, A, R, G, B) kxArgb_Init_(ARGB, A, R, G, B)
981
982 /**
983 * @struct kComparison
984 * @extends kValue
985 * @ingroup kApi-Data
986 * @brief Comparison type enumeration.
987 *
988 * The following enumerators are defined:
989 * - #kCOMPARISON_EQ
990 * - #kCOMPARISON_NEQ
991 * - #kCOMPARISON_LT
992 * - #kCOMPARISON_LTE
993 * - #kCOMPARISON_GT
994 * - #kCOMPARISON_GTE
995 */
996 typedef k32s kComparison;
997
998 #define kCOMPARISON_EQ (0) ///< Is equal.
999 #define kCOMPARISON_NEQ (1) ///< Is not equal.
1000 #define kCOMPARISON_LT (2) ///< Is less than.
1001 #define kCOMPARISON_LTE (3) ///< Is less than or equal.
1002 #define kCOMPARISON_GT (4) ///< Is greater than.
1003 #define kCOMPARISON_GTE (5) ///< Is greater than or equal.
1004
1005 /**
1006 * Callback signature to determine equality of two items.
1007 *
1008 * @param item1 Pointer to first item.
1009 * @param item2 Pointer to second item.
1010 * @return kTRUE if the arguments are equal; kFALSE otherwise.
1011 */
1012 typedef kBool (kCall* kEqualsFx)(const void* item1, const void* item2);
1013
1014 /**
1015 * Callback signature to determine hash code of an item.
1016 *
1017 * @param item Pointer to item.
1018 * @return Item hash code.
1019 */
1020 typedef kSize (kCall* kHashFx)(const void* item);
1021
1022 /**
1023 * Callback signature for a generic event handler.
1024 *
1025 * @param receiver Receiver context pointer.
1026 * @param sender Sender context pointer.
1027 * @param args Pointer to callback argument.
1028 * @return Operation status.
1029 */
1030 typedef kStatus (kCall* kCallbackFx)(kPointer receiver, kPointer sender, void* args);
1031
1032 /**
1033 * @struct kCallback
1034 * @extends kValue
1035 * @ingroup kApi
1036 * @brief Represents a callback function and context pointer.
1037 */
1038 typedef struct kCallback
1039 {
1040 kCallbackFx function; ///< Callback function.
1041 kPointer receiver; ///< Callback receiver context pointer.
1042 } kCallback;
1043
1044 /**
1045 * @struct kFileMode
1046 * @extends kValue
1047 * @ingroup kApi-Io
1048 * @brief Flags that control how a file is opened.
1049 *
1050 * The following enumerators are defined:
1051 * - #kFILE_MODE_READ
1052 * - #kFILE_MODE_WRITE
1053 * - #kFILE_MODE_UPDATE
1054 */
1055 typedef k32s kFileMode;
1056
1057 #define kFILE_MODE_READ (0x1) ///< Open the file with permission to read.
1058 #define kFILE_MODE_WRITE (0x2) ///< Open the file with permission to write.
1059 #define kFILE_MODE_UPDATE (0x4) ///< Preserve contents when opened for writing.
1060
1061 /**
1062 * @struct kSeekOrigin
1063 * @extends kValue
1064 * @ingroup kApi-Io
1065 * @brief Seek origin enumeration.
1066 *
1067 * The following enumerators are defined:
1068 * - #kSEEK_ORIGIN_BEGIN
1069 * - #kSEEK_ORIGIN_CURRENT
1070 * - #kSEEK_ORIGIN_END
1071 */
1072 typedef k32s kSeekOrigin;
1073
1074 #define kSEEK_ORIGIN_BEGIN (0) ///< Seek relative to the start of stream.
1075 #define kSEEK_ORIGIN_CURRENT (1) ///< Seek relative to the current position.
1076 #define kSEEK_ORIGIN_END (2) ///< Seek relative to the end of stream.
1077
1078 /**
1079 * Returns the kType object associated with the specified class, interface, or value symbol.
1080 *
1081 * This macro is used to access type information by compile-time symbol name. E.g.
1082 *
1083 * @code
1084 *
1085 * #include <kApi/Data/kImage.h>
1086 *
1087 * void PrintImageTypeInfo()
1088 * {
1089 * kType type = kTypeOf(kImage);
1090 *
1091 * printf("Type name: %s\n", kType_Name(type));
1092 * printf("Base class: %s\n", kType_Name(kType_Base(type)));
1093 * }
1094 *
1095 * @endcode
1096 *
1097 * Use of this macro requires that the header file defining the specified type symbol has
1098 * been included. For example, kTypeOf(kArrayList) requires inclusion of <kApi/Data/kArrayList.h>.
1099 *
1100 * @param SYMBOL Type symbol, such as kArrayList or k32s.
1101 * @return kType object representing metadata about the specified type.
1102 */
1103 #define kTypeOf(SYMBOL) kTypeOf_(SYMBOL)
1104
1105 /**
1106 * Returns the kAssembly object associated with the specified assembly symbol.
1107 *
1108 * This macro is used to access assembly information by compile-time symbol name. E.g.
1109 *
1110 * @code
1111 *
1112 * #include <kApi/kApiLib.h>
1113 *
1114 * void PrintCoreAssemblyInfo()
1115 * {
1116 * kAssembly assembly = kAssemblyOf(kApiLib);
1117 *
1118 * printf("Assembly name: %s\n", kAssembly_Name(assembly));
1119 * printf("Type count: %u\n", (k32u) kAssembly_TypeCount(assembly));
1120 * }
1121 *
1122 * @endcode
1123 *
1124 * Use of this macro requires that the header file defining the specified assembly symbol
1125 * has been included. For example, kAssemblyOf(kApiLib) requires inclusion of <kApi/kApiLib.h>
1126 *
1127 * @param SYMBOL Assembly symbol, such as <em>kApiLib</em>.
1128 * @return kAssembly object representing metadata about the specified assembly.
1129 */
1130 #define kAssemblyOf(SYMBOL) kAssemblyOf_(SYMBOL)
1131
1132 /**
1133 * Returns static data associated with the specified class symbol.
1134 *
1135 * This macro is used within class implementations to access static state.
1136 *
1137 * @param SYMBOL Class symbol, such as <em>kArrayList</em>.
1138 * @return Pointer to static data for the specified class.
1139 */
1140 #define kStaticOf(SYMBOL) kStaticOf_(SYMBOL)
1141
1142 /**
1143 * Indicates whether static initialization has completed for the specified type symbol.
1144 *
1145 * @param SYMBOL Class symbol, such as <em>kArrayList</em>.
1146 * @return kTRUE if initialization has completed; kFALSE otherwise.
1147 */
1148 #define kStaticInitialized(SYMBOL) kStaticInitialized_(SYMBOL)
1149
1150 /**
1151 * Returns the number of elements in a C array.
1152 *
1153 * Equivalent to sizeof(CARRAY)/sizeof(CARRAY[0]).
1154 *
1155 * @param CARRAY C array variable name.
1156 * @return Count of array elements.
1157 */
1158 #define kCountOf(CARRAY) kCountOf_(CARRAY)
1159
1160 /**
1161 * Casts the ITEM argument to the specified TYPE.
1162 *
1163 * Equivalent (TYPE)(ITEM).
1164 *
1165 * This macro is guaranteed to evaluate its arguments only once.
1166 *
1167 * @param TYPE Type to which the item is cast.
1168 * @param ITEM Value to be cast.
1169 * @return Result of the cast.
1170 */
1171 #define kCast(TYPE, ITEM) kCast_(TYPE, ITEM)
1172
1173 /**
1174 * Returns the minimum of two numbers.
1175 *
1176 * @param A First value.
1177 * @param B Second value.
1178 * @return The lesser of A or B.
1179 */
1180 #define kMin_(A, B) kxMin_(A, B)
1181
1182 /**
1183 * Returns the maximum of two numbers.
1184 *
1185 * @param A First value.
1186 * @param B Second value.
1187 * @return The greater of A or B.
1188 */
1189 #define kMax_(A, B) kxMax_(A, B)
1190
1191 /**
1192 * Returns a value limited to the specified range.
1193 *
1194 * @param V Input value.
1195 * @param VMIN Minimum output value.
1196 * @param VMAX Maximum output value.
1197 * @return The input value, limited to [VMIN, VMAX].
1198 */
1199 #define kClamp_(V, VMIN, VMAX) kxClamp_((V), (VMIN), (VMAX))
1200
1201 /**
1202 * Returns the absolute value of a number.
1203 *
1204 * @param A Input value.
1205 * @return Absolute value of input argument.
1206 */
1207 #define kAbs_(A) kxAbs_(A)
1208
1209 /**
1210 * Sets all bits of a structure to zero.
1211 *
1212 * @param VALUE Structure instance.
1213 */
1214 #define kZero_(VALUE) kxZero_(VALUE)
1215
1216 /**
1217 * Performs a small copy with minimal overhead.
1218 *
1219 * @param DEST Destination address.
1220 * @param SRC Source address.
1221 * @param SIZE Transfer size (bytes).
1222 */
1223 #define kItemCopy_(DEST, SRC, SIZE) kxItemCopy_(DEST, SRC, SIZE)
1224
1225 /**
1226 * Performs a small fill with minimal overhead.
1227 *
1228 * @param DEST Destination address.
1229 * @param FILL Value to fill (byte).
1230 * @param SIZE Fill size (bytes).
1231 */
1232 #define kItemSet_(DEST, FILL, SIZE) kxItemSet_(DEST, FILL, SIZE)
1233
1234 /**
1235 * Zero-initializes a small amount of memory with minimal overhead.
1236 *
1237 * @param DEST Destination address.
1238 * @param SIZE Transfer size (bytes).
1239 */
1240 #define kItemZero_(DEST, SIZE) kItemSet_(DEST, 0, SIZE)
1241
1242 /**
1243 * Gets a pointer to the Nth element of an array.
1244 *
1245 * @param BASE Array pointer.
1246 * @param INDEX Element index.
1247 * @param SIZE Element size.
1248 */
1249 #define kItemAt_(BASE, INDEX, SIZE) kAt_((BASE), (INDEX)*(SIZE))
1250
1251 /**
1252 * Declares a type assembly.
1253 *
1254 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1255 * @param SYMBOL Assembly symbol name (e.g. <em>kApi</em>).
1256 * @see @ref extending, kBeginAssembly, kEndAssembly
1257 */
1258 #define kDeclareAssembly(PREFIX, SYMBOL) kDeclareAssembly_(PREFIX, SYMBOL)
1259
1260 /**
1261 * Starts the definition of a type assembly.
1262 *
1263 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1264 * @param SYMBOL Assembly symbol name (e.g. <em>kApi</em>).
1265 * @param VERSION Assembly version string (e.g. "6.0.0.0").
1266 * @see @ref extending, kEndAssembly
1267 */
1268 #define kBeginAssembly(PREFIX, SYMBOL, VERSION) kBeginAssembly_(PREFIX, SYMBOL, VERSION)
1269
1270 /**
1271 * Ends the definition of a type assembly.
1272 *
1273 * @see @ref extending
1274 */
1275 #define kEndAssembly() kEndAssembly_()
1276
1277 /**
1278 * Declares type information for a structure value type.
1279 *
1280 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1281 * @param SYMBOL Value symbol(e.g. <em>k32s</em>).
1282 * @param BASE Value base symbol (typically <em>kValue</em>).
1283 * @see @ref extending, kBeginValue, kEndValue
1284 */
1285 #define kDeclareValue(PREFIX, SYMBOL, BASE) kDeclareValue_(PREFIX, SYMBOL, BASE)
1286
1287 /**
1288 * Starts the definition of a structure value type.
1289 *
1290 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1291 * @param SYMBOL Value symbol(e.g. <em>k32s</em>).
1292 * @param BASE Value base symbol (typically <em>kValue</em>).
1293 * @see @ref extending, kEndValue
1294 */
1295 #define kBeginValue(PREFIX, SYMBOL, BASE) kBeginValue_(PREFIX, SYMBOL, BASE)
1296
1297 /**
1298 * Ends the definition of a structure value type.
1299 *
1300 * @see @ref extending
1301 */
1302 #define kEndValue() kEndValue_()
1303
1304 /**
1305 * Declares type information for an enumeration value type.
1306 *
1307 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1308 * @param SYMBOL Value symbol(e.g. <em>kStatus</em>).
1309 * @param BASE Value base symbol (typically <em>kValue</em>).
1310 * @see @ref extending, kBeginEnum, kEndEnum
1311 */
1312 #define kDeclareEnum(PREFIX, SYMBOL, BASE) kDeclareEnum_(PREFIX, SYMBOL, BASE)
1313
1314 /**
1315 * Starts the definition of an enumeration value type.
1316 *
1317 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1318 * @param SYMBOL Value symbol(e.g. <em>kStatus</em>).
1319 * @param BASE Value base symbol (typically <em>kValue</em>).
1320 * @see @ref extending, kEndEnum
1321 */
1322 #define kBeginEnum(PREFIX, SYMBOL, BASE) kBeginEnum_(PREFIX, SYMBOL, BASE)
1323
1324 /**
1325 * Ends the definition of an enumeration value type.
1326 *
1327 * @see @ref extending
1328 */
1329 #define kEndEnum() kEndEnum_()
1330
1331 /**
1332 * Declares type information for a bit-flag enumeration value type.
1333 *
1334 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1335 * @param SYMBOL Value symbol(e.g. <em>kFileMode</em>).
1336 * @param BASE Value base symbol (typically <em>kValue</em>).
1337 * @see @ref extending, kBeginBitEnum, kEndBitEnum
1338 */
1339 #define kDeclareBitEnum(PREFIX, SYMBOL, BASE) kDeclareBitEnum_(PREFIX, SYMBOL, BASE)
1340
1341 /**
1342 * Starts the definition of a bit-flag enumeration value type.
1343 *
1344 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1345 * @param SYMBOL Value symbol(e.g. <em>kFileMode</em>).
1346 * @param BASE Value base symbol (typically <em>kValue</em>).
1347 * @see @ref extending, kEndBitEnum
1348 */
1349 #define kBeginBitEnum(PREFIX, SYMBOL, BASE) kBeginBitEnum_(PREFIX, SYMBOL, BASE)
1350
1351 /**
1352 * Ends the definition of a bit-flag enumeration value type.
1353 *
1354 * @see @ref extending
1355 */
1356 #define kEndBitEnum() kEndBitEnum_()
1357
1358 /**
1359 * Declares type information for an array-based value type.
1360 *
1361 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1362 * @param SYMBOL Value symbol(e.g. <em>kText32</em>).
1363 * @param BASE Value base symbol (typically <em>kValue</em>).
1364 * @see @ref extending, kBeginArrayValue, kEndArrayValue
1365 */
1366 #define kDeclareArrayValue(PREFIX, SYMBOL, BASE) kDeclareArrayValue_(PREFIX, SYMBOL, BASE)
1367
1368 /**
1369 * Starts the definition of an array-based value type.
1370 *
1371 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1372 * @param SYMBOL Value symbol(e.g. <em>kText32</em>).
1373 * @param TYPE Array element type symbol(e.g. <em>kChar</em>).
1374 * @param BASE Value base symbol (typically <em>kValue</em>).
1375 * @see @ref extending, kEndArrayValue
1376 */
1377 #define kBeginArrayValue(PREFIX, SYMBOL, TYPE, BASE) kBeginArrayValue_(PREFIX, SYMBOL, TYPE, BASE)
1378
1379 /**
1380 * Ends the definition of an array-based value type.
1381 *
1382 * @see @ref extending
1383 */
1384 #define kEndArrayValue() kEndArrayValue_()
1385
1386 /**
1387 * Declares type information for an interface type.
1388 *
1389 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1390 * @param SYMBOL Interface symbol(e.g. <em>kCollection</em>).
1391 * @param BASE Interface base symbol (typically <em>kNull</em>).
1392 * @see @ref extending, kBeginInterface, kEndInterface
1393 */
1394 #define kDeclareInterface(PREFIX, SYMBOL, BASE) kDeclareInterface_(PREFIX, SYMBOL, BASE)
1395
1396 /**
1397 * Starts the definition of an interface type.
1398 *
1399 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1400 * @param SYMBOL Interface symbol(e.g. <em>kCollection</em>).
1401 * @param BASE Interface base symbol (typically <em>kNull</em>).
1402 * @see @ref extending, kEndInterface
1403 */
1404 #define kBeginInterface(PREFIX, SYMBOL, BASE) kBeginInterface_(PREFIX, SYMBOL, BASE)
1405
1406 /**
1407 * Ends the definition of an interface type.
1408 *
1409 * @see @ref extending
1410 */
1411 #define kEndInterface() kEndInterface_()
1412
1413 /**
1414 * Declares type information for a class type.
1415 *
1416 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1417 * @param SYMBOL Class symbol(e.g. <em>kFile</em>).
1418 * @param BASE Class base symbol (e.g. <em>kObject</em>).
1419 * @see @ref extending, kBeginFullClass, kEndFullClass
1420 */
1421 #define kDeclareFullClass(PREFIX, SYMBOL, BASE) kDeclareFullClass_(PREFIX, SYMBOL, BASE)
1422
1423 /**
1424 * Starts the definition of a class type.
1425 *
1426 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1427 * @param SYMBOL Class symbol(e.g. <em>kFile</em>).
1428 * @param BASE Class base symbol (e.g. <em>kObject</em>).
1429 * @see @ref extending, kEndFullClass
1430 */
1431 #define kBeginFullClass(PREFIX, SYMBOL, BASE) kBeginFullClass_(PREFIX, SYMBOL, BASE)
1432
1433 /**
1434 * Ends the definition of a class type.
1435 *
1436 * @see @ref extending
1437 */
1438 #define kEndFullClass() kEndFullClass_()
1439
1440 /**
1441 * Declares type information for a class type that requires an expanded vtable but does not have static data.
1442 *
1443 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1444 * @param SYMBOL Class symbol(e.g. <em>kAlloc</em>).
1445 * @param BASE Class base symbol (e.g. <em>kObject</em>).
1446 * @see @ref extending, kBeginVirtualClass, kEndVirtualClass
1447 */
1448 #define kDeclareVirtualClass(PREFIX, SYMBOL, BASE) kDeclareVirtualClass_(PREFIX, SYMBOL, BASE)
1449
1450 /**
1451 * Starts the definition of a class type that requires an expanded vtable but does not have static data.
1452 *
1453 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1454 * @param SYMBOL Class symbol(e.g. <em>kAlloc</em>).
1455 * @param BASE Class base symbol (e.g. <em>kObject</em>).
1456 * @see @ref extending, kEndVirtualClass
1457 */
1458 #define kBeginVirtualClass(PREFIX, SYMBOL, BASE) kBeginVirtualClass_(PREFIX, SYMBOL, BASE)
1459
1460 /**
1461 * Ends the definition of a class type that requires an expanded vtable but does not have static data.
1462 *
1463 * @see @ref extending
1464 */
1465 #define kEndVirtualClass() kEndVirtualClass_()
1466
1467 /**
1468 * Declares type information for a class type that has only static data.
1469 *
1470 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1471 * @param SYMBOL Class symbol(e.g. <em>kNetwork</em>).
1472 * @see @ref extending, kBeginStaticClass, kEndStaticClass
1473 */
1474 #define kDeclareStaticClass(PREFIX, SYMBOL) kDeclareStaticClass_(PREFIX, SYMBOL)
1475
1476 /**
1477 * Starts the definition of a class type that has only static data.
1478 *
1479 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1480 * @param SYMBOL Class symbol(e.g. <em>kNetwork</em>).
1481 * @see @ref extending, kEndFullClass
1482 */
1483 #define kBeginStaticClass(PREFIX, SYMBOL) kBeginStaticClass_(PREFIX, SYMBOL)
1484
1485 /**
1486 * Ends the definition of a class type that has only static data.
1487 *
1488 * @see @ref extending
1489 */
1490 #define kEndStaticClass() kEndStaticClass_()
1491
1492 /**
1493 * Declares type information for a class type that does not require an expanded vtable and does not have static data.
1494 *
1495 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1496 * @param SYMBOL Class symbol(e.g. <em>kArrayList</em>).
1497 * @param BASE Class base symbol (e.g. <em>kObject</em>).
1498 * @see @ref extending, kBeginClass, kEndClass
1499 */
1500 #define kDeclareClass(PREFIX, SYMBOL, BASE) kDeclareClass_(PREFIX, SYMBOL, BASE)
1501
1502 /**
1503 * Starts the definition of a class type that does not require an expanded vtable and does not have static data.
1504 *
1505 * @param PREFIX Function/data declaration prefix (e.g. <em>k</em>).
1506 * @param SYMBOL Class symbol(e.g. <em>kArrayList</em>).
1507 * @param BASE Class base symbol (e.g. <em>kObject</em>).
1508 * @see @ref extending, kEndClass
1509 */
1510 #define kBeginClass(PREFIX, SYMBOL, BASE) kBeginClass_(PREFIX, SYMBOL, BASE)
1511
1512 /**
1513 * Ends the definition of a class type that does not require an expanded vtable and does not have static data.
1514 *
1515 * @see @ref extending
1516 */
1517 #define kEndClass() kEndClass_()
1518
1519 /**
1520 * Within an assembly definition, specifies a dependency on another assembly.
1521 *
1522 * @param SYMBOL Dependency target (e.g. <em>kApi</em>).
1523 * @see @ref extending
1524 */
1525 #define kAddDependency(SYMBOL) kAddDependency_(SYMBOL)
1526
1527 /**
1528 * Within an assembly definition, adds a type to the assembly.
1529 *
1530 * @param SYMBOL Type symbol (e.g. <em>kArrayList</em>).
1531 * @see @ref extending
1532 */
1533 #define kAddType(SYMBOL) kAddType_(SYMBOL)
1534
1535 /**
1536 * Within an assembly definition, indicates a requirement on static initialization order.
1537 *
1538 * The order of kAddPriority statements within an assembly definition determines the order
1539 * in which types will be initialized. If initialization priorities are not given, types
1540 * can be initialized in any order.
1541 *
1542 * @param SYMBOL Type symbol (e.g. <em>kArrayList</em>).
1543 * @see @ref extending
1544 */
1545 #define kAddPriority(SYMBOL) kAddPriority_(SYMBOL)
1546
1547 /**
1548 * Within a type definition, indicates that a type implements the specified interface.
1549 *
1550 * @param SYMBOL Type symbol (e.g. <em>kArrayList</em>).
1551 * @param IFACE Interface symbol (e.g. <em>kCollection</em>).
1552 * @see @ref extending
1553 */
1554 #define kAddInterface(SYMBOL, IFACE) kAddInterface_(SYMBOL, IFACE)
1555
1556 /**
1557 * Within a type definition, indicates that a type has the specified non-virtual method.
1558 *
1559 * @param SYMBOL Type symbol (e.g. <em>kArrayList</em>).
1560 * @param METHOD Method name (e.g. <em>Remove</em>).
1561 * @see @ref extending
1562 */
1563 #define kAddMethod(SYMBOL, METHOD) kAddMethod_(SYMBOL, METHOD)
1564
1565 /**
1566 * Within a type definition, indicates that a type overrides the specified virtual method.
1567 *
1568 * @param IN_TYPE Overriding type (e.g. <em>kArrayList</em>).
1569 * @param FROM_TYPE Overridden type (e.g. <em>kObject</em>).
1570 * @param METHOD Method name (e.g. <em>VRelease</em>).
1571 * @see @ref extending
1572 */
1573 #define kAddVMethod(IN_TYPE, FROM_TYPE, METHOD) kAddVMethod_(IN_TYPE, FROM_TYPE, METHOD)
1574
1575 /**
1576 * Within a type definition, indicates that a type implements the specified interface method.
1577 *
1578 * @param IN_TYPE Overriding type (e.g. <em>kArrayList</em>).
1579 * @param FROM_IFACE Overridden interface (e.g. <em>kCollection</em>).
1580 * @param IMETHOD Interface method name (e.g. <em>VGetIterator</em>).
1581 * @param CMETHOD Type method name (e.g. <em>GetIterator</em>).
1582 * @see @ref extending
1583 */
1584 #define kAddIVMethod(IN_TYPE, FROM_IFACE, IMETHOD, CMETHOD) kAddIVMethod_(IN_TYPE, FROM_IFACE, IMETHOD, CMETHOD)
1585
1586 /**
1587 * Within a structure type definition, indicates that a structure has the specified field.
1588 *
1589 * @param VALUE Structure type (e.g. <em>kPoint32s</em>).
1590 * @param FIELD_TYPE Field type (e.g. <em>k32s</em>).
1591 * @param FIELD Field name (e.g. <em>x</em>).
1592 * @see @ref extending
1593 */
1594 #define kAddField(VALUE, FIELD_TYPE, FIELD) kAddField_(VALUE, FIELD_TYPE, FIELD)
1595
1596 /**
1597 * Within an enumeration type definition, indicates that an enumeration has the specified enumerator.
1598 *
1599 * @param VALUE Enumeration type (e.g. <em>kStatus</em>).
1600 * @param ENUMERATOR Enumerator(e.g. <em>kERROR</em>).
1601 * @see @ref extending
1602 */
1603 #define kAddEnumerator(VALUE, ENUMERATOR) kAddEnumerator_(VALUE, ENUMERATOR)
1604
1605 /**
1606 * Within a type definition, indicates that a type has the specified serialization version.
1607 *
1608 * @param TYPE Type symbol (e.g. <em>kArrayList</em>).
1609 * @param FORMAT Serialization format name string (e.g. "kdat6").
1610 * @param FORMAT_VER Serialization format version string (e.g. "5.7.1.0").
1611 * @param GUID Type identifier string within serialization format (e.g. "kArrayList-0").
1612 * @param WRITE_METHOD Serialization write method (e.g. <em>WriteDat6V0</em>).
1613 * @param READ_METHOD Serialization read method (e.g. <em>ReadDat6V0</em>).
1614 * @see @ref extending, kSerializer
1615 */
1616 #define kAddVersion(TYPE, FORMAT, FORMAT_VER, GUID, WRITE_METHOD, READ_METHOD) \
1617 kAddVersion_(TYPE, FORMAT, FORMAT_VER, GUID, WRITE_METHOD, READ_METHOD)
1618
1619 /**
1620 * Adds specific flags to type metadata.
1621 *
1622 * @param TYPE Type (e.g. <em>kObject</em>).
1623 * @param FLAGS Type flags (e.g. <em>kTYPE_FLAGS_ABSTRACT</em>).
1624 * @see @ref extending
1625 */
1626 #define kAddFlags(TYPE, FLAGS) kAddFlags_(TYPE, FLAGS)
1627
1628 kEndHeader()
1629
1630 #include <kApi/kApiDef.x.h>
1631
1632 #endif
kText64
Represents a 64-unit, null-terminated, kChar sequence.
k32u
Represents a 32-bit unsigned integer.
kRect32s::y
k32s y
Y-coordinate of the origin.
Definition: kApiDef.h:807
kRect64f::height
k64f height
Height of the rectangle.
Definition: kApiDef.h:837
kRect32f::x
k32f x
X-coordinate of the origin.
Definition: kApiDef.h:820
kRect32s
Rectangle structure with 32-bit signed integer fields.
Definition: kApiDef.h:804
kPoint3d32f
3D point structure with 32-bit floating-point fields.
Definition: kApiDef.h:754
kRect64f::x
k64f x
X-coordinate of the origin.
Definition: kApiDef.h:834
kRotatedRect32s::width
k32s width
Width of the rectangle.
Definition: kApiDef.h:861
kRgb::b
k8u b
Blue component value.
Definition: kApiDef.h:941
kStatus::kStatus_Name
const kChar * kStatus_Name(kStatus status)
Returns a text string representing the name of a status code (e.g.
kRect16s::width
k16s width
Width of the rectangle.
Definition: kApiDef.h:794
kArgb
ARGB color pixel structure.
Definition: kApiDef.h:963
kRect16s::y
k16s y
Y-coordinate of the origin.
Definition: kApiDef.h:793
kPoint16s
2D point structure with 16-bit signed integer fields.
Definition: kApiDef.h:671
k64u
Represents a 64-bit unsigned integer.
kApiCfg.h
Architecture/compiler-specific definitions.
kText256
Represents a 256-unit, null-terminated, kChar sequence.
kCallback::receiver
kPointer receiver
Callback receiver context pointer.
Definition: kApiDef.h:1041
kRotatedRect32f
Rotated rectangle structure with 32-bit floating-point fields.
Definition: kApiDef.h:872
kRect64f::y
k64f y
Y-coordinate of the origin.
Definition: kApiDef.h:835
kCallbackFx
kStatus(kCall * kCallbackFx)(kPointer receiver, kPointer sender, void *args)
Callback signature for a generic event handler.
Definition: kApiDef.h:1030
kPointer
Represents a void pointer.
kRgb
RGB color pixel structure.
Definition: kApiDef.h:939
kPoint3d16s::z
k16s z
Z-coordinate value.
Definition: kApiDef.h:732
k16u
Represents a 16-bit unsigned integer.
kRotatedRect32s::xc
k32s xc
X-coordinate of the rectangle center.
Definition: kApiDef.h:859
kRotatedRect32s
Rotated rectangle structure with 32-bit signed integer fields.
Definition: kApiDef.h:857
kRotatedRect32f::yc
k32f yc
Y-coordinate of the rectangle center.
Definition: kApiDef.h:875
kSize
Represents an unsigned integer that can store a pointer address.
kRotatedRect32s::angle
k32s angle
Rotation angle of the rectangle.
Definition: kApiDef.h:863
k8u
Represents an 8-bit unsigned integer.
kPoint3d64f::y
k64f y
Y-coordinate value.
Definition: kApiDef.h:770
kPoint3d64f::x
k64f x
X-coordinate value.
Definition: kApiDef.h:769
kVersion::kVersion_Build
k8u kVersion_Build(kVersion version)
Returns the build part of a version number.
kVersion::kVersion_Parse
kStatus kVersion_Parse(kVersion *version, const kChar *buffer)
Parses a version from a formatted string.
kChar
Represents a single unit (byte) in a UTF-8 character.
kByte
Represents a byte on the current platform.
kPoint16s::x
k16s x
X-coordinate value.
Definition: kApiDef.h:673
kPoint3d16s::y
k16s y
Y-coordinate value.
Definition: kApiDef.h:731
kRotatedRect32f::angle
k32f angle
Rotation angle of the rectangle.
Definition: kApiDef.h:878
kSSize
Represents a signed integer that can store a pointer address.
kRect32s::height
k32s height
Height of the rectangle.
Definition: kApiDef.h:809
kRect32f
Rectangle structure with 32-bit floating-point fields.
Definition: kApiDef.h:818
kHashFx
kSize(kCall * kHashFx)(const void *item)
Callback signature to determine hash code of an item.
Definition: kApiDef.h:1020
kRect32s::width
k32s width
Width of the rectangle.
Definition: kApiDef.h:808
kPixelFormat
Pixel format descriptor enumeration.
kRotatedRect32s::height
k32s height
Height of the rectangle.
Definition: kApiDef.h:862
kRect64f
Rectangle structure with 64-bit floating-point fields.
Definition: kApiDef.h:832
kText128
Represents a 128-unit, null-terminated, kChar sequence.
kPoint3d32f::x
k32f x
X-coordinate value.
Definition: kApiDef.h:756
kSeekOrigin
Seek origin enumeration.
kPoint16s::y
k16s y
Y-coordinate value.
Definition: kApiDef.h:674
kPoint3d16s::x
k16s x
X-coordinate value.
Definition: kApiDef.h:730
kPoint3d32f::z
k32f z
Z-coordinate value.
Definition: kApiDef.h:758
kRect64f::width
k64f width
Width of the rectangle.
Definition: kApiDef.h:836
kPoint3d64f::z
k64f z
Z-coordinate value.
Definition: kApiDef.h:771
kCallback
Represents a callback function and context pointer.
Definition: kApiDef.h:1038
kArgb::r
k8u r
Red component value.
Definition: kApiDef.h:967
kRotatedRect32s::yc
k32s yc
Y-coordinate of the rectangle center.
Definition: kApiDef.h:860
k32s
Represents a 32-bit signed integer.
kVersion::kVersion_Compare
k32s kVersion_Compare(kVersion version1, kVersion version2)
Returns an integral value indicating the relationship between the versions.
kEqualsFx
kBool(kCall * kEqualsFx)(const void *item1, const void *item2)
Callback signature to determine equality of two items.
Definition: kApiDef.h:1012
kFunction
void(kCall * kFunction)()
Generic pointer to function.
Definition: kApiDef.h:28
kRgb::r
k8u r
Red component value.
Definition: kApiDef.h:943
kRotatedRect32f::height
k32f height
Height of the rectangle.
Definition: kApiDef.h:877
kRgb::g
k8u g
Green component value.
Definition: kApiDef.h:942
k64s
Represents a 64-bit signed integer.
kVersion::kVersion_Format
kStatus kVersion_Format(kVersion version, kChar *buffer, kSize capacity)
Formats a version to a string buffer.
kText16
Represents a 16-unit, null-terminated, kChar sequence.
kFileMode
Flags that control how a file is opened.
k8s
Represents an 8-bit signed integer.
kRotatedRect32f::width
k32f width
Width of the rectangle.
Definition: kApiDef.h:876
kArgb::b
k8u b
Blue component value.
Definition: kApiDef.h:965
kRect16s::height
k16s height
Height of the rectangle.
Definition: kApiDef.h:795
kArgb::g
k8u g
Green component value.
Definition: kApiDef.h:966
kText32
Represents a 32-unit, null-terminated, kChar sequence.
kPoint3d16s
3D point structure with 16-bit signed integer fields.
Definition: kApiDef.h:728
kVersion::kVersion_Release
k8u kVersion_Release(kVersion version)
Returns the release part of a version number.
k16s
Represents a 16-bit signed integer.
kRect32f::y
k32f y
Y-coordinate of the origin.
Definition: kApiDef.h:821
k32f
Represents a 32-bit floating-point number.
kVersion
Represents a version number.
kArgb::a
k8u a
Alpha component value.
Definition: kApiDef.h:968
kVersion::kVersion_Minor
k8u kVersion_Minor(kVersion version)
Returns the minor part of a version number.
kStatus
Represents an enumeration of error codes.
kRgb::x
k8u x
Undefined.
Definition: kApiDef.h:944
kCall
#define kCall
kApi standard function calling convention.
Definition: kApiDef.h:17
kCfa
Image color filter array enumeration.
kRect32f::width
k32f width
Width of the rectangle.
Definition: kApiDef.h:822
kRect16s
Rectangle structure with 16-bit signed integer fields.
Definition: kApiDef.h:790
kVersion::kVersion_Create
kVersion kVersion_Create(k32u major, k32u minor, k32u release, k32u build)
Creates a version value from its constituent parts.
kVersion::kVersion_Major
k8u kVersion_Major(kVersion version)
Returns the major part of a version number.
k64f
Represents a 64-bit floating-point number.
kComparison
Comparison type enumeration.
kRect32s::x
k32s x
X-coordinate of the origin.
Definition: kApiDef.h:806
kRotatedRect32f::xc
k32f xc
X-coordinate of the rectangle center.
Definition: kApiDef.h:874
kBool
Represents a boolean value.
kRect16s::x
k16s x
X-coordinate of the origin.
Definition: kApiDef.h:792
kRect32f::height
k32f height
Height of the rectangle.
Definition: kApiDef.h:823
kPoint3d64f
3D point structure with 64-bit floating-point fields.
Definition: kApiDef.h:767
kPoint3d32f::y
k32f y
Y-coordinate value.
Definition: kApiDef.h:757