1. Introduction

2. Fundamentals

2.1. Environment

The Mesh Loader library and the Mesh Loader library specification requires and assumes the following properties of the build and runtime environment:

  • The environment must have runtime support for 8, 16, 32 and 64-bit signed and unsigned twos-complement integers
    • When building from source, most c11 implementations cover this requirement.
    • When building from source, all c2x implementations cover this requirement.
  • The environment must have runtime support for 32 and 64-bit float point types.
    • When building from source, all c11 implementations cover this requirement.
    • These are used in the implementation using their standard types.
  • The environment must have runtime support for the std-atomic library.
    • When building from source, all c11 implementations cover this requirement.

Headers provided by the API:

  • For standard API calls, use include/meshLoader/meshLoader.
  • For only standard API types, use include/meshLoader/publicTypes. These are included in include/meshLoader
  • For custom job interfaces, use include/meshLoader/customJob.
  • For utility functions, use include/meshLoader/utility.

Header usage example: 

#include <meshLoader/meshLoader>

2.2. Execution Model

This section outlines the execution model of the Mesh Loader library.

The library uses a number of threads to load a number of mesh objects or other data in the background of the running application. The data loaded is ordered, processed and stored in Job objects. These jobs are processed by Worker objects, each worker running on an individual processor execution thread.

Jobs are processed in a piece-meal manner, each Worker acquiring a Job from a library Instance and processing a part of the loading, releasing it afterwards back to the instance. This ensures resource-safe, efficient start, pause, resume and stop capabilities.

Jobs are also processed via priority, and by type. Furthermore, the API can be expanded with user-defined Custom Job functions, that can be executed by the API from the Worker threads.

2.3. Object Model

The instance, jobs and meshes are represented by Mesh Loader objects. At the API level, they are referred as handles.

Objects created from other objects are referred to as Child objects. The other used object is referred to as a Parent object Child objects must be used only with their Parent objects, and not with other Parent objects.

2.4. Object Lifetime

Objects are created or allocated by MeshLoader_create* or by MeshLoader_allocate* commands, respectively. Once created, it is generally considered to be immutable, though the contents of certain object types are free to change. Objects are destroyed or freed by MeshLoader_destroy* or by MeshLoader_free* commands, respectively.

It is an application's responsibility to track the lifetime of MeshLoader objects, and not to destroy them while they are still in use.

The ownership of application-owned memory is immediately acquired by any Mesh Loader command it is passed into. Ownership of such memory must be released back to the application at the end of the duration of the command, so that the application can alter or free this memory as soon as all the commands that acquired it have returned.

While any Jobs are in the pending state, the following objects must not be destroyed

  • MeshLoader_Job

While any Jobs are in the pending state, the following objects should not be destroyed

  • MeshLoader_Instance

2.5. Application Binary Interface

Shared library implementations must use the default Application Binary Interface (ABI) of the standard C compiler for the platform, or provide customized API headers that cause application code to use the implementation's non-default ABI.

Command Syntax and Duration

The Specification describes Mesh Loader commands and functions using C11 syntax. Language bindings may allow for stricter parameter passing, or object-oriented interfaces.

The following base types are used / are given aliases to be used by the implementation

For 8, 16, 32 and 64-bit signed and unsigned integer types, the following type definitions are used 

typedef unsigned char                   MeshLoader_uint8;
typedef unsigned short int              MeshLoader_uint16;
typedef unsigned int                    MeshLoader_uint32;
typedef unsigned long long int          MeshLoader_uint64;

typedef signed char                     MeshLoader_sint8;
typedef signed short int                MeshLoader_sint16;
typedef signed int                      MeshLoader_sint32;
typedef signed long long int            MeshLoader_sint64;

For 32 and 64-bit floating point types, the standard C types are used 

float
double

For the boolean type, the following are defined. 

typedef MeshLoader_uint8                MeshLoader_bool;
#define MeshLoader_true                 0x01U
#define MeshLoader_false                0x00U
  • MeshLoader_true is a constant representing MeshLoader_bool True value
  • MeshLoader_false is a constant representing MeshLoader_bool False value

For representing sizes and address values, the following type is defined. 

typedef MeshLoader_uint64               MeshLoader_size;

For representing UTF-8 formatted constant strings, the following type is defined. 

typedef char const *                    MeshLoader_StringLiteral;

2.7. Valid Usage

2.7.1. Explicit Valid Usage

Explicit Valid Usage defines a set of conditions which must be met in order to achieve well-defined runtime behavior in an application. These conditions depend only on the Mesh Loader state, and the parameters of objects whose usage is constrained by the condition.

The core layer assumes applications are using the API correctly. Except as documented, the behavior of the core layer to an application using the API incorrectly is undefined, and may include program termination.

Explicit Valid Usage are described in a block labelled "Valid Usage" following each command or structure they apply to.

2.7.2. Implicit Valid Usage

Some valid usage conditions apply to all commands and structures in the API, unless explicitly denoted otherwise for a specific command or structure. These conditions are considered implicit, and are described in a block labelled "Valid Usage (Implicit)" following each command or structure they apply to.

Implicit valid usage conditions:

  • Valid Usage for Object Handles:

    Any input parameter to a command that is an object handle must be a valid object handle, unless otherwise specified. An object handle is valid if:

    • It has been created or allocated by a previous, successful call to the API. Such calls are noted in the Specification.
    • It has not been deleted or freed by a previous call to the API. Such calls are noted in the Specification.
    • Any objects used by that object, either as part of creation or execution, must also be valid.

    The reserved values MeshLoader_invalidHandle, NULL in C or nullptr in C++ can be used in place of handles, when explicitly called out in the Specification. Any command that creates an object successfully must not return these values. It is valid to pass these values to MeshLoader_destroy* or MeshLoader_free* commands, which will ignore these values.

  • Valid Usage for Pointers:

    Any parameter that is a pointer must be a valid pointer only if it explicitly called out by a Valid Usage statement.

    A pointer is "valid" if it points at memory containing values of the number and type(s) expected by the command, and all the fundamental types accessed through the pointer satisfy the alignment requirements of the host processor.

  • Valid Usage for Strings:

    Any parameter that is a pointer to char, or of type MeshLoader_StringLiteral must be a finite sequence of values terminated by a null character, or if explicitly called out in the Specification, can be NULL.

  • Valid Usage for Enumerated Types:

    Any parameter of an enumerated type must be a valid enumerant for that type. An enumerant is valid if:

    • The enumerant is defined as part of the enumerated type.

  • Valid Usage for Flags

    A collection of flags is represented by a bitmask using the type MeshLoader_flags 

    typedef MeshLoader_uint32               MeshLoader_Flags;

    Bitmasks are passed to many commands and structures to compactly represent options, but MeshLoader_Flags is not used directly in the API. Instead, a MeshLoader_*Flags type which is an alias for MeshLoader_Flags, and whose name matches with the corresponding MeshLoader_*FlagBits that are valid for that type, is used.

    Any MeshLoader_*Flags member or parameter used in the API as an input must be a valid combination of bit flags. A valid combination is either zero or the bitwise OR of valid bit flags. A bit flag is valid if:

    • The bit flag is defined as part of the MeshLoader_*FlagBits type, where the bits type is obtained by taking the flag type and replacing the trailing Flags with FlagBits. For example, a flag value of type MeshLoader_MeshLoadModeFlags must contain only bit flags defined by MeshLoader_MeshLoadModeFlagBits.

    Only the low-order 31 bits ( bit positions zero through 30 ) are available for use as flag bits.

  • Valid Usage for Structure Types:

    Any parameter that is a structure containing a structureType member must have a value of structureType which is a valid MeshLoader_StructureType value matching the type of the structure.

  • Valid Usage for Structure Pointer Chains:

    Any parameter that is a structure containing a void * pNext member must have a value of pNext that is either NULL, or is a pointer to a valid extending structure, containing structureType and pNext, in this order, as the first two members, aligned at 8 bytes.

    Each type of extended structure must not appear more than once in a pNext chain, including any aliases. This general rule may be explicitly overridden for specific structures.

    Any component of the implementation must skip over, without processing any extending structure in the chain that are not defined by the core interface component.

    As a convenience to implementations and layers needing to iterate through a structure pointer chain, the API provides two base structure. These structures allow for some type safety, and can be used by the API functions that operate on generic inputs and outputs:

    • The MeshLoader_BaseInStructure is defined as: 

      typedef struct MeshLoader_BaseInStructure {
    MeshLoader_StructureType                    structureType;
    struct MeshLoader_BaseInStructure   const * pNext;
} MeshLoader_BaseInStructure;
      • structureType is the structure type of the structure being iterated through.
      • pNext is NULL or a pointer to the next structure in the structure chain.

      The MeshLoader_BaseInStructure can be used to facilitate iterating through a read-only structure pointer chain.

    • The MeshLoader_BaseOutStructure is defined as: 

      typedef struct MeshLoader_BaseOutStructure {
    MeshLoader_StructureType                    structureType;
    struct MeshLoader_BaseOutStructure        * pNext;
} MeshLoader_BaseOutStructure;
      • structureType is the structure type of the structure being iterated through.
      • pNext is NULL or a pointer to the next structure in the structure chain.

      The MeshLoader_BaseOutStructure can be used to facilitate iterating through structure pointer chain that returns data back to the application.

  • Valid Usage for Nested Structures:

    The above conditions apply recursively to members of structures provided as input to a command, either as a direct argument to the command, or themselves a member of another structure.

    Specifics on valid usage of each command are covered in their individual sections.

2.8. MeshLoader_Result Return Codes

While the core Mesh Loader API is not designed to capture incorrect usage, some circumstances still require return codes. Commands return their status via return codes that are one in two categories:

  • Successful completion codes are returned when a command needs to communicate success or status information. All successful completion codes are non-negative values.
  • Run time error codes are returned when a command needs to communicate a failure that could only be detected at runtime. All runtime error codes are negative values.

All return codes in the Mesh Loader library are reported via MeshLoader_Result return values. The possible codes are: 

