-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
7 changed files
with
388 additions
and
249 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,242 +1,8 @@ | ||
| Help for mksprite {Module_MajorVersion} | ||
| ====================== | ||
| MkSprite and SFMerge | ||
| ==================== | ||
|
|
||
| MkSprite - creates sprites from DrawFiles and Euclid files. | ||
| SFMerge - merge sprites from many sprite files into a new sprite file. | ||
|
|
||
| mksprite converts files into fairly optimal sprite files. The goal is to read | ||
| many types of files, but so far only Draw and Euclid files are supported. | ||
|
|
||
| mksprite -h prints a brief summary of options. | ||
|
|
||
| The syntax is *mksprite [options] <infile> [-o] <outfile> | ||
|
|
||
| <infile> is the name of the input file. | ||
| <outfile> is the name of the output sprite file. | ||
|
|
||
| Example: | ||
| *mksprite -f /mks_ctrl -b &dddddd -m 1 drawfile sprite | ||
|
|
||
| Converts "drawfile" into "sprite", using the options specified, and further | ||
| options read from the control file "/mks_ctrl". | ||
|
|
||
|
|
||
| Options | ||
| ======= | ||
|
|
||
| -a <accuracy> | ||
| Set colour matching accuracy in percent (default 8%). This is how far apart | ||
| colours can be, while still causing only one palette entry to be added. The | ||
| smaller the number, the closer the output colours are to the original, and the | ||
| larger the sprite (and palette) becomes. | ||
| The default 8% may seem like a considerable error, but it relies on the fact | ||
| that there are almost always palette entries left over when the essential ones | ||
| have been taken, and the largest errors will be removed using these remaining | ||
| ones. | ||
| 100% is the distance between black and white. In other words, if you set it | ||
| to 100%, all colours will be considered the same, and only one palette entry | ||
| will be generated (or rather two, since we don't have 0 bpp sprites). | ||
|
|
||
| -b <&rrggbb> | ||
| The background colour is white (&ffffff) by default. This is the colour of | ||
| the sprite before anything is drawn to it. So anything left over will remain | ||
| the background colour. | ||
| When generating sprites with masks, the background colour has another purpose. | ||
| It is a hint about which colour the sprite will be plotted on top of. At the | ||
| edges of the solid parts, the colours are shaded towards this background hint | ||
| before they become transparent. | ||
|
|
||
| -c <colours> | ||
| This forces the output sprite to have the given number of colours. In fact it | ||
| will be rounded up to the next possible pixel depth, i.e. 2, 4, 16 or 256 | ||
| colours. | ||
| Using this option will almost always either degrade the quality, or waste | ||
| space. It is used to ensure a certain output, e.g. if the sprite is going to | ||
| be plotted by some program that only supports 4 bpp. | ||
|
|
||
| -m <level> | ||
| This sets the transparency level. The default is 0, which means all possible | ||
| pixels are solid, so the output sprite never has a mask. If a mask is needed, | ||
| you need to use this option. | ||
| The level is the intensity required before pixels are considered solid. Note | ||
| that "intensity" does not mean brightness, or anything related to the colour. | ||
| It is an expression of how much of the pixel is covered by solid colour. | ||
| The useful range is 0 to 16. 0 makes all pixels solid. 16 gives high | ||
| transparency, meaning that a given pixel must be covered _entirely_ by solid | ||
| colour to show, otherwise it is deemed transparent. Anything over 16 gives | ||
| completely transparent sprites. 4 is a nice level if the background hint is | ||
| holoured. The lower you go, the more important the background hint becomes, | ||
| as many pixels on the edges will be very close to that colour. Setting a | ||
| high level of 16 makes the background hint irrelevant, since when the pixels | ||
| would have started to move towards the background colour, they immediately | ||
| become transparent instead. | ||
| If, for any reason, the sprite ends up without any transparent pixels, a mask | ||
| will not be included in the output sprite. | ||
| Note that the Euclid module doesn't support transparency, since it always | ||
| fills the background with a solid colour. | ||
|
|
||
| -mat <file> | ||
| Uses the given material definition file for rendering Euclid files. You don't | ||
| need to specify it, if you have a "matierials" file available through | ||
| File$Path. | ||
|
|
||
| -n <name> | ||
| This simply sets the name of the output sprite. If it isn't given, the name | ||
| will be the leafname of the input file. | ||
|
|
||
| -p <file> | ||
| This preloads the output palette from <file>. The number of palette entries | ||
| in the file then determines the number of colours in the output sprite, unless | ||
| -c <colours> is also given. The palette does not need to contain all the | ||
| colours, so you can force the use of only some of them, and let the rest be | ||
| calculated as normal. E.g. if the palette file has 5 colours, a 16 colour | ||
| sprite will be generated with the last 11 entries calculated. It is 16 because | ||
| that is the lowest number possible that can accomodate 5 entries. Use -c if | ||
| you want to force a specific number of colours. | ||
| Remember that -a defaults to 8. So even if you have supplied a palette with | ||
| exactly the right colours in, it might still select different ones unless | ||
| you say -a 0. | ||
|
|
||
| -s | ||
| This will cause the palette entries to be sorted by their absolute brightness. | ||
| If makes no visual difference whatsoever, but in some cases it makes the | ||
| output sprites easier to deal with. | ||
|
|
||
| -v | ||
| Prints information about what is happening. | ||
|
|
||
| -xeig <factor> | ||
| -yeig <factor> | ||
| This changes the XEig or YEig factors to something else than 1. It is mainly | ||
| used with "-yeig 2", to make sprites for mode 12. Values less than 0 or greater | ||
| than 3 becomes 0 and 3 respectively. | ||
|
|
||
| -xsize <os-units> | ||
| -ysize <os-units> | ||
| This ensures that the output sprite has the specified width and/or height. | ||
| The input graphic will then be scaled to fit the given dimensions, preserving | ||
| its aspect ratio. Valid values are from 1 and upwards. Note, that in the | ||
| current version, this only has any effect for drawfiles. | ||
|
|
||
|
|
||
| Special options | ||
| --------------- | ||
|
|
||
| The remaining options are special, because they can't be altered by a control | ||
| file. | ||
|
|
||
| -h | ||
| Prints the help text. | ||
|
|
||
| -depend <file> | ||
| Output a list of dependencies to <file>. This will be the input file, a | ||
| palette file if given, and the control file if the input file matches a line | ||
| in it. | ||
|
|
||
| -o <outfile> | ||
| Sets the output file name. It is optional if this filename is the last | ||
| argument given. | ||
|
|
||
| -f <file> | ||
| Sets a control file to use for further options. This is mainly used in | ||
| makefiles, because then you can define a single rule for converting draw | ||
| into sprite, but still have different options for some of the conversions. | ||
| This control file consists of a line per rule. One rule is a wildcard mask, | ||
| followed by tab(s) or space(s), then a set of options. If the input filename | ||
| is matched by the wildcard string, the options override the ones given in | ||
| the command. This can happen several times if more than one rule applies. | ||
|
|
||
| Example: | ||
|
|
||
| In the makefile, you have put: | ||
| .SUFFIXES: .spr .draw | ||
| .draw.spr:; mksprite -f draw.mks_ctrl -b &dddddd -o $@ $< | ||
|
|
||
| ...then a set of dependencies listing the sprites you want generated, e.g.: | ||
|
|
||
| !Sprites: spr.!amplayer spr.file_1ad \ | ||
| spr.small_1ad spr.ic_amplayer | ||
| sfmerge $@ $? | ||
|
|
||
| This means make will look in the the directory 'draw' for '!amplayer' etc., | ||
| and call mksprite to produce the sprites. Then it calls sfmerge to merge the | ||
| new ones into !Sprites. What's 'sfmerge' I hear you ask. That's another small | ||
| utility you should be able to get from the same place you got this. | ||
|
|
||
| All the sprites generated will have the grey background given in the command. | ||
| This is where the control file is useful, because you might want red background | ||
| and a sorted palette on one of them, and a mask on another, etc. | ||
|
|
||
| So in 'draw.mks_ctrl' you can list this: | ||
| *!amplayer -b &ff0000 -s | ||
| *ic_amplayer -m 4 | ||
|
|
||
| And you end up the the described behaviour. It's that simple. | ||
|
|
||
|
|
||
| Points to note | ||
| ============== | ||
|
|
||
| Switches behave is a slightly different way in control files; They are | ||
| replaced, rather than overridden. This means that if the command had -s on, | ||
| it will be turned off unless it's also present in the relevant control file. | ||
|
|
||
| The program relies on the DrawFile module to render the file properly. | ||
| Unfortunately this is not always the case. For example, if you use 16 colour | ||
| sprites in the drawfile, make sure they have a palette (otherwise the | ||
| colours will probably be wrong). | ||
|
|
||
| Note that it is currently a good idea to convert text strings in draw files | ||
| into paths. This is because DrawFile uses the VDU system to print them, | ||
| which makes the wimp think the screen might have been messed up (even though | ||
| output was switched to a sprite - but it doesn't check this). The upshot is | ||
| that you can get the "Press SPACE or click mouse to continue" message after | ||
| conversion, which isn't very helpful. Strangely, this doesn't always happen, | ||
| even when converting the same file over and over. One of life's mysteries. | ||
|
|
||
| Everything relies on the bounding box being correct, which isn't a problem | ||
| for files made by !Draw. But anything else (e.g. ArtWorks) might require | ||
| the file to take a trip through !Draw to fix the boxes, otherwise the size | ||
| may be slightly wrong. | ||
|
|
||
|
|
||
| Files in release | ||
| ---------------- | ||
|
|
||
| !Help This file. | ||
| Examples.draw A test draw file. | ||
| Examples.Materials Some materials for the Euclid module. | ||
| Examples.pan A test Euclid file. | ||
| Examples.test Obey file that attempts to convert draw and pan | ||
| into sprites. | ||
| ToSprite A GenCon plugin for FilerPro, adding an entry to | ||
| the Convert window for draw and euclid. To use, put | ||
| it in the directory | ||
| <Filer$Dir>.Utilities.GenCon.Functions. | ||
|
|
||
|
|
||
| How to make Euclid files | ||
| ======================== | ||
|
|
||
| Look at the example, "pan". Note the object called BBox, this is a special | ||
| mesh with 1 vane, that determines the size of the output. It doesn't need | ||
| to appear in the "$" scene, only the size of it is used. | ||
| There are 10 Euclid units per output pixel. In "pan", BBox goes from -70,-80 | ||
| to 80,70, i.e. it is 150 by 150. So the output sprite will be 15 by 15. | ||
|
|
||
| The viewpoint will be whereever "$.!Camera" is. | ||
|
|
||
| These Euclid files are not exactly obvious. It can be difficult to achieve | ||
| a certain colour, since it depends on a lot of things (object colour, lights, | ||
| material). !ArcLight is very handy for checking it. Note the horrible error | ||
| spreading it _insists_ on doing, is usually completely removed by the | ||
| supersampling in mksprite. | ||
|
|
||
|
|
||
| Contact | ||
| ======= | ||
|
|
||
| Questions, etc. should be addressed to: | ||
| Thomas Olsson | ||
| tolsson@armware.dk | ||
|
|
||
| New versions can be found at: | ||
| https://www.armpit.dk/files/ | ||
| The MkSprite and SFMerge tools were written by Thomas Olsson. | ||
| Individual Help files can be found in this directory. |
Oops, something went wrong.