Changeset 37236 in project for wiki/eggref/5/sdl2-image


Ignore:
Timestamp:
02/14/19 01:35:38 (4 months ago)
Author:
jacius
Message:

Update sdl2-image wiki for version 0.2.0.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/sdl2-image

    r37226 r37236  
    2424
    2525The sdl2-image egg requires the [[/egg/sdl2|sdl2]] egg,
    26 [[http://libsdl.org/|Simple DirectMedia Layer]] version 2.0.0 or
    27 higher, and [[http://www.libsdl.org/projects/SDL_image/|SDL_image]]
    28 version 2.0 or higher. It will not work with older versions of SDL or
    29 SDL_image.
     26[[http://libsdl.org/|Simple DirectMedia Layer]] 2.0.0 or higher,
     27and [[http://www.libsdl.org/projects/SDL_image/|SDL_image]]  2.0 or higher.
     28It will not work with older versions of SDL or SDL_image.
    3029
    3130This egg requires CHICKEN Scheme 4.8 or higher.
    32 Please file an issue or contact the maintainer if you need to use this library with an earlier version of CHICKEN Scheme.
     31As of version 0.2.0, this egg is compatible with both CHICKEN 4 and CHICKEN 5.
    3332
    3433
    3534== Installation
    3635
    37 When installing the egg, you should set the {{SDL2_FLAGS}} environment
    38 variable to a string of compiler flags to be used when compiling the
    39 egg. If you have the {{sdl2-config}} helper program installed on your
    40 system, you can set appropriate flags and install the extension like
    41 so (notice these are back ticks, not quotes):
    42 
    43  export SDL2_FLAGS=`sdl2-config --cflags --libs`
     36In most cases, you can install the sdl2-image egg in the usual way:
     37
    4438 chicken-install sdl2-image
    4539
    46 If you do not have the {{sdl2-config}} helper program installed on your
    47 computer, you may manually specify SDL-related compiler flags (notice
    48 these are double quotes, not back ticks):
    49 
    50  export SDL2_FLAGS="-I/usr/local/include/SDL2 -L/usr/local/lib -lSDL2"
     40The installer will try to automatically determine the SDL2 compiler and linker flags
     41using the {{sdl2-config}} command.
     42
     43In special cases, you may need to set the
     44{{SDL2_CFLAGS}}, {{SDL2_LDFLAGS}}, {{SDL2_IMAGE_CFLAGS}}, and/or {{SDL2_IMAGE_LDFLAGS}}
     45environment variables to provide the compiler and linker flags, then try again.
     46(The {{SDL2_IMAGE_*}} flags are used in addition to the {{SDL2_*}} flags.)
     47
     48For example:
     49
     50 export SDL2_CFLAGS="-I/usr/local/include/SDL2"
     51 export SDL2_LDFLAGS="-L/usr/local/lib -lSDL2"
     52 export SDL2_IMAGE_LDFLAGS="-lSDL2_image"
    5153 chicken-install sdl2-image
    5254
    53 By default, the sdl2-image egg will be linked against SDL_image using
    54 the compiler flag {{-lSDL2_image}}. You can override this by setting the
    55 {{SDL2_IMAGE_FLAGS}} environment variable, if needed. You can also use
    56 that environment variable in case you have installed SDL_image in a
    57 different location than SDL.
    58 
    59 The {{SDL2_FLAGS}} and {{SDL2_IMAGE_FLAGS}} environment variables are
    60 only needed during installation of the egg. They do not need to be set
    61 during normal use.
    62 
     55These environment variables are needed only when installing the egg itself.
     56They are not needed when compiling or running programs that use the egg.
     57
     58=== Installing on macOS
     59
     60On macOS, the sdl2-image egg can be compiled using either
     61UNIX-style libraries (e.g. compiled from source or installed via Homebrew)
     62or Mac-style frameworks (e.g. downloaded from the SDL website).
     63
     64When automatically determining compiler and linker flags on macOS,
     65the installer will first check to see if {{sdl2-config}} is available.
     66If it is available, the installer will use it to determine the flags.
     67
     68If {{sdl2-config}} is not available, the installer will check to see if
     69{{SDL2.framework}} and {{SDL2_image.framework}} are available
     70in either the {{/Library/Frameworks}} or {{/System/Library/Frameworks}} directories.
     71If so, the installer will use the frameworks.
     72
     73If the frameworks are installed in some other directory,
     74or if you want to force using the framework even when {{sdl2-config}} is available,
     75set the {{SDL2_CFLAGS}}, {{SDL2_LDFLAGS}}, {{SDL2_IMAGE_CFLAGS}}, and/or {{SDL2_IMAGE_LDFLAGS}}
     76enviroment variables to tell the compiler where to find the frameworks:
     77
     78 export SDL2_CFLAGS="-F/path/to/your/frameworks"
     79 export SDL2_LDFLAGS="-F/path/to/your/frameworks -framework SDL2"
     80 export SDL2_IMAGE_LDFLAGS="-framework SDL2_image"
     81 chicken-install sdl2
    6382
    6483== Usage and Examples
     
    6887
    6988<enscript highlight="scheme">
    70 (use (prefix sdl2-image img:))
     89(cond-expand
     90  (chicken-4 (use (prefix sdl2 "sdl2:")
     91                  (prefix sdl2-image "img:")))
     92  (chicken-5 (import (prefix sdl2 "sdl2:")
     93                     (prefix sdl2-image "img:"))))
     94
    7195(img:load "image.jpg")
    7296</enscript>
     
    78102== Version History
    79103
     104; 0.2.0 (2019-02-13) : Ported to be compatible with both CHICKEN 4 and CHICKEN 5. More user-friendly installation process.
    80105; 0.1.0 (2015-12-19) : Initial release.
    81106
     
    84109
    85110
    86 
    87111== API
    88112
     
    90114
    91115<enscript highlight="scheme">
    92 (use (prefix sdl2 sdl2:)
    93      (prefix sdl2-image img:)
    94      (only lolevel
    95            object-evict object-release))
     116(cond-expand
     117  (chicken-4 (use (prefix sdl2 "sdl2:")
     118                  (prefix sdl2-image "img:")
     119                  (only lolevel object-evict object-release)))
     120  (chicken-5 (import (prefix sdl2 "sdl2:")
     121                     (prefix sdl2-image "img:")
     122                     object-evict)))
    96123
    97124;; Load an image from a file.
     
    124151Until version 1.0.0 is released, the API is not guaranteed to be "stable".
    125152That means the maintainer reserves the right to change the API if needed,
    126 possibly in ways that break backwards compatibility with previous versions.
    127 '''Large backwards-incompatible changes are unlikely''',
     153possibly in ways that break backward compatibility with previous versions.
     154'''Large backward-incompatible changes are unlikely''',
    128155but there may be small tweaks and fixes to the API if problems are discovered.
    129156
    130 After version 1.0.0 is released, the API is guaranteed to remain stable (no backwards-incompatible changes)
     157After version 1.0.0 is released, the API is guaranteed to remain stable (no backward-incompatible changes)
    131158until the next new major version (e.g. going from version 1.x to 2.0.0, or 2.x to 3.0.0).
    132159
     
    154181need to be initialized.)
    155182
    156 Returns a list of symbols indicating all the image loaders that are
    157 now initialized, including any that were already initialized. You
    158 should check the return value to see whether all the image loaders you
     183Returns a list of symbols indicating all the image loaders that are now initialized.
     184You should check the return value to see whether all the image loaders you
    159185requested were actually initialized. If not, {{get-error}} from the
    160186sdl2 egg ''might'' return an error message explaining why the image
     
    181207* {{current-version}} returns the version of SDL_image that the sdl2-image egg is currently using.
    182208
    183 For example, the user may have compiled the sdl2-image egg with SDL_image 2.0.0, then later upgraded SDL_image to 2.1.0, but not yet recompiled the sdl2-image egg with the new version.
    184 In such a case, {{compiled-version}} would return {{(2 0 0)}}, and {{current-version}} would return {{(2 1 0)}}.
     209For example, the user may have compiled the sdl2-image egg with SDL_image 2.0.1, then later upgraded SDL_image to 2.0.2, but not yet recompiled the sdl2-image egg with the new version.
     210In such a case, {{compiled-version}} would return {{(2 0 1)}}, and {{current-version}} would return {{(2 0 2)}}.
    185211But, features from the new version would not be available until the user recompiles the sdl2-image egg.
    186212
Note: See TracChangeset for help on using the changeset viewer.