typedef enum {
    MeshLoader_Result_Success                       = 0,
    MeshLoader_Result_NotReady                      = 1,
    MeshLoader_Result_TooSmall                      = 2,
    MeshLoader_Result_JobNotStarted                 = 3,
    MeshLoader_Result_ErrorUnknown                  = -1,
    MeshLoader_Result_IllegalArgument               = -2,
    MeshLoader_Result_TooManyObjects                = -3,
    MeshLoader_Result_OutOfMemory                   = -4,
    MeshLoader_Result_MutexError                    = -5,
    MeshLoader_Result_PriorityQueueEmpty            = -6,
    MeshLoader_Result_PriorityQueueFull             = -7,
    MeshLoader_Result_ResourceNotFound              = -8,
    MeshLoader_Result_JobExecutionFailed            = -9,
} MeshLoader_Result;

Success Codes

  • MeshLoader_Result_Success - Command successfully completed.
  • MeshLoader_Result_NotReady - An operation has not been yet completed.
  • MeshLoader_Result_TooSmall - A return array was too small for the result.
  • MeshLoader_Result_JobNotStarted - A job that should be in Running or Higher state is only in Ready state.

Error Codes

  • MeshLoader_Result_ErrorUnknown - An unknown error has occurred; either the application has provided invalid input, or an implementation failure has occurred.
  • MeshLoader_Result_IllegalArgument - An argument passed to an API call violates the Valid Usage (Implicit) section of the respective call. This code must not be returned by a release variant library.
  • MeshLoader_Result_TooManyObjects - Too many objects of the type have already been created.
  • MeshLoader_Result_OutOfMemory - A memory allocation has failed. This must only be returned if no attempt to allocate the memory was made to accommodate the new allocation.
  • MeshLoader_Result_MutexError - The implementation failed to acquire exclusive access to a resource. This must not be returned by a release variant library.
  • MeshLoader_Result_PriorityQueueEmpty - The implementation failed to remove an element from an implementation Priority Queue. This must not be returned by a release variant library.
  • MeshLoader_Result_PriorityQueueFull - The implementation failed to add an element to an implementation Priority Queue. This must not be returned by a release variant library.
  • MeshLoader_Result_ResourceNotFound - A given resource could not be located by the implementation. This can be applied extensively, such as when an invalid path is given. This must not be returned by a release variant library.
  • MeshLoader_Result_JobExecutionFailed - A job failed during runtime execution, and was detected at this function call.

2.9. Structure Types

Each value corresponds to a particular structure with a structureType member with a matching name. As a general rule, the name of each MeshLoader_StructureType value is obtained by taking the name of the structure, and adding _StructureType between the MeshLoader and _StructureName. An example would be for the structure MeshLoader_JobsStartInfo, whose associated MeshLoader_StructureType enumerant is MeshLoader_StructureType_JobsStartInfo. The structureType must equal the enumerant's value when passed to the API.

Structure types supported are described by the following: 

typedef enum {
    MeshLoader_StructureType_Unknown                = 0x00000000U,

    MeshLoader_StructureType_AllocationCallbacks    = 0x00000001U,

    MeshLoader_StructureType_InstanceCreateInfo     = 0x00000002U,

    MeshLoader_StructureType_JobsCreateInfo         = 0x00000003U,
    MeshLoader_StructureType_JobsStartInfo          = 0x00000004U,
    MeshLoader_StructureType_JobsPauseInfo          = 0x00000005U,
    MeshLoader_StructureType_JobsResumeInfo         = 0x00000006U,
    MeshLoader_StructureType_JobsStopInfo           = 0x00000007U,
    MeshLoader_StructureType_JobsTerminateInfo      = 0x00000008U,
    MeshLoader_StructureType_JobsQueryInfo          = 0x00000009U,

    MeshLoader_StructureType_CreateJobInfo          = 0x00000010U,
    MeshLoader_StructureType_QueryJobInfo           = 0x0000000AU,

    MeshLoader_StructureType_AllocationNotification = 0x0000000CU,

    MeshLoader_StructureType_JobData                = 0x00001000U,
    MeshLoader_StructureType_CustomJobInfo          = 0x00001001U,

    MeshLoader_StructureType_MeshData               = 0x0000000BU,
} MeshLoader_StructureType;

3. Instances

In order to use the library, an instance has to be created. There is no global state for the library. All objects are created from instances.

Instances are represented by MeshLoader_Instance handles: 

MESH_LOADER_DEFINE_HANDLE ( MeshLoader_Instance )

3.1. Instance Creation

To create an instance object, call: 

MeshLoader_Result MeshLoader_createInstance (
    MeshLoader_InstanceCreateInfo   const * pCreateInfo,
    MeshLoader_AllocationCallbacks  const * pAllocationCallbacks,
    MeshLoader_Instance                   * pInstance
);

Valid Usage (Implicit)

  • MLUID-MeshLoader_createInstance-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid MeshLoader_InstanceCreateInfo structure
  • MLUID-MeshLoader_createInstance-pAllocationCallbacks-parameter
    If pAllocationCallbacks is not NULL, pAllocationCallbacks must be a valid pointer to a valid MeshLoader_AllocationCallbacks structure
  • MLUID-MeshLoader_createInstance-pInstance-parameter
    pInstance must be a valid pointer to a MeshLoader_Instance handle

Return Codes

Success
  • MeshLoader_Result_Success
Failure
  • MeshLoader_Result_OutOfMemory
  • MeshLoader_Result_MutexError

The MeshLoader_InstanceCreateInfo structure is defined as: 

typedef struct {
    MeshLoader_StructureType            structureType;
    void                        const * pNext;
    MeshLoader_InstanceCreateFlags      flags;
    MeshLoader_uint32                   maxWorkerThreadCount;
} MeshLoader_InstanceCreateInfo;
  • structureType is the type of the structure.
  • pNext is NULL or a pointer to a structure extending this structure.
  • flags is reserved for future use.
  • maxWorkerThreadCount is the maximum number of threads the Instance is allowed to use for Worker Thread objects. If value is 0, the instance will use 1/4 of the maximum processor capable concurrent threads ( logical core count )

Valid Usage (Implicit)

  • MLUID-MeshLoader_InstanceCreateInfo-structureType
    structureType must be MeshLoader_StructureType_InstanceCreateInfo
  • MLUID-MeshLoader_InstanceCreateInfo-pNext
    pNext must be NULL
  • MLUID-MeshLoader_InstanceCreateInfo-flags-parameter
    flags must be 0

The MeshLoader_InstanceCreateFlags type is reserved for future use. 

typedef MeshLoader_Flags                MeshLoader_InstanceCreateFlags;

3.2. Instance Destruction

To destroy an instance, call: 

void MeshLoader_destroyInstance (
    MeshLoader_Instance                     instance,
    MeshLoader_AllocationCallbacks  const * pAllocationCallbacks
);
  • instance is the handle of the instance to destroy
  • pAllocationCallbacks controls memory allocation as described in the Memory Allocation chapter.

Valid Usage

  • MLUID-MeshLoader_destroyInstance-instance-00001
    All child objects created using instance must have been destroyed prior to this call.
  • MLUID-MeshLoader_destroyInstance-instance-00002
    If MeshLoader_AllocationCallbacks were provided when instance was created, a compatible set of callbacks must be provided as a parameter for this call.
  • MLUID-MeshLoader_destroyInstance-instance-00003
    If no MeshLoader_AllocationCallbacks were provided when instance was created, pAllocationCallbacks must be NULL.

Valid Usage (Implicit)

  • MLUID-MeshLoader_destroyInstance-instance-parameter
    If instance is not NULL, instance must be a valid MeshLoader_Instance handle.
  • MLUID-MeshLoader_destroyInstance-pAllocationCallbacks-parameter
    If pAllocationCallbacks is not NULL, pAllocationCallbacks must be a valid pointer to a valid MeshLoader_AllocationCallbacks structure.

4. Jobs

A Job is a description of the task that has to be computed in the background by the library in order to load a single object. Once created, it has to be started, and the result can be observed or fully acquired from it. The job type determines the task that the Worker Thread will execute in order to load the requested file.

The job types can be expanded by creating User Defined Jobs.

Jobs are created using an instance, and are Child objects to the used Instance. The application must, as a result, destroy all jobs created from an instance before destroying an instance.

Jobs are represented by MeshLoader_Job handles: 

MESH_LOADER_DEFINE_HANDLE ( MeshLoader_Job )

4.1. Job Lifetime & Execution

Since a lot of objects have to be loaded, jobs should be created, started and queried in large batches. Since they operate on a priority basis, there is some control over the order in which jobs will be handled and be finished.

The following states are defined for a job:

  • Ready - the job is created and awaiting launch.
  • Running - the job is being treated by a Worker or is waiting for a Worker to handle it.
  • Paused - the job is not being treated by any Worker and will not be picked up by one until it is resumed to Running.
  • Stopped - the job is not being treated by any Worker and cannot be picked up anymore until it is restarted, or is destroyed.
  • Terminated - the job is not being treated by any Worker and should not be restarted.
  • Finished - the job has is finished, and its results can be observed or acquired. It can be restarted afterwards.
  • FinishedError - the job has encountered an error, and must be cleared of its error state before being restarted, or just destroyed.

The possible job states are defined by the MeshLoader_JobState enumeration.

The following actions are defined for interacting with a job from the API:

  • Start - used for starting job objects execution.
  • Pause - used to pause job objects execution.
  • Resume - used to resume job objects execution.
  • Stop - used to stop job objects execution in a safe manner.
  • Terminate - used to terminate job objects execution immediately.
  • Get Error - used to acquire the error that caused a job object's execution to halt.

The possible job actions are defined by the interfaces found in Job Execution Commands section.

State Transition Table:

Action/State Ready Running Paused Stopped Terminated Finished Finished Error
Start Running Running undefined Running undefined Running undefined
Pause undefined Paused Paused Stopped undefined Finished undefined
Resume Ready Running Running Stopped undefined Finished undefined
Stop Ready Stopped Stopped Stopped undefined Finished undefined
Terminate Terminated Terminated Terminated Terminated undefined Terminated Terminated
Get Error Ready Running Paused Stopped undefined Finished Ready

  • An undefined state transition entry in the table represents an incompatible Action/State transition. Triggering the defined action (row header) for a job while it's state is the defined state (column header) results in undefined behaviour.

    An example would be triggering Pause on a job that is Ready is undefined behaviour, since the job has not even been started, and the implementation does not specify any behaviour for this transition. The job this action is triggered on could remain in the Ready state, or transition to the Paused state.

  • The Terminated state must not have any actions triggered upon it, and must only be destroyed.

4.2. Job Creation

To create a number of Job objects, call: 

MeshLoader_Result MeshLoader_createJobs (
    MeshLoader_Instance                     instance,
    MeshLoader_JobsCreateInfo       const * pCreateInfo,
    MeshLoader_AllocationCallbacks  const * pAllocationCallbacks
);

Valid Usage (Implicit)

  • MLUID-MeshLoader_createJobs-instance-parameter
    instance must be a valid MeshLoader_Instance handle.
  • MLUID-MeshLoader_createJobs-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid MeshLoader_JobsCreateInfo structure.
  • MLUID-MeshLoader_createJobs-pAllocationCallbacks-parameter
    If pAllocationCallbacks is not NULL, pAllocationCallbacks must be a valid pointer to a valid MeshLoader_AllocationCallbacks structure.

Return Codes

Success
  • MeshLoader_Result_Success
Failure
  • MeshLoader_Result_OutOfMemory
  • MeshLoader_Result_MutexError

The MeshLoader_JobsCreateInfo structure is defined as: 

typedef struct {
    MeshLoader_StructureType            structureType;
    void                        const * pNext;
    MeshLoader_JobsCreateFlags          flags;
    MeshLoader_uint32                   jobCount;
    MeshLoader_Job                    * pJobs;
    MeshLoader_CreateJobInfo    const * pCreateJobInfos;
} MeshLoader_JobsCreateInfo;
  • structureType is the type of the structure.
  • pNext is NULL or a pointer to a structure extending this structure.
  • flags is a bitmask of MeshLoader_JobsCreateFlagBits indicating the behaviour of the batch create command.
  • jobCount is the unsigned integer count of the jobs to be created by this command.
  • pJobs is a pointer to an array of MeshLoader_Job, and is the memory area where the command's output will be saved, if successful.
  • pCreateJobInfos is a pointer to an array of MeshLoader_CreateJobInfo structures describing the intended behaviour of each of the jobs to be created

Valid Usage (Implicit)

  • MLUID-MeshLoader_JobsCreateInfo-structureType
    structureType must be MeshLoader_StructureType_JobsCreateInfo.
  • MLUID-MeshLoader_JobsCreateInfo-pNext
    pNext must be NULL.
  • MLUID-MeshLoader_JobsCreateInfo-flags-parameter
    flags must be a valid combination of MeshLoader_JobsCreateFlagBits values.
  • MLUID-MeshLoader_JobsCreateInfo-jobCount-parameter
    jobCount must be greater than 0.
  • MLUID-MeshLoader_JobsCreateInfo-pJobs-parameter
    pJobs must be a valid pointer to an array of jobCount valid MeshLoader_Job handles.
  • MLUID-MeshLoader_JobsCreateInfo-pCreateJobInfos-parameter
    pCreateJobInfos must be a valid pointer to an array of valid jobCount MeshLoader_CreateJobInfo structures.

Bits that can be set in MeshLoader_JobsCreateInfo::flags, specifying creation usage of the Jobs, are: 

typedef enum {
    MeshLoader_JobsCreateFlag_ContinueIfError       = 0x00000001U,
} MeshLoader_JobsCreateFlagBits;
  • MeshLoader_JobsCreateFlag_ContinueIfError specifies that, if a job creation fails, the other jobs will proceed to be created, and the subsequent failed creations will result in a NULL handle stored for the respective jobs inside the MeshLoader_JobsCreateInfo::pJobs array.

The bitmask type used in MeshLoader_JobsCreateInfo::flags is defined as follows: 

typedef MeshLoader_Flags                MeshLoader_JobsCreateFlags;

The MeshLoader_CreateJobInfo is defined as: 

typedef struct {
    MeshLoader_StructureType            structureType;
    void                        const * pNext;
    MeshLoader_JobType                  jobType;
    MeshLoader_MeshLoadModeFlags        loadMode;
    MeshLoader_StringLiteral            inputPath;
    float                               priority;
} MeshLoader_CreateJobInfo;
  • structureType is the type of the structure.
  • pNext is NULL or a pointer to a structure extending this structure.
  • jobType is an enumerant value defined by MeshLoader_JobType, specifying the job's type and file format.
  • loadMode is a bitmask of MeshLoader_MeshLoadModeFlags indicating the load mode and operations to be done in the Job Execution.
  • inputPath is a pointer to a null-terminated UTF-8 MeshLoader_StringLiteral which contains the path, relative to the application or absolute, of the file that is used as input data for the job.
  • priority is a float value specifying the priority of the Job, ranging from 0.0f (lowest) to 1.0f (highest).

Valid Usage

  • MLUID-MeshLoader_CreateJobInfo-pNext-00004
    If the pNext chain includes a MeshLoader_CustomJobInfo structure, then jobType must be MeshLoader_JobType_Custom.
  • MLUID-MeshLoader_CreateJobInfo-jobType-00005
    If jobType is MeshLoader_JobType_Custom, the pNext pNext structure chain must include a a MeshLoader_CustomJobInfo structure.

Valid Usage (Implicit)

  • MLUID-MeshLoader_CreateJobInfo-structureType
    structureType must be MeshLoader_StructureType_CreateJobInfo.
  • MLUID-MeshLoader_CreateJobInfo-pNext
    Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of MeshLoader_CustomJobInfo.
  • MLUID-MeshLoader_CreateJobInfo-jobType-parameter
    jobType must be a valid enumerant defined by MeshLoader_JobType
  • MLUID-MeshLoader_CreateJobInfo-loadMode-parameter
    loadMode must be a valid combination of MeshLoader_MeshLoadModeFlagBits values.
  • MLUID-MeshLoader_CreateJobInfo-inputPath-parameter
    inputPath must be a valid pointer to a null-terminated UTF-8 string.
  • MLUID-MeshLoader_CreateJobInfo-priority-parameter
    priority must be greater than or equal to 0.0f and less than or equal to 1.0f.

Values that can be used to specify a Job's type are defined by MeshLoader_JobType: 

typedef enum {
    MeshLoader_JobType_Obj                          = 0x00000000U,
    MeshLoader_JobType_Custom                       = 0x00001000U,
} MeshLoader_JobType;
  • MeshLoader_JobType_Obj describes a job that requires loading a Wavefront .obj file, and that will use the included library loader task.
  • MeshLoader_JobType_Custom describes a job whose behaviour is user-defined by the implementing application. A job described by this type must have its behaviour specified. See more in User Defined Jobs

The specific data that a job is expected to load and contain at finish can be mentioned using the bits described by MeshLoader_MeshLoadModeFlagBits: 

typedef enum {
    MeshLoader_MeshLoadModeFlag_LoadFaces           = 0x00000001U,
    MeshLoader_MeshLoadModeFlag_LoadIndices         = 0x00000002U,
} MeshLoader_MeshLoadModeFlagBits;
  • MeshLoader_MeshLoadModeFlag_LoadFaces specifies that the job must include valid mesh face data.
  • MeshLoader_MeshLoadModeFlag_LoadIndices specifies that the job must include valid mesh indices data.

The bitmask type used for specifying the load formats is defined as follows: 

typedef MeshLoader_Flags                MeshLoader_MeshLoadModeFlags;

The specified load mode behavior will have a direct effect on what functions can be used to load mesh data, once the job is finished loading. More info can be found at Reading Mesh Data.

4.3. Job Execution Commands

To start a batch of jobs, call: 

MeshLoader_Result MeshLoader_startJobs (
        MeshLoader_Instance                     instance,
        MeshLoader_JobsStartInfo        const * pStartInfo
);

Valid Usage

  • MLUID-MeshLoader_startJobs-jobStates-00006
    All job handles contained in the array given through the pJobs pointer in the structure at pStartInfo must be in a state that is compatible with the start operation, as defined by the State Transition Table.
  • MLUID-MeshLoader_startJobs-pAllocationCallbacks-00007
    If pAllocationCallbacks in the structure at pStartInfo is not NULL, the elements contained within the given MeshLoader_AllocationCallbacks must remain available after call using this structure is complete, until the Jobs started by the call have destroyed.

Valid Usage (Implicit)

  • MLUID-MeshLoader_startJobs-instance-parameter
    instance must be a valid MeshLoader_Instance handle.
  • MLUID-MeshLoader_startJobs-pCreateInfo-parameter
    pStartInfo must be a valid pointer to a valid MeshLoader_JobsStartInfo structure.

Return Codes

Success
  • MeshLoader_Result_Success
Failure
  • MeshLoader_Result_OutOfMemory
  • MeshLoader_Result_MutexError

The MeshLoader_JobsStartInfo structure is defined as follows: 

typedef struct {
    MeshLoader_StructureType                structureType;
    void                            const * pNext;
    MeshLoader_JobsStartFlags               flags;
    MeshLoader_uint32                       jobCount;
    MeshLoader_Job                  const * pJobs;
    MeshLoader_AllocationCallbacks  const * pAllocationCallbacks;
} MeshLoader_JobsStartInfo;
  • structureType is the type of the structure.
  • pNext is NULL or a pointer to a structure extending this structure.
  • flags is reserved for future use.
  • jobCount is an unsigned integer specifying the number of Jobs that are to be started.
  • pJobs is a pointer to an array of valid MeshLoader_Job handles, previously created with MeshLoader_createJobs. The jobs associated to the given handles are to be started.
  • pAllocationCallbacks is a pointer to a MeshLoader_AllocationCallbacks structure. This controls the memory allocation handled by the Worker Threads when processing this job, as described in the Memory Allocation chapter.

Valid Usage (Implicit)

  • MLUID-MeshLoader_JobsStartInfo-structureType
    structureType must be MeshLoader_StructureType_JobsStartInfo.
  • MLUID-MeshLoader_JobsStartInfo-pNext
    pNext must be NULL.
  • MLUID-MeshLoader_JobsStartInfo-flags-parameter
    flags must be 0.
  • MLUID-MeshLoader_JobsStartInfo-jobCount-parameter
    jobCount must be greater than 0.
  • MLUID-MeshLoader_JobsStartInfo-pJobs-parameter
    pJobs must be a valid pointer to an array of jobCount valid MeshLoader_Job handles.
  • MLUID-MeshLoader_JobsStartInfo-pAllocationCallbacks-parameter
    If pAllocationCallbacks is not NULL, pAllocationCallbacks must be a valid pointer to a valid MeshLoader_AllocationCallbacks structure.

To pause a job, call: To be added

To resume a job, call: To be added

To stop a job, call: To be added

To terminate a job, call: To be added

To get the error of a job, call: To be added

4.4. Querying Job Status

To query the status of a batch of jobs, call: 

MeshLoader_Result MeshLoader_queryJobs (
    MeshLoader_Instance                     instance,
    MeshLoader_JobsQueryInfo              * pQueryInfo
);

Valid Usage

Valid Usage (Implicit)

  • MLUID-MeshLoader_startJobs-instance-parameter
    instance must be a valid MeshLoader_Instance handle.
  • MLUID-MeshLoader_startJobs-pCreateInfo-parameter
    pQueryInfo must be a valid pointer to a valid MeshLoader_JobsQueryInfo structure.

Return Codes

Success
  • MeshLoader_Result_Success

The MeshLoader_JobsQueryInfo structure is defined as follows: 

typedef struct {
    MeshLoader_StructureType            structureType;
    void                              * pNext;
    MeshLoader_JobsQueryFlags           flags;
    MeshLoader_uint32                   jobCount;
    MeshLoader_QueryJobInfo           * pQueryJobInfos;
} MeshLoader_JobsQueryInfo;
  • structureType is the type of the structure.
  • pNext is NULL or a pointer to a structure extending this structure.
  • flags is reserved for future use.
  • jobCount is an unsigned integer specifying the number of Jobs that are to be started.
  • pQueryJobInfos is a pointer to an array of MeshLoader_QueryJobInfo structures, where the query result will be saved.

Valid Usage (Implicit)

  • MLUID-MeshLoader_JobsQueryInfo-structureType
    structureType must be MeshLoader_StructureType_JobsQueryInfo.
  • MLUID-MeshLoader_JobsQueryInfo-pNext
    pNext must be NULL.
  • MLUID-MeshLoader_JobsQueryInfo-flags-parameter
    flags must be 0.
  • MLUID-MeshLoader_JobsQueryInfo-jobCount-parameter
    jobCount must be greater than 0.
  • MLUID-MeshLoader_JobsQueryInfo-pQueryJobInfos-parameter
    pQueryJobInfos must be a valid pointer to an array of jobCount valid MeshLoader_QueryJobInfo structures.

The MeshLoader_QueryJobInfo structure is defined as follows: 

typedef struct {
    MeshLoader_StructureType            structureType;
    void                              * pNext;
    MeshLoader_Job                      job;
    MeshLoader_JobState                 state;
    float                               progress;
} MeshLoader_QueryJobInfo;
  • structureType is the type of the structure.
  • pNext is NULL or a pointer to a structure extending this structure.
  • job is a MeshLoader_Job handle, representing the queried job.
  • state will contain a value defined by MeshLoader_JobState that represents the state of the job, also described in Job Lifetime & Execution section.
  • progress will contain a floating point value between 0.0f and 1.0f, representing the job progress the defined range, 0.0f representing a job that is not started, and 1.0f representing a job that has finished. Another example, a job that is 25% done would have the progress value 0.25f.

Valid Usage (Implicit)

  • MLUID-MeshLoader_QueryJobInfo-structureType
    structureType must be MeshLoader_StructureType_QueryJobInfo.
  • MLUID-MeshLoader_QueryJobInfo-pNext
    pNext must be NULL.
  • MLUID-MeshLoader_QueryJobInfo-job-parameter
    job must contain a valid MeshLoader_Job handle, created in a previous MeshLoader_createJobs call.

The states of a job, as described also in the Job Lifetime and Execution section, are defined by MeshLoader_JobState enumeration, defined as follows: 

typedef enum {
    MeshLoader_JobState_Ready                      = 0x00000001U,
    MeshLoader_JobState_Running                    = 0x00000002U,
    MeshLoader_JobState_Paused                     = 0x00000003U,
    MeshLoader_JobState_Stopped                    = 0x00000004U,
    MeshLoader_JobState_Terminated                 = 0x00000005U,
    MeshLoader_JobState_Finished                   = 0x00000010U,
    MeshLoader_JobState_FinishedError              = 0x00000020U,
} MeshLoader_JobState;
  • MeshLoader_JobState_Ready represents the Ready state of a Job.
  • MeshLoader_JobState_Running represents the Running state of a Job.
  • MeshLoader_JobState_Paused represents the Paused state of a Job.
  • MeshLoader_JobState_Stopped represents the Stopped state of a Job.
  • MeshLoader_JobState_Terminated represents the Terminated state of a Job.
  • MeshLoader_JobState_Finished represents the Finished state of a Job.
  • MeshLoader_JobState_FinishedError represents the Finished Error state of a Job.

To query whether any jobs are running, call: 

MeshLoader_Result MeshLoader_anyJobsRunning (
    MeshLoader_Instance                     instance,
    MeshLoader_bool                       * pAnyRunning
);
  • instance is a handle of a valid MeshLoader_Instance handle previously created with MeshLoader_createInstance.
  • pAnyRunning is a pointer to a MeshLoader_bool value to store the operation result in. If any jobs are running, pAnyRunning will contain MeshLoader_true after the call, MeshLoader_false otherwise.

Valid Usage (Implicit)

  • MLUID-MeshLoader_anyJobsRunning-instance-parameter
    instance must be a valid MeshLoader_Instance handle.
  • MLUID-MeshLoader_anyJobsRunning-pAnyRunning-parameter
    pAnyRunning must be a valid pointer to a MeshLoader_bool value.

Return Codes

Success
  • MeshLoader_Result_Success
Failure
  • MeshLoader_Result_MutexError

4.5. Job Destruction

To destroy a batch of jobs, call: 

void MeshLoader_destroyJobs (
    MeshLoader_Instance                     instance,
    MeshLoader_uint32                       jobCount,
    MeshLoader_Job                  const * pJobs,
    MeshLoader_AllocationCallbacks  const * pAllocationCallbacks
);

Valid Usage

  • MLUID-MeshLoader_destroyJobs-pJobs-00009
    All job objects in the array passed through pJobs must be in a Stopped, Finished, Finished Error or Terminated state.
  • MLUID-MeshLoader_destroyInstance-pJobs-00010
    If MeshLoader_AllocationCallbacks were provided when the jobs contained in the pJobs array of MeshLoader_Job handles were created, a compatible set of callbacks must be provided as a parameter for this call.
  • MLUID-MeshLoader_destroyInstance-pJobs-00011
    If no MeshLoader_AllocationCallbacks were provided when the jobs contained in the pJobs array of MeshLoader_Job handles were created, pAllocationCallbacks must be NULL.

Valid Usage (Implicit)

  • MLUID-MeshLoader_destroyJobs-instance-parameter
    instance must be a valid MeshLoader_Instance handle.
  • MLUID-MeshLoader_destroyJobs-jobCount-parameter
    jobCount must be greater than 0.
  • MLUID-MeshLoader_destroyJobs-pJobs-parameter
    jobCount must be a valid pointer to an array of jobCount valid MeshLoader_Job handles.
  • MLUID-MeshLoader_createJobs-pAllocationCallbacks-parameter
    If pAllocationCallbacks is not NULL, pAllocationCallbacks must be a valid pointer to a valid MeshLoader_AllocationCallbacks structure.

5. Meshes

The end purpose of the Job Objects described in the previous chapter, and consequently, this library, is to load mesh objects. These are representations of 3D models, and come in several formats. These usually describe and object using vertices and faces. While this is the minimum required data for a model representation, some formats include additional specialized data, such as normal vectors, texture data or bump maps.

Any data format or specialized data structure that is not available in the implementation can be defined through User Defined Jobs and the interfaces provided for them.

A MeshLoader_Job object will create and populate a Mesh object during its lifetime, and will make it readable or release it to the main process after it has finished processing. It is up to the application whether the Mesh object is only read from the job or taken from it.

A Mesh Object is represented by MeshLoader_Mesh handles: 

MESH_LOADER_DEFINE_HANDLE ( MeshLoader_Mesh )

5.1. Mesh Ownership

Mesh Objects that are only read from Jobs must not be destroyed by the application. These will be freed upon the job's destruction or upon its restart. These are referred to as job-owned.

Mesh Objects that are taken from Jobs must be destroyed. After a Mesh Object is taken from a job successfully, subsequent attempts to read/take a Mesh Object from that Job will not yield another object, unless the job goes through another load-cycle (restart->finish). These are referred to as application-owned.

5.2. Mesh Acquisition

To acquire a mesh and without releasing it from the job, leaving the implementation to destroy it, call: 

MeshLoader_Result MeshLoader_getMesh (
        MeshLoader_Job                          job,
        MeshLoader_Mesh                       * pMesh
);

Valid Usage

  • MLUID-MeshLoader_getMesh-job-00016
    job should represent a Job Object whose state is Finished, as described in the Job Lifetime and Execution section.
  • MLUID-MeshLoader_getMesh-job-00017
    job must not have been given to a MeshLoader_takeMesh call as the job parameter before this call without having gone through another load-cycle(start->finish).
  • MLUID-MeshLoader_getMesh-pMesh-00023
    The MeshLoader_Mesh handle located at pMesh must not be a valid, application-owned handle.

Valid Usage (Implicit)

  • MLUID-MeshLoader_getMesh-job-parameter
    job must be a valid MeshLoader_Job handle.
  • MLUID-MeshLoader_getMesh-pMesh-parameter
    pMesh must be a valid pointer to a MeshLoader_Mesh handle.

Return Codes

Success
  • MeshLoader_Result_Success
  • MeshLoader_Result_JobNotStarted
  • MeshLoader_Result_NotReady
Failure
  • MeshLoader_Result_JobExecutionFailed

The mesh obtained in pMesh from a successful call will be a job-owned mesh.

To take a mesh by releasing it from the job, requiring the acquired mesh to be destroyed by the application, call: 

MeshLoader_Result MeshLoader_takeMesh (
        MeshLoader_Job                          job,
        MeshLoader_AllocationCallbacks  const * pAllocationCallbacks,
        MeshLoader_Mesh                       * pMesh
);

Valid Usage

  • MLUID-MeshLoader_takeMesh-job-00018
    job should represent a Job Object whose state is Finished, as described in the Job Lifetime and Execution section.
  • MLUID-MeshLoader_takeMesh-job-00019
    job must not have been given to a MeshLoader_takeMesh call as the job parameter before this call without having gone through another load-cycle(start->finish).
  • MLUID-MeshLoader_takeMesh-pAllocationCallbacks-00020
    If the MeshLoader_JobsStartInfo passed to the MeshLoader_startJobs call that created the job was given a valid, not NULL MeshLoader_AllocationCallbacks, pAllocationCallbacks given here should point to the same structure. The application does take into account the possibility of another structure being given here, which will re-allocate all mesh data with these callbacks, and free them from the one stored at start.
  • MLUID-MeshLoader_takeMesh-pAllocationCallbacks-00021
    If the MeshLoader_JobsStartInfo passed to the MeshLoader_startJobs call that created the job was NULL, pAllocationCallbacks given here should also be NULL. The application does take into account the possibility of these not being NULL, in which case the library will use internal allocations to free the original mesh data, or reallocate the new mesh data, depending on which of the allocator values was NULL.
  • MLUID-MeshLoader_takeMesh-pMesh-00022
    The MeshLoader_Mesh handle located at pMesh must not be a valid, application-owned handle.

Valid Usage (Implicit)

  • MLUID-MeshLoader_takeMesh-job-parameter
    job must be a valid MeshLoader_Job handle.
  • MLUID-MeshLoader_createJobs-pAllocationCallbacks-parameter
    If pAllocationCallbacks is not NULL, pAllocationCallbacks must be a valid pointer to a valid MeshLoader_AllocationCallbacks structure.
  • MLUID-MeshLoader_takeMesh-pMesh-parameter
    pMesh must be a valid pointer to a MeshLoader_Mesh handle.

Return Codes

Success
  • MeshLoader_Result_Success
  • MeshLoader_Result_JobNotStarted
  • MeshLoader_Result_NotReady
Failure
  • MeshLoader_Result_JobExecutionFailed

The mesh obtained in pMesh from a successful call will be an application-owned mesh.

5.3. Reading Mesh Data

The mesh contained data can be acquired in a read-only format, in a structure, or by enumeration of individual formats, by copy.

The data contained in the mesh depends on the MeshLoader_MeshLoadModeFlags specified to the MeshLoader_CreateJobInfo in the MeshLoader_JobsCreateInfo given to the MeshLoader_createJobs call that created the MeshLoader_Job that loaded the Mesh.

Each flag adds to the behavior, does not block another load behavior unless explicitly specified, and behave as described:

  • If MeshLoader_MeshLoadModeFlag_LoadFaces was used, the Mesh will have face data loaded.
  • If MeshLoader_MeshLoadModeFlag_LoadIndices was used, the Mesh will have face data loaded, formatted as one array of indices.

To read the mesh data in a read-only format, call: 

MeshLoader_Result MeshLoader_getMeshData (
        MeshLoader_Mesh                         mesh,
        MeshLoader_MeshData                   * pMeshData
);

Valid Usage (Implicit)

  • MLUID-MeshLoader_getMeshData-mesh-parameter
    mesh must be a valid MeshLoader_Mesh handle.
  • MLUID-MeshLoader_getMeshData-pMeshData-parameter
    pMeshData must be a valid pointer to a valid MeshLoader_MeshData structure.

Return Codes

Success
  • MeshLoader_Result_Success

The MeshLoader_MeshData structure is defined as follows: 

typedef struct {
    MeshLoader_StructureType        structureType;
    void                          * pNext;
    MeshLoader_uint32               vertexCount;
    MeshLoader_VertexData   const * pVertices;
    MeshLoader_uint32               faceCount;
    MeshLoader_FaceData     const * pFaces;
    MeshLoader_IndexData    const * pIndexData;
} MeshLoader_MeshData;
  • structureType is the type of the structure.
  • pNext is NULL or a pointer to a structure extending this structure.
  • vertexCount is an unsigned integer representing the number of vertices the mesh is composed of.
  • pVertices is a pointer to an array of MeshLoader_VertexData structures, representing the vertices the mesh is composed of.
  • faceCount is an unsigned integer representing the number of faces the mesh is composed of.
  • pFaces is a pointer to an array of MeshLoader_FaceData structures, representing the faces the mesh is composed of.

After a successful call of MeshLoader_getMeshData, the at pMesh will contain the following:

  • vertexCount will be set to the number of vertices the mesh is composed of.
  • pVertices will be a pointer to an array of vertexCount valid MeshLoader_VertexData structures.
  • If MeshLoader_MeshLoadModeFlag_LoadFaces was used, faceCount will be set to the number of faces the mesh is composed of.
  • If MeshLoader_MeshLoadModeFlag_LoadFaces was used, pFaces will be a pointer to an array of faceCount valid MeshLoader_FaceData structures.
  • If MeshLoader_MeshLoadModeFlag_LoadFaces was not used, faceCount will be 0.
  • If MeshLoader_MeshLoadModeFlag_LoadFaces was not used, pFaces will be NULL.
  • If MeshLoader_MeshLoadModeFlag_LoadIndices was used, pIndexData will be a pointer to a valid MeshLoader_IndexData structure.
  • If MeshLoader_MeshLoadModeFlag_LoadIndices was not used, pIndexData will be NULL.

Valid Usage (Implicit)

  • MLUID-MeshLoader_MeshData-structureType
    structureType must be MeshLoader_StructureType_MeshData.
  • MLUID-MeshLoader_MeshData-pNext
    pNext must be NULL.

The MeshLoader_VertexData structure is described as follows: 

typedef struct {
    double x;
    double y;
    double z;
} MeshLoader_VertexData;
  • x represents the first coordinate of the vertex, used to represent it in 3D space.
  • y represents the second coordinate of the vertex, used to represent it in 3D space.
  • z represents the third coordinate of the vertex, used to represent it in 3D space.

The MeshLoader_FaceData structure is described as follows: 

typedef struct {
    MeshLoader_uint32 u;
    MeshLoader_uint32 v;
    MeshLoader_uint32 w;
} MeshLoader_FaceData;
  • u represents the first index of the face, to start drawing from.
  • v represents the second index of the face, to start drawing from.
  • w represents the third index of the face, to start drawing from.

The MeshLoader_IndexData structure is described as follows: 

typedef struct {
    MeshLoader_uint32           indexCount;
    MeshLoader_uint32   const * pIndices;
} MeshLoader_IndexData;
  • indexCount is the number of vertex drawing indices in the mesh.
  • pIndices is a pointer to an array of vertex drawing indices.

After a successful call of MeshLoader_getMeshData with MeshLoader_MeshLoadModeFlag_LoadIndices, the 's pIndexData will contain the following:

  • indexCount will be the number of vertex drawing indices, equivalent to 3 * faceCount.
  • pIndices will be a valid pointer to an array of indexCount indices.

To enumerate the vertices of a mesh, call: 

MeshLoader_Result MeshLoader_enumerateMeshVertices (
        MeshLoader_Mesh                         mesh,
        MeshLoader_uint32                     * pVertexCount,
        MeshLoader_VertexData                 * pVertices
);

If pVertices is NULL, then the number of vertices available is returned in pVertexCount. Otherwise, pVertexCount must point to a variable set by the user to the number of elements in the pVertices array, and on return the variable is overwritten with the number of structures actually written to pVertices. If pVertexCount is less than the number of vertices, at most pVertexCount structures will be written, and MeshLoader_Result_TooSmall will be returned instead of MeshLoader_Result_Success, to indicate that not all the available vertices were returned.

Valid Usage (Implicit)

  • MLUID-MeshLoader_enumerateMeshVertices-mesh-parameter
    mesh must be a valid MeshLoader_Mesh handle.
  • MLUID-MeshLoader_enumerateMeshVertices-mesh-pVertexCount
    pVertexCount must be a valid pointer to a MeshLoader_uint32 value.
  • MLUID-MeshLoader_enumerateMeshVertices-mesh-pVertices
    If the value referenced by pVertexCount is not 0, and pVertices is not NULL, pVertices must be a valid pointer to an array of pVertexCount valid MeshLoader_VertexData structures.

Return Codes

Success
  • MeshLoader_Result_Success
  • MeshLoader_Result_TooSmall
Failure
  • MeshLoader_Result_ResourceNotFound

If loaded with MeshLoader_MeshLoadModeFlag_LoadFaces, the faces of a mesh can be enumerated by calling: 

MeshLoader_Result MeshLoader_enumerateMeshFaces (
        MeshLoader_Mesh                         mesh,
        MeshLoader_uint32                     * pFaceCount,
        MeshLoader_FaceData                   * pFaces
);

If pFaces is NULL, then the number of faces available is returned in pFaceCount. Otherwise, pFaceCount must point to a variable set by the user to the number of elements in the pFaces array, and on return the variable is overwritten with the number of structures actually written to pFaces. If pFaceCount is less than the number of faces, at most pFaceCount structures will be written, and MeshLoader_Result_TooSmall will be returned instead of MeshLoader_Result_Success, to indicate that not all the available faces were returned.

Valid Usage

  • MLUID-MeshLoader_enumerateMeshFaces-loadMode-00027
    mesh must be a MeshLoader_Mesh handle obtained from a job that was created and loaded with MeshLoader_MeshLoadModeFlag_LoadFaces.

Valid Usage (Implicit)

  • MLUID-MeshLoader_enumerateMeshFaces-mesh-parameter
    mesh must be a valid MeshLoader_Mesh handle.
  • MLUID-MeshLoader_enumerateMeshFaces-mesh-pFaceCount
    pFaceCount must be a valid pointer to a MeshLoader_uint32 value.
  • MLUID-MeshLoader_enumerateMeshFaces-mesh-pFaces
    If the value referenced by pFaceCount is not 0, and pFaces is not NULL, pFaces must be a valid pointer to an array of pFaceCount valid MeshLoader_FaceData structures.

Return Codes

Success
  • MeshLoader_Result_Success
  • MeshLoader_Result_TooSmall
Failure
  • MeshLoader_Result_ResourceNotFound

If loaded with MeshLoader_MeshLoadModeFlag_LoadIndices, the faces of a mesh can be enumerated by calling: 

MeshLoader_Result MeshLoader_enumerateIndices (
        MeshLoader_Mesh                         mesh,
        MeshLoader_uint32                     * pIndexCount,
        MeshLoader_uint32                     * pIndices
);

If pIndices is NULL, then the number of indices available is returned in pIndexCount. Otherwise, pIndexCount must point to a variable set by the user to the number of elements in the pIndices array, and on return the variable is overwritten with the number of values actually written to pIndices. If pIndexCount is less than the number of indices, at most pIndices values will be written, and MeshLoader_Result_TooSmall will be returned instead of MeshLoader_Result_Success, to indicate that not all the available indices were returned.

Valid Usage

  • MLUID-MeshLoader_enumerateIndices-loadMode-00028
    mesh must be a MeshLoader_Mesh handle obtained from a job that was created and loaded with MeshLoader_MeshLoadModeFlag_LoadIndices.

Valid Usage (Implicit)

  • MLUID-MeshLoader_enumerateIndices-mesh-parameter
    mesh must be a valid MeshLoader_Mesh handle.
  • MLUID-MeshLoader_enumerateIndices-mesh-pIndexCount
    pIndexCount must be a valid pointer to a MeshLoader_uint32 value.
  • MLUID-MeshLoader_enumerateIndices-mesh-pIndices
    If the value referenced by pIndexCount is not 0, and pIndices is not NULL, pIndices must be a valid pointer to an array of pIndexCount valid MeshLoader_uint32 values.

Return Codes

Success
  • MeshLoader_Result_Success
  • MeshLoader_Result_TooSmall
Failure
  • MeshLoader_Result_ResourceNotFound

5.4. Mesh Destruction

To destroy an application-owned mesh, call: 

void MeshLoader_destroyMesh (
        MeshLoader_Mesh                         mesh,
        MeshLoader_AllocationCallbacks  const * pAllocationCallbacks
);

Valid Usage

  • MLUID-MeshLoader_destroyMesh-mesh-00024
    The mesh handle must be an application-owned handle.
  • MLUID-MeshLoader_destroyMesh-pAllocationCallbacks-00025
    If MeshLoader_AllocationCallbacks were provided when the mesh was acquired using MeshLoader_takeMesh, a compatible set of callbacks must be provided as a parameter for this call.
  • MLUID-MeshLoader_destroyMesh-pAllocationCallbacks-00026
    If no MeshLoader_AllocationCallbacks were provided when the mesh was acquired using MeshLoader_takeMesh, pAllocationCallbacks must be NULL.

Valid Usage (Implicit)

  • MLUID-MeshLoader_destroyMesh-mesh-parameter
    mesh must be a valid MeshLoader_Mesh handle.
  • MLUID-MeshLoader_destroyMesh-pAllocationCallbacks-parameter
    If pAllocationCallbacks is not NULL, pAllocationCallbacks must be a valid pointer to a valid MeshLoader_AllocationCallbacks structure.

6. Memory Allocation

The Mesh Loader Library provides applications the opportunity to perform memory allocations on behalf of the library implementations. If this feature is not used, the implementation will perform its own memory allocations. Since most memory allocations are off the critical path, this is not meant as a performance feature. Rather, this can be useful for certain embedded systems, for systems with existing dedicated allocation, for debugging purposes (e.g. putting a guard page after all allocations), or for memory allocation logging.

Memory Allocation Handing is done via providing allocator functions in a MeshLoader_AllocationCallbacks structure, defined as: 

typedef struct {
    MeshLoader_StructureType                            structureType;
    void                                              * pNext;
    void                                              * pUserData;
    MeshLoader_AllocationFunction                       allocationFunction;
    MeshLoader_ReallocationFunction                     reallocationFunction;
    MeshLoader_FreeFunction                             freeFunction;
    MeshLoader_InternalAllocationNotificationFunction   internalAllocationNotificationFunction;
    MeshLoader_InternalAllocationNotificationFunction   internalReallocationNotificationFunction;
    MeshLoader_InternalAllocationNotificationFunction   internalFreeNotificationFunction;
} MeshLoader_AllocationCallbacks;
  • structureType is the type of the structure.
  • pNext is NULL or a pointer to a structure extending this structure.
  • pUserData is a value to be interpreted by the implementation of the callbacks. When any of the callbacks in MeshLoader_AllocationCallbacks are called, the library implementation will pass this value as the first parameter to the callback. This value can vary each time the allocator is passed into a command, even when the same object takes an allocator in multiple commands.
  • allocationFunction is a MeshLoader_AllocationFunction pointer to an application-defined memory allocation function.
  • reallocationFunction is a MeshLoader_ReallocationFunction pointer to an application-defined memory reallocation function.
  • freeFunction is a MeshLoader_FreeFunction pointer to an application-defined memory free function.
  • internalAllocationNotificationFunction is a MeshLoader_InternalAllocationNotificationFunction pointer to an application-defined function that is called by the implementation when the library makes internal allocations.
  • internalReallocationNotificationFunction is a MeshLoader_InternalAllocationNotificationFunction pointer to an application-defined function that is called by the implementation when the library makes internal reallocations.
  • internalFreeNotificationFunction is a MeshLoader_InternalAllocationNotificationFunction pointer to an application-defined function that is called by the implementation when the library frees internal allocations.

Valid Usage

  • MLUID-MeshLoader_AllocationCallbacks-allocationFunction-00012
    allocationFunction must be a valid pointer to a valid user-defined MeshLoader_AllocationFunction.
  • MLUID-MeshLoader_AllocationCallbacks-reallocationFunction-00013
    reallocationFunction must be a valid pointer to a valid user-defined MeshLoader_ReallocationFunction.
  • MLUID-MeshLoader_AllocationCallbacks-freeFunction-00014
    freeFunction must be a valid pointer to a valid user-defined MeshLoader_FreeFunction.
  • MLUID-MeshLoader_AllocationCallbacks-internalNotifications-00015
    If either of internalAllocationNotificationFunction, internalReallocationNotificationFunction or internalFreeNotificationFunction is not NULL, all three must be valid pointers to valid MeshLoader_InternalAllocationNotificationFunction user-defined functions.

Valid Usage (Implicit)

  • MLUID-MeshLoader_AllocationCallbacks-structureType
    structureType must be MeshLoader_StructureType_AllocationCallbacks.
  • MLUID-MeshLoader_AllocationCallbacks-pNext
    pNext must be NULL.

The type of allocationFunction, MeshLoader_AllocationFunction is: 

typedef void * ( * MeshLoader_AllocationFunction ) (
    void                              * pUserData,
    MeshLoader_size                     size,
    MeshLoader_size                     alignment,
    MeshLoader_SystemAllocationScope    allocationScope
);
  • pUserData is the value specified for MeshLoader_AllocationCallbacks::pUserData in the allocator specified by the application.
  • size is the size in bytes of the requested allocation.
  • alignment is the requested alignment of the allocation in bytes and must be a power of two.
  • allocationScope is a MeshLoader_SystemAllocationScope value specifying the allocation scope of the lifetime of the allocation.

If allocationFunction is unable to allocate the requested memory, it must return NULL. If the allocation is successful, it must return a valid pointer to memory allocation containing at least size bytes, and with the pointer value being a multiple of alignment bytes.

Correct library operation cannot be assumed if the application does not follow these rules.

For example, internalAllocation (or internalReallocation) could cause termination of running Mesh Loader instance(s) on a failed allocation for debugging purposes, either directly or indirectly. In these circumstances, it cannot be assumed that any part of any affected MeshLoader_Instance objects are going to operate correctly (even MeshLoader_destroyInstance) , and the application must ensure it cleans up properly via other means (e.g. process termination).

If allocationFunction returns NULL, and the implementation is unable to continue correct processing of the current command without the requested allocation, it must treat this as a runtime error, and generate MeshLoader_Result_OutOfMemory at the appropriate time of the command in which the condition was detected, as described in Return Codes.

If the implementation is able to continue correct processing of the current command without the requested allocation, then it may do so, and must not generate MeshLoader_Result_OutOfMemory as a result of this failed allocation.

The type of reallocationFunction, MeshLoader_ReallocationFunction is: 

typedef void * ( * MeshLoader_ReallocationFunction ) (
        void                              * pUserData,
        void                              * pOriginal,
        MeshLoader_size                     size,
        MeshLoader_size                     alignment,
        MeshLoader_SystemAllocationScope    allocationScope
);
  • pUserData is the value specified for MeshLoader_AllocationCallbacks::pUserData in the allocator specified by the application.
  • pOriginal must be either NULL or a pointer previously returned by allocationFunction or reallocationFunction of a compatible allocator.
  • size is the size in bytes of the requested allocation.
  • alignment is the requested alignment of the allocation in bytes and must be a power of two.
  • allocationScope is a MeshLoader_SystemAllocationScope value specifying the allocation scope of the lifetime of the allocation.

reallocationFunction must return an allocation with enough space for size bytes, and the contents of the original allocation from bytes zero to min(original size, new size) - 1 must be preserved in the returned allocation. If size is larger than the old size, the contents of the additional space are undefined. If satisfying these requirements involves creating a new allocation, then the old allocation should be freed.

If pOriginal is NULL, then reallocationFunction must behave equivalently to a call of MeshLoader_AllocationFunction with the same parameter values (without pOriginal)

If size is zero, then reallocationFunction must behave equivalently to a call of MeshLoader_FreeFunction with the same pUserData parameter value, and pMemory equal to pOriginal.

If pOriginal is not NULL, the implementation must ensure that alignment is equal to the alignment used to originally allocate pOriginal.

If this function fails and pOriginal is not NULL, the application must not free the old allocation.

Additionally, reallocationFunction must follow the same rules for MeshLoader_AllocationFunction.

The type of freeFunction, MeshLoader_FreeFunction is: 

typedef void ( * MeshLoader_FreeFunction ) (
        void                              * pUserData,
        void                              * pMemory
);
  • pUserData is the value specified for MeshLoader_AllocationCallbacks::pUserData in the allocator specified by the application.
  • pMemory is the allocation to be freed.

pMemory may be NULL, which the callback must handle safely. If pMemory is not NULL, it must be a pointer previously allocated by allocationFunction or reallocationFunction. The application should free this memory.

The type of internalAllocationNotificationFunction, internalReallocationNotificationFunction and internalFreeNotificationFunction is: 

typedef void ( * MeshLoader_InternalAllocationNotificationFunction ) (
        void                                      * pUserData,
        MeshLoader_AllocationNotification   const * pNotification
);

These are purely informational callbacks.

Each allocation has an allocation scope defining its lifetime and which object it is associated with. Possible values passed to the allocationScope parameter of the callback functions specified by MeshLoader_AllocationCallbacks, indicating the allocation scope, are: 

typedef enum {
    MeshLoader_SystemAllocationScope_Unknown        = 0x00000000U,
    MeshLoader_SystemAllocationScope_Instance       = 0x00000001U,
    MeshLoader_SystemAllocationScope_Worker         = 0x00000002U,
    MeshLoader_SystemAllocationScope_Object         = 0x00000003U,
    MeshLoader_SystemAllocationScope_Component      = 0x00000004U,
} MeshLoader_SystemAllocationScope;
  • MeshLoader_SystemAllocationScope_Unknown specifies that the allocation scope is undefined.
  • MeshLoader_SystemAllocationScope_Instance specifies that the allocation is scoped to the lifetime of a MeshLoader_Instance.
  • MeshLoader_SystemAllocationScope_Worker specifies that the allocation is scoped to the lifetime of a MeshLoader_Job being processed by Mesh Loader Workers. This memory must be usable across multiple processor threads.
  • MeshLoader_SystemAllocationScope_Object specifies that the allocation is scoped to the lifetime of a Mesh Loader Object that is being created or used.
  • MeshLoader_SystemAllocationScope_Component specifies that the allocation is scoped to the lifetime of a component of a Mesh Loader Object that is being created or used.

The MeshLoader_AllocationNotification structure is defined as: 

typedef struct {
    MeshLoader_StructureType            structureType;
    void                        const * pNext;
    void                              * pMemory;
    void                              * pOldMemory;
    MeshLoader_size                     size;
    MeshLoader_size                     alignment;
    MeshLoader_SystemAllocationScope    allocationScope;
    MeshLoader_StringLiteral            explicitMemoryPurpose;
} MeshLoader_AllocationNotification;
  • structureType is the type of the structure.
  • pNext is NULL or a pointer to a structure extending this structure.
  • If a parameter of internalAllocationNotificationFunction or internalReallocationNotificationFunction pMemory will contain the address of the allocated resource. If a parameter of internalFreeNotificationFunction, pMemory will contain the address of the resource that will be freed.
  • If a parameter of internalReallocationNotificationFunction, pOldMemory will contain the old address of the resource.
  • If a parameter of internalAllocationNotificationFunction or internalReallocationNotificationFunction, size will contain the size, in bytes, of the memory allocated at pMemory.
  • If a parameter of internalAllocationNotificationFunction or internalReallocationNotificationFunction, alignment will contain the alignment, in bytes, of the memory allocated at pMemory. This value is a power of two.
  • allocationScope is a MeshLoader_SystemAllocationScope value specifying the allocation scope of the lifetime of the allocation.
  • explicitMemoryPurpose is a pointer to a null-terminated, UTF-8 formatted MeshLoader_StringLiteral specifying the explicit purpose of the allocation.

pNotification is, just like the function it is passed into (MeshLoader_AllocationNotification), purely information. Consequently, the application must not apply any allocation or modification operations to the addresses received through the pMemory or pOldMemory values.

7. User Defined Jobs

For object types/formats that are not available in the standard implementation, it can be extended with user-defined jobs. These are created by specifying an extending structure to the MeshLoader_CreateJobInfo structures in the MeshLoader_JobsCreateInfo passed to the MeshLoader_createJobs call. These jobs are referred to as Custom Jobs.

To access the Custom Job types and functions, include the "customJob" header 

#include <meshLoader/customJob>

7.1. Custom Job Creation

To create a custom job, add the MeshLoader_CustomJobInfo to the MeshLoader_JobsCreateInfo::pNext chain when creating Job Objects. The structure is defined as follows: 

typedef struct {
    MeshLoader_StructureType            structureType;
    void                        const * pNext;
    void                              * pUserData;
    MeshLoader_Job_MainFunction         jobFunction;
} MeshLoader_CustomJobInfo;
  • structureType is the type of the structure.
  • pNext is NULL or a pointer to the structure extending this structure.
  • pUserData is a value to be interpreted by the implementation of the custom job. When a worker thread will call the jobFunction to process a part of the job, the user can acquire this value with MeshLoader_Job_getUserData.
  • jobFunction is a MeshLoader_Job_MainFunction pointer to an application-defined function that is called by the implementation every time a Worker Thread is assigned to process a part of the defined Job.

Valid Usage (Implicit)

  • MLUID-MeshLoader_CustomJobInfo-structureType
    structureType must be MeshLoader_StructureType_CustomJobInfo.
  • MLUID-MeshLoader_CustomJobInfo-pNext
    pNext must either be NULL, or a valid pointer to a valid structure that would be expected in the pNext chain of MeshLoader_CreateJobInfo.
  • MLUID-MeshLoader_CustomJobInfo-jobFunction
    jobFunction must be a valid pointer to an application defined Job main function.

The MeshLoader_Job_MainFunction is described as follows: 

typedef MeshLoader_Result ( * MeshLoader_Job_MainFunction ) (
        MeshLoader_Job_Context  context
);
  • context is a MeshLoader_Job_Context object handle, representing the data that is accessible from the function through API calls.

Valid Usage

  • MLUID-MeshLoader_Job_MainFunction-return-00029
    An application-defined function MeshLoader_Job_MainFunction must return MeshLoader_Result_Success when the function executed successfully.

The MeshLoader_Job_Context is defined as follows: 

MESH_LOADER_DEFINE_HANDLE ( MeshLoader_Job_Context )

7.2. Custom Job Garbage Collection

Since all jobs are executed on multiple CPU threads, a call to a MeshLoader_Job_MainFunction is a call done from a separate thread to the main application thread, well-defined behaviour for Custom Jobs is hard to achieve. Added to this is the large size of object files and the long times required to load these files. To bypass one of the major problems of this, that is memory allocation, any large amount of data should be managed with the MeshLoader_Job_*memory functions. These ensure that in the case of errors or thread termination, the memory is safely freed.

To allocate memory from a MeshLoader_Job_MainFunction, call: 

MeshLoader_Result MeshLoader_Job_allocateMemory (
        MeshLoader_Job_Context      jobContext,
        MeshLoader_size             size,
        void                     ** ppMemory
);

If the memory allocation fails, ppMemory will contain the NULL value.

Valid Usage (Implicit)

  • MLUID-MeshLoader_Job_allocateMemory-jobContext-parameter
    jobContext must be a valid MeshLoader_Job_Context handle received from the current MeshLoader_Job_MainFunction call.
  • MLUID-MeshLoader_Job_allocateMemory-size-parameter
    size must be greater than 0.
  • MLUID-MeshLoader_Job_allocateMemory-ppMemory-parameter
    ppMemory must be a valid pointer to a void * value.

Return Codes

Success
  • MeshLoader_Result_Success
Failure
  • MeshLoader_Result_OutOfMemory
  • MeshLoader_Result_MutexError

To allocate memory from a MeshLoader_Job_MainFunction, call: 

MeshLoader_Result MeshLoader_Job_allocateMemory2 (
        MeshLoader_Job_Context      jobContext,
        MeshLoader_size             size,
        MeshLoader_size             alignment,
        void                     ** ppMemory
);
  • jobContext is a MeshLoader_Job_Context handle given as a parameter in the MeshLoader_Job_MainFunction.
  • size is the size, in bytes, of the memory to allocate.
  • alignment is the alignment, in bytes, of the memory to allocate.
  • ppMemory is a pointer to the pointer to store the allocated memory into

If the memory allocation fails, ppMemory will contain the NULL value.

Valid Usage (Implicit)

  • MLUID-MeshLoader_Job_allocateMemory2-jobContext-parameter
    jobContext must be a valid MeshLoader_Job_Context handle received from the current MeshLoader_Job_MainFunction call.
  • MLUID-MeshLoader_Job_allocateMemory2-size-parameter
    size must be greater than 0.
  • MLUID-MeshLoader_Job_allocateMemory2-alignment-parameter
    alignment must be a greater than 0 and must be a power of two.
  • MLUID-MeshLoader_Job_allocateMemory2-ppMemory-parameter
    ppMemory must be a valid pointer to a void * value.

Return Codes

Success
  • MeshLoader_Result_Success
Failure
  • MeshLoader_Result_OutOfMemory
  • MeshLoader_Result_MutexError

To reallocate memory from a MeshLoader_Job_MainFunction, call: 

MeshLoader_Result MeshLoader_Job_reallocateMemory (
        MeshLoader_Job_Context      jobContext,
        void                      * pOldMemory,
        MeshLoader_size             size,
        void                     ** ppMemory
);
  • jobContext is a MeshLoader_Job_Context handle given as a parameter in the MeshLoader_Job_MainFunction.
  • pOldMemory is a pointer to the old memory that is to be reallocated.
  • size is the size in bytes of the memory to allocate.
  • ppMemory is a pointer to the pointer to store the allocated memory into

If the memory allocation fails, ppMemory will contain the NULL value.

Valid Usage (Implicit)

Return Codes

Success
  • MeshLoader_Result_Success
Failure
  • MeshLoader_Result_OutOfMemory
  • MeshLoader_Result_MutexError

To reallocate memory from a MeshLoader_Job_MainFunction, call: 

MeshLoader_Result MeshLoader_Job_reallocateMemory2 (
        MeshLoader_Job_Context      jobContext,
        void                      * pOldMemory,
        MeshLoader_size             size,
        MeshLoader_size             alignment,
        void                     ** ppMemory
);
  • jobContext is a MeshLoader_Job_Context handle given as a parameter in the MeshLoader_Job_MainFunction.
  • pOldMemory is a pointer to the old memory that is to be reallocated.
  • size is the size, in bytes, of the memory to allocate.
  • alignment is the alignment, in bytes, of the memory to allocate.
  • ppMemory is a pointer to the pointer to store the allocated memory into

If the memory allocation fails, ppMemory will contain the NULL value.

Valid Usage (Implicit)

Return Codes

Success
  • MeshLoader_Result_Success
Failure
  • MeshLoader_Result_OutOfMemory
  • MeshLoader_Result_MutexError

To free memory from a MeshLoader_Job_MainFunction, call: 

MeshLoader_Result MeshLoader_Job_freeMemory (
        MeshLoader_Job_Context    jobContext,
        void                    * pMemory
);

Valid Usage (Implicit)

Return Codes

Success
  • MeshLoader_Result_Success
Failure
  • MeshLoader_Result_OutOfMemory
  • MeshLoader_Result_MutexError

To release the memory tracking of a pointer allocated in a MeshLoader_Job_MainFunction, call: 

MeshLoader_Result MeshLoader_Job_releaseMemory (
        MeshLoader_Job_Context    jobContext,
        void                    * pMemory
);

This function is used to release memory from garbage collection tracking, making it possible to pass memory to objects that are to be used after the Job has finished, such as Mesh Data.

Valid Usage (Implicit)

Return Codes

Success
  • MeshLoader_Result_Success
Failure
  • MeshLoader_Result_OutOfMemory
  • MeshLoader_Result_MutexError

7.3. Custom Job API Functions

To acquire the pUserData given to the MeshLoader_CustomJobInfo at job creation, call: 

MeshLoader_Result MeshLoader_Job_getUserData (
        MeshLoader_Job_Context    jobContext,
        void                   ** ppUserData
);

Valid Usage (Implicit)

  • MLUID-MeshLoader_Job_getUserData-jobContext-parameter
    jobContext must be a valid MeshLoader_Job_Context handle received from the current MeshLoader_Job_MainFunction call.
  • MLUID-MeshLoader_Job_getUserData-ppUserData-parameter
    ppUserData must be a valid pointer to a void * value.

Return Codes

Success
  • MeshLoader_Result_Success

To store data for the next call of MeshLoader_Job_MainFunction, call: 

MeshLoader_Result MeshLoader_Job_setDataForNextCall (
        MeshLoader_Job_Context    jobContext,
        void                    * pData
);

Valid Usage (Implicit)

Return Codes

Success
  • MeshLoader_Result_Success

To acquire the data stored by the previous call of MeshLoader_Job_MainFunction, call: 

MeshLoader_Result MeshLoader_Job_getDataFromPreviousCall (
        MeshLoader_Job_Context    jobContext,
        void                   ** ppData
);

Valid Usage (Implicit)

  • MLUID-MeshLoader_Job_getDataFromPreviousCall-jobContext-parameter
    jobContext must be a valid MeshLoader_Job_Context handle received from the current MeshLoader_Job_MainFunction call.
  • MLUID-MeshLoader_Job_getDataFromPreviousCall-ppData-parameter
    ppData must be a valid pointer to a void * value.

Return Codes

Success
  • MeshLoader_Result_Success

To get the progress of the job, call: 

MeshLoader_Result MeshLoader_Job_getProgress (
        MeshLoader_Job_Context  jobContext,
        float                 * pProgress
);
  • jobContext is a MeshLoader_Job_Context handle given as a parameter in the MeshLoader_Job_MainFunction.
  • pProgress is a pointer to a float to load the progress into after a successful call. The progress is a value between 0.0f and 1.0f, 0.0f representing a job that is 0% done, and 1.0f representing a job that is 100% done. As an example, a progress of 0.25f represents a job progress of 25%.

Valid Usage (Implicit)

  • MLUID-MeshLoader_Job_getProgress-jobContext-parameter
    jobContext must be a valid MeshLoader_Job_Context handle received from the current MeshLoader_Job_MainFunction call.
  • MLUID-MeshLoader_Job_getProgress-pProgress-parameter
    pProgress must be a valid pointer to a float value.

Return Codes

Success
  • MeshLoader_Result_Success

To set the progress of the job, call: 

MeshLoader_Result MeshLoader_Job_setProgress (
        MeshLoader_Job_Context  jobContext,
        float                   progress
);
  • jobContext is a MeshLoader_Job_Context handle given as a parameter in the MeshLoader_Job_MainFunction.
  • progress is a float to store the progress from. The progress is a value between 0.0f and 1.0f, 0.0f representing a job that is 0% done, and 1.0f representing a job that is 100% done. As an example, a progress of 0.25f represents a job progress of 25%.

Valid Usage (Implicit)

  • MLUID-MeshLoader_Job_setProgress-jobContext-parameter
    jobContext must be a valid MeshLoader_Job_Context handle received from the current MeshLoader_Job_MainFunction call.
  • MLUID-MeshLoader_Job_setProgress-progress-parameter
    parameter must be greater than or equal to 0.0f and less than or equal to 1.0f.

Return Codes

Success
  • MeshLoader_Result_Success

To get the load mode of the job, call: 

MeshLoader_Result MeshLoader_Job_getLoadMode (
        MeshLoader_Job_Context          jobContext,
        MeshLoader_MeshLoadModeFlags  * pLoadMode
);

Valid Usage (Implicit)

Return Codes

Success
  • MeshLoader_Result_Success

To get the input path of the job, call: 

MeshLoader_Result MeshLoader_Job_getInputPath (
        MeshLoader_Job_Context        jobContext,
        MeshLoader_StringLiteral    * pInputPath
);

Valid Usage (Implicit)

Return Codes

Success
  • MeshLoader_Result_Success

To set the Mesh Vertex Data, call: 

MeshLoader_Result MeshLoader_Job_setMeshVertexData (
        MeshLoader_Job_Context          jobContext,
        MeshLoader_uint32               vertexCount,
        MeshLoader_VertexData   const * pVertices
);

Valid Usage

Valid Usage (Implicit)

  • MLUID-MeshLoader_Job_setMeshVertexData-jobContext-parameter
    jobContext must be a valid MeshLoader_Job_Context handle received from the current MeshLoader_Job_MainFunction call.
  • MLUID-MeshLoader_Job_setMeshVertexData-vertexCount-parameter
    vertexCount must be greater than 0.
  • MLUID-MeshLoader_Job_setMeshVertexData-pVertices-parameter
    pVertices must be a valid pointer to an array of vertexCount valid MeshLoader_VertexData structures.

Return Codes

Success
  • MeshLoader_Result_Success

To set the Mesh Face Data, call: 

MeshLoader_Result MeshLoader_Job_setMeshFaceData (
        MeshLoader_Job_Context          jobContext,
        MeshLoader_uint32               faceCount,
        MeshLoader_FaceData     const * pFaces
);

Valid Usage

Valid Usage (Implicit)

  • MLUID-MeshLoader_Job_setMeshFaceData-jobContext-parameter
    jobContext must be a valid MeshLoader_Job_Context handle received from the current MeshLoader_Job_MainFunction call.
  • MLUID-MeshLoader_Job_setMeshFaceData-faceCount-parameter
    faceCount must be greater than 0.
  • MLUID-MeshLoader_Job_setMeshFaceData-pFaces-parameter
    pFaces must be a valid pointer to an array of faceCount valid MeshLoader_FaceData structures.

Return Codes

Success
  • MeshLoader_Result_Success

To set the Mesh Index Data, call: 

MeshLoader_Result MeshLoader_Job_setMeshIndexData (
        MeshLoader_Job_Context          jobContext,
        MeshLoader_IndexData    const * pIndexData
);

Valid Usage

Valid Usage (Implicit)

  • MLUID-MeshLoader_Job_setMeshIndexData-jobContext-parameter
    jobContext must be a valid MeshLoader_Job_Context handle received from the current MeshLoader_Job_MainFunction call.
  • MLUID-MeshLoader_Job_setMeshIndexData-pFaces-pIndexData
    pIndexData must be a valid pointer to a valid MeshLoader_IndexData structure, its indexCount must. be greater than 0 and its pIndices must be a valid pointer to an array of indexCount valid MeshLoader_uint32 values.

Return Codes

Success
  • MeshLoader_Result_Success

To mark a job as finished, call: 

MeshLoader_Result MeshLoader_Job_finish (
        MeshLoader_Job_Context          jobContext
);

This function will cause the Mesh Loader Library implementation stop calling this function, and mark the executed Job as Finished. Any resources that are scoped to the Job and are persistent must be released, cleared or freed prior to this call.

Valid Usage

Valid Usage (Implicit)

Return Codes

Success
  • MeshLoader_Result_Success

7.4. Custom Job Implementation Guidelines

In order to facilitate easy pause, resume and stop of jobs and to avoid unresponsive threads, job execution functions should be implemented to execute recurrently, either with a state machine or by other means. The Job Function has no method of receiving a stop/terminate request, and must wait for the stop of the call to treat those requests. Consequently, the function should not exceed a given period of execution time, depending on scenario.

If a recurrent function approach is not chosen, another approach would be defining a stop conditional variable and passing it in the MeshLoader_CustomJobInfo::pUserData member, and acquiring it in the Job Main Function with MeshLoader_Job_getUserData.

The Job Main Function should also account for specific allocate/free resource function/states to make it easy to treat error states and possible leaks in the case of stop/termination.

The user defined job must treat all operations with care, as in the case of in-thread runtime-errors, traps, segmentation faults and any other execution halting errors, memory freeing is not guaranteed.

To avoid memory issues, use the Garbage Collection Allocation Functions. These are not mandatory, such as not requiring any allocation, having the memory pre-allocated inside the MeshLoader_CustomJobInfo::pUserData, or if thread is not error-prone and no terminate calls are to be done.

The standard implementation object loader functions are implemented using only the Custom Job API Functions and the Garbage Collection Memory Allocators for robustness, so these can be used as examples:

  • Wavefront .OBJ file loader, recurrent calls: objWorker.c.