loader_aw

Load OBJ/MTL file formats
git clone git://git.meso-star.fr/loader_aw.git
Log | Files | Refs | README | LICENSE

README.md (3863B)

      1 # Loader of the Alias Wafefront obj and mtl file formats
      2 
      3 AW is a C library whose purpose is to load the Alias Wavefront
      4 [`obj`](http://www.martinreddy.net/gfx/3d/OBJ.spec) and
      5 [`mtl`](http://www.fileformat.info/format/material/) file formats. Only
      6 a subset of these formats are currently supported.
      7 
      8 For `obj` files, polygonal primitives with their per vertex-position,
      9 normal and texture coordinates are loaded. Smooth, common and material
     10 groupings are also handled correctly.
     11 
     12 For `mtl` files, ambient, diffuse, specular, glossiness and transmissive
     13 RGB or XYZ colors are supported. Additionally, it loads the refraction
     14 index and the illumination model. The library also loads the filename of
     15 ambient, diffuse, specular, glossiness and bump textures and their
     16 attributes (blend< u|v \>, color correction, channel mapping, texcoord
     17 < offset|scale|turbulence \>, image resolution and bump multiplier).
     18 
     19 ## Requirements
     20 
     21 - C compiler
     22 - POSIX make
     23 - pkg-config
     24 - [RSys](https://gitlab.com/vaplv/rsys/)
     25 
     26 ## Installation
     27 
     28 Edit config.mk as needed, then run:
     29 
     30     make clean install
     31 
     32 ## Release notes
     33 
     34 ### Version 2.1
     35 
     36 ### POSIX make
     37 
     38 Replace CMake by Makefile as build system. The build procedure is
     39 written in POSIX make, which the user can configure via the `config.mk`
     40 file. The POSIX script `make.sh` contains commands that could be found
     41 directly in the Makefile, but which are placed here to simplify its
     42 writing. Finally, a pkg-config file is provided to link the library as
     43 an external dependency.
     44 
     45 In addition to the features already provided by its CMake alternative,
     46 the Makefile supports the construction of static libraries, provides an
     47 uninstall target and updates compiler and linker flags to increase the
     48 security and robustness of generated binaries. In any case, the main
     49 motivation for using POSIX make is to rely on a good old
     50 well-established standard with simple functionality, available on all
     51 UNIX systems, thus simplifying its portability and support while being
     52 much lighter.
     53 
     54 ### Miscellaneous
     55 
     56 Update the `aw_obj_desc` data structure: add the number of positions,
     57 texcoords and normals as new member variables of the structure.
     58 
     59 ### Version 2.0.1
     60 
     61 Sets the CMake minimum version to 3.1: since CMake 3.20, version 2.8 has
     62 become obsolete.
     63 
     64 ### Version 2.0
     65 
     66 Full review and refactoring of the code.
     67 
     68 - The named groups, the maps and the materials become pod data
     69   structures without any init/release/copy function. Their name is now
     70   exposed as a regular `const char*` rather than stored in a `struct
     71   str` data structure.
     72 - All floating point data are encoded in double precision rather than in
     73   single precision.
     74 - The `struct aw_obj_vertex` data structure stores only the index of the
     75   vertex attributes. Their values are retrieved by the new
     76   `aw_obj_get_vertex_data` function.
     77 - Add an optional stream name parameter to the
     78   `aw_<obj|mtl>_load_stream` functions: it allows the user to define the
     79   name of the stream to load, a name that is internally used by the
     80   logger to print messages regarding the stream.
     81 - Rename the `get` functions.
     82 - Rely on RSys to parse the input files and to perform text conversions.
     83 - Add support of the `map_bump` keyword as an alias of the `bump`
     84   keyword in the mtl fileformat.
     85 
     86 ### Version 1.3.1
     87 
     88 - Update the version of the RSys dependency to 0.6: replace the
     89   deprecated `[N]CHECK` macros by the new macro `CHK`.
     90 
     91 ### Version 1.3
     92 
     93 - Add the `aw_obj_purge` and `aw_mtl_purge` functions that not only
     94   reset the state of the loaders, as the `aw_obj_clear` and
     95   `aw_mtl_clear` functions, but also free their internal memory.
     96 
     97 ## License
     98 
     99 Copyright (C) 2014-2017, 2020-2023 Vincent Forest (vaplv@free.fr)
    100 
    101 AW is free software released under GPL v3+ license: GNU GPL version 3 or
    102 later.  You are welcome to redistribute it under certain conditions;
    103 refer to the COPYING file for details.