Skip to content

Commit

Permalink
Cosmetic changes to README, add .gitignore
Browse files Browse the repository at this point in the history 
Fixed some typos in tinyexr.h.
  • Loading branch information
@akien-mga
akien-mga committed May 1, 2020
1 parent 4dbd05a commit 80e0f29
Show file tree
Hide file tree
Showing 3 changed files with 65 additions and 68 deletions.
2 changes: 2 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
output.exr
test_tinyexr
109 changes: 52 additions & 57 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,19 @@

[![Coverity Scan Build Status](https://scan.coverity.com/projects/5827/badge.svg)](https://scan.coverity.com/projects/5827)

`tinyexr` is a small, single header-only library to load and save OpenEXR(.exr) images.
`tinyexr` is written in portable C++(no library dependency except for STL), thus `tinyexr` is good to embed into your application.
`tinyexr` is a small, single header-only library to load and save OpenEXR (.exr) images.
`tinyexr` is written in portable C++ (no library dependency except for STL), thus `tinyexr` is good to embed into your application.
To use `tinyexr`, simply copy `tinyexr.h` into your project.

Current status of `tinyexr` is:

- OpenEXR v1 image
- [x] Scanline format
- [ ] Tiled format
- [x] Tile format with no LoD(load).
- [ ] Tile format with LoD(load).
- [ ] Tile format with no LoD(save).
- [ ] Tile format with LoD(save).
- [x] Tile format with no LoD (load).
- [ ] Tile format with LoD (load).
- [ ] Tile format with no LoD (save).
- [ ] Tile format with LoD (save).
- [x] Custom attributes
- OpenEXR v2 image
- [ ] Multipart format
Expand All @@ -38,19 +38,19 @@ Current status of `tinyexr` is:
- [x] ZIP
- [x] ZIPS
- [x] PIZ
- [x] ZFP(tinyexr extension)
- [x] ZFP (tinyexr extension)
- [ ] B44?
- [ ] B44A?
- [ ] PIX24?
- Line order.
- [x] Increasing, decreasing(load)
- [x] Increasing, decreasing (load)
- [ ] Random?
- [ ] Increasing, decreasing(save)
- Pixel format(UINT, FLOAT).
- [x] UINT, FLOAT(load)
- [x] UINT, FLOAT(deep load)
- [x] UINT, FLOAT(save)
- [ ] UINT, FLOAT(deep save)
- [ ] Increasing, decreasing (save)
- Pixel format (UINT, FLOAT).
- [x] UINT, FLOAT (load)
- [x] UINT, FLOAT (deep load)
- [x] UINT, FLOAT (save)
- [ ] UINT, FLOAT (deep save)
- Support for big endian machine.
- [x] Loading scanline image
- [x] Saving scanline image
Expand All @@ -67,23 +67,23 @@ Current status of `tinyexr` is:
- [ ] OpenMP multi-threading in deep image loading.
- [ ] OpenMP multi-threading in deep image saving.
* C interface.
* You can easily write language bindings(e.g. golang)
* You can easily write language bindings (e.g. golang)

# Use case

## New TinyEXR(v0.9.5+)
## New TinyEXR (v0.9.5+)

* Godot. Multi-platform 2D and 3D game engine https://godotengine.org/
* Filament. PBR engine. https://github.com/google/filament
* PyEXR. Loading OpenEXR (.exr) images using Python. https://github.com/ialhashim/PyEXR
* The-Forge. The Forge Cross-Platform Rendering Framework PC, Linux, Ray Tracing, macOS / iOS, Android, XBOX, PS4 https://github.com/ConfettiFX/The-Forge
* Your project here!

## Older TinyEXR(v0.9.0)
## Older TinyEXR (v0.9.0)

* mallie https://github.com/lighttransport/mallie
* Cinder 0.9.0 https://libcinder.org/notes/v0.9.0
* Piccante(develop branch) http://piccantelib.net/
* Piccante (develop branch) http://piccantelib.net/
* Your project here!

## Examples
Expand All @@ -93,7 +93,7 @@ Current status of `tinyexr` is:
* [examples/exr2rgbe/](examples/exr2rgbe) EXR to .hdr converter
* [examples/ldr2exr/](examples/exr2rgbe) LDR to EXR converter
* [examples/exr2ldr/](examples/exr2ldr) EXR to LDR converter
* [examples/cube2longlat/](examples/cube2longlat) Cubemap to longlat(equirectangler) converter
* [examples/cube2longlat/](examples/cube2longlat) Cubemap to longlat (equirectangler) converter

## Experimental

Expand All @@ -103,7 +103,7 @@ Current status of `tinyexr` is:

NOTE: **API is still subject to change**. See the source code for details.

Include `tinyexr.h` with `TINYEXR_IMPLEMENTATION` flag(do this only for **one** .cc file).
Include `tinyexr.h` with `TINYEXR_IMPLEMENTATION` flag (do this only for **one** .cc file).

```cpp
//Please include your own zlib-compatible API header before
Expand All @@ -116,11 +116,11 @@ Include `tinyexr.h` with `TINYEXR_IMPLEMENTATION` flag(do this only for **one**

### Compile flags

* `TINYEXR_USE_MINIZ` Use embedded miniz(default = 1). Please include `zlib.h` header(before `tinyexr.h`) if you disable miniz support.
* `TINYEXR_USE_PIZ` Enable PIZ compression support(default = 1)
* `TINYEXR_USE_ZFP` Enable ZFP compression supoort(TinyEXR extension, default = 0)
* `TINYEXR_USE_THREAD` Enable threaded loading using C++11 thread(Requires C++11 compiler. default = 0)
* `TINYEXR_USE_OPENMP` Enable OpenMP threading support(default = 1 if `_OPENMP` is defined)
* `TINYEXR_USE_MINIZ` Use embedded miniz (default = 1). Please include `zlib.h` header (before `tinyexr.h`) if you disable miniz support.
* `TINYEXR_USE_PIZ` Enable PIZ compression support (default = 1)
* `TINYEXR_USE_ZFP` Enable ZFP compression supoort (TinyEXR extension, default = 0)
* `TINYEXR_USE_THREAD` Enable threaded loading using C++11 thread (Requires C++11 compiler, default = 0)
* `TINYEXR_USE_OPENMP` Enable OpenMP threading support (default = 1 if `_OPENMP` is defined)
* Use `TINYEXR_USE_OPENMP=0` to force disable OpenMP code path even if OpenMP is available/enabled in the compiler.

### Quickly reading RGB(A) EXR file.
Expand All @@ -141,16 +141,16 @@ Include `tinyexr.h` with `TINYEXR_IMPLEMENTATION` flag(do this only for **one**
}
} else {
...
free(out); // relase memory of image data
free(out); // release memory of image data
}

```
### Reading layered RGB(A) EXR file.
If you want to read EXR image with layer info(Channel has a name with delimiter `.`), please use LoadEXRWithLayer` API.
If you want to read EXR image with layer info (channel has a name with delimiter `.`), please use `LoadEXRWithLayer` API.
You need to know layer name in advance(e.g. through `EXRLayers` API).
You need to know layer name in advance (e.g. through `EXRLayers` API).
```cpp
const char* input = ...;
Expand All @@ -170,7 +170,7 @@ You need to know layer name in advance(e.g. through `EXRLayers` API).
}
} else {
...
free(out); // relase memory of image data
free(out); // release memory of image data
}
```
Expand Down Expand Up @@ -381,7 +381,7 @@ See `example/deepview` for actual usage.
int ret = LoadDeepEXR(&deepImage, input, &err);
// acccess to each sample in the deep pixel.
// access to each sample in the deep pixel.
for (int y = 0; y < deepImage.height; y++) {
int sampleNum = deepImage.offset_table[y][deepImage.width-1];
for (int x = 0; x < deepImage.width-1; x++) {
Expand All @@ -406,18 +406,13 @@ See `example/deepview` for actual usage.

![DeepViewExample](https://github.com/syoyo/tinyexr/blob/master/examples/deepview/deepview_screencast.gif?raw=true)

## Defines

* TINYEXR_USE_MINIZ Set `1`(default) to use embedded miniz compression. If you want zlib or custom zlib compatible library, set `0` and link zlib library.
* TINYEXR_USE_ZFP Set `1` to use ZFP compression.

## TinyEXR extension

### ZFP

#### NOTE

TinyEXR adds ZFP compression as an experimemtal support(Linux and MacOSX only).
TinyEXR adds ZFP compression as an experimemtal support (Linux and MacOSX only).

ZFP only supports FLOAT format pixel, and its image width and height must be the multiple of 4, since ZFP compresses pixels with 4x4 pixel block.

Expand Down Expand Up @@ -474,35 +469,35 @@ Contribution is welcome!
- [ ] B44A?
- [ ] PIX24?
- [ ] Custom attributes
- [x] Normal image(EXR 1.x)
- [ ] Deep image(EXR 2.x)
- [ ] JavaScript library(experimental. using Emscripten)
- [x] Normal image (EXR 1.x)
- [ ] Deep image (EXR 2.x)
- [ ] JavaScript library (experimental, using Emscripten)
- [x] LoadEXRFromMemory
- [ ] SaveMultiChannelEXR
- [ ] Deep image save/load
- [ ] Write from/to memory buffer.
- [ ] Deep image save/load
- [ ] Tile format.
- [x] Tile format with no LoD(load).
- [ ] Tile format with LoD(load).
- [ ] Tile format with no LoD(save).
- [ ] Tile format with LoD(save).
- [x] Tile format with no LoD (load).
- [ ] Tile format with LoD (load).
- [ ] Tile format with no LoD (save).
- [ ] Tile format with LoD (save).
- [ ] Support for custom compression type.
- [x] zfp compression(Not in OpenEXR spec, though)
- [x] zfp compression (Not in OpenEXR spec, though)
- [ ] zstd?
- [x] Multi-channel.
- [ ] Multi-part(EXR2.0)
- [ ] Multi-part (EXR2.0)
- [x] Load multi-part image
- [ ] Load multi-part deep image
- [ ] Line order.
- [x] Increasing, decreasing(load)
- [x] Increasing, decreasing (load)
- [ ] Random?
- [ ] Increasing, decreasing(save)
- [ ] Pixel format(UINT, FLOAT).
- [x] UINT, FLOAT(load)
- [x] UINT, FLOAT(deep load)
- [x] UINT, FLOAT(save)
- [ ] UINT, FLOAT(deep save)
- [ ] Increasing, decreasing (save)
- [ ] Pixel format (UINT, FLOAT).
- [x] UINT, FLOAT (load)
- [x] UINT, FLOAT (deep load)
- [x] UINT, FLOAT (save)
- [ ] UINT, FLOAT (deep save)
- [ ] Support for big endian machine.
- [ ] Loading multi-part channel EXR
- [ ] Saving multi-part channel EXR
Expand Down Expand Up @@ -535,11 +530,11 @@ Contribution is welcome!

## Author(s)

Syoyo Fujita(syoyo@lighttransport.com)
Syoyo Fujita (syoyo@lighttransport.com)

## Contributor(s)

* Matt Ebb (http://mattebb.com) : deep image example. Thanks!
* Matt Pharr (http://pharr.org/matt/) : Testing tinyexr with OpenEXR(IlmImf). Thanks!
* Andrew Bell (https://github.com/andrewfb) & Richard Eakin (https://github.com/richardeakin) : Improving TinyEXR API. Thanks!
* Mike Wong (https://github.com/mwkm) : ZIPS compression support in loading. Thanks!
* Matt Ebb (http://mattebb.com): deep image example. Thanks!
* Matt Pharr (http://pharr.org/matt/): Testing tinyexr with OpenEXR(IlmImf). Thanks!
* Andrew Bell (https://github.com/andrewfb) & Richard Eakin (https://github.com/richardeakin): Improving TinyEXR API. Thanks!
* Mike Wong (https://github.com/mwkm): ZIPS compression support in loading. Thanks!
22 changes: 11 additions & 11 deletions tinyexr.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -287,7 +287,7 @@ typedef struct _DeepImage {
extern int LoadEXR(float **out_rgba, int *width, int *height,
const char *filename, const char **err);

// Loads single-frame OpenEXR image by specifing layer name. Assume EXR image contains A(single channel
// Loads single-frame OpenEXR image by specifying layer name. Assume EXR image contains A(single channel
// alpha) or RGB(A) channels.
// Application must free image data as returned by `out_rgba`
// Result image format is: float x RGBA x width x hight
Expand All @@ -302,7 +302,7 @@ extern int LoadEXRWithLayer(float **out_rgba, int *width, int *height,
//
// @param[out] layer_names List of layer names. Application must free memory after using this.
// @param[out] num_layers The number of layers
// @param[out] err Error string(wll be filled when the function returns error code). Free it using FreeEXRErrorMessage after using this value.
// @param[out] err Error string(will be filled when the function returns error code). Free it using FreeEXRErrorMessage after using this value.
//
// @return TINYEXR_SUCCEES upon success.
//
Expand Down Expand Up @@ -497,8 +497,8 @@ extern int LoadEXRFromMemory(float **out_rgba, int *width, int *height,
#endif // TINYEXR_H_

#ifdef TINYEXR_IMPLEMENTATION
#ifndef TINYEXR_IMPLEMENTATION_DEIFNED
#define TINYEXR_IMPLEMENTATION_DEIFNED
#ifndef TINYEXR_IMPLEMENTATION_DEFINED
#define TINYEXR_IMPLEMENTATION_DEFINED

#include <algorithm>
#include <cassert>
Expand Down Expand Up @@ -619,7 +619,7 @@ namespace miniz {
- Critical fix for the MZ_ZIP_FLAG_DO_NOT_SORT_CENTRAL_DIRECTORY bug
(thanks kahmyong.moon@hp.com) which could cause locate files to not find
files. This bug
would only have occured in earlier versions if you explicitly used this
would only have occurred in earlier versions if you explicitly used this
flag, OR if you used mz_zip_extract_archive_file_to_heap() or
mz_zip_add_mem_to_archive_file_in_place()
(which used this flag). If you can't switch to v1.15 but want to fix
Expand Down Expand Up @@ -7712,7 +7712,7 @@ static int rleCompress(int inLength, const char in[], signed char out[]) {

if (runEnd - runStart >= MIN_RUN_LENGTH) {
//
// Compressable run
// Compressible run
//

*outWrite++ = static_cast<char>(runEnd - runStart) - 1;
Expand Down Expand Up @@ -8056,7 +8056,7 @@ static void wav2Encode(
int p2 = 2; // == 1 << (level+1)

//
// Hierachical loop on smaller dimension n
// Hierarchical loop on smaller dimension n
//

while (p2 <= n) {
Expand Down Expand Up @@ -9582,7 +9582,7 @@ static bool DecompressZfp(float *dst, int dst_width, int dst_num_lines,
zfp = zfp_stream_open(NULL);

if (param.type == TINYEXR_ZFP_COMPRESSIONTYPE_RATE) {
zfp_stream_set_rate(zfp, param.rate, zfp_type_float, /* dimention */ 2,
zfp_stream_set_rate(zfp, param.rate, zfp_type_float, /* dimension */ 2,
/* write random access */ 0);
} else if (param.type == TINYEXR_ZFP_COMPRESSIONTYPE_PRECISION) {
zfp_stream_set_precision(zfp, param.precision, zfp_type_float);
Expand Down Expand Up @@ -10798,7 +10798,7 @@ static void ConvertHeader(EXRHeader *exr_header, const HeaderInfo &info) {
memcpy(exr_header->custom_attributes[i].type, info.attributes[i].type,
256);
exr_header->custom_attributes[i].size = info.attributes[i].size;
// Just copy poiner
// Just copy pointer
exr_header->custom_attributes[i].value = info.attributes[i].value;
}

Expand Down Expand Up @@ -12225,7 +12225,7 @@ size_t SaveEXRImageToMemory(const EXRImage *exr_image,
}
#endif

// TOOD(LTE): C++11 thread
// TODO(LTE): C++11 thread

// Use signed int since some OpenMP compiler doesn't allow unsigned type for
// `parallel for`
Expand Down Expand Up @@ -13582,5 +13582,5 @@ int SaveEXR(const float *data, int width, int height, int components,
#pragma clang diagnostic pop
#endif

#endif // TINYEXR_IMPLEMENTATION_DEIFNED
#endif // TINYEXR_IMPLEMENTATION_DEFINED
#endif // TINYEXR_IMPLEMENTATION

0 comments on commit 80e0f29

Please sign in to comment.