;===============================================================================
; HermIRES 1.29 C64 hires-bitmap editor help
;===============================================================================
; 2014 Hermit Software Hungary (Mihaly Horvath)
;-------------------------------------------------------------------------------
Hello Sceners
I ended up writing this tool because I needed something that runs as well on
Linux just as on other OS supported by 'Allegro' library...
It's a cross-platform hires bitmap (Art Studio 1 format) editor for the C64,
and since v1.28 it's also capable to handle AFLI (Adanced-FLI 320x200 hires).
The format has some restrictions, here are the rules:
-the maximal resolution of the picture is 320x200
-only 16 fix C64 colours can be used (no gradient either)
-in a 8x8 pixel-block only 2 colours can used to be displayable by C64
(this is detected in HermIRES, but .hbm files can be saved with clashes too.)
*AFLI mode is less strict: every 8x1 pixel-block can have 2 colours, but
it has a disadvantage: the first 3 character columns (FLI-bug) has few
colours,
their background is 0xF everywhere, foreground is selectable for each
(Control+Click).
Displaying AFLI takes considerable CPU time so it's mainly for standalone
graphics...
-on a real C64 the PAL will blur the screen-content a bit, should check on CRT,
or at least VICE emulator's CRT simulation.
I hope you'll find this tool useful...
(You can see the new additions and plans at the bottom of this readme-file.)
1.Installation and compilation:
===============================
HermIRES can operate in 3 different fixed window sizes, and decides which can
be used on your monitor when it starts. The minimal resolution is 1024x768 to
see the GUI on the screen entirely.
The compiled program doesn't need installation, HermIRES.exe runs on Windows,
and HermIRES without extension runs on linux with X11 graphics.
I used static linking where it was possible to increase the portability of
these
standalone executable binaries.
However in case it isn't static, allegro runtime library is needed...
In the current build I compiled Windows executable dynamically, so it needs the
.dll called 'allegro-4.4.2-monolith-mt.dll'.
(In Ubuntu download 'liballegro-4.4' runtime library with Synaptic Package
Manager.)
If you want to recompile the HermIRES.cpp source-code, here are the steps:
a.compile on Linux:
-prerequisites: allegro 4.2 library (liballegro) with static linking support
and the usual C++ toolchain ('build-essential' .deb package)
-compilation steps: -'cd source' folder, in command-line type 'sh
compile.sh'
-or type 'make', then 'make install'
(the binary, menu entry and icon goes to system-folders)
b.compile on Windows (one way of it):
-prerequisites: DevCpp 4.9.9.2 or MinGW should be installed with the g++.exe
binaries
allegro-devpak (e.g. "allegro-4.4.2-1mpx.DevPak" but this
has no static-linking support)
(thes link seems right:
http://devpaks.org/details.php?devpak=340)
should be installed into DevCpp with its Packman.exe
-compilation steps: method1: Go to 'source' folder and run 'compile.bat' for
4.4.2 allegro devpak (program-icon works..)
method2: in DevCpp: open 'HermIRES.dev', and press F9 to
compile and run (program icon won't work..)
(method3: or for static build with allegro 4.2: 'cd
source' folder, and run 'compile-devpak42.bat'))
-then if needed, set shortcut-icon and '.hbm'
file-association (no installer made yet)
*there's a file called 'bmpexe.asm' too, but it's not needed to compile it,
because its compiled binary is included in HermIRES.cpp source-file.
(btw. to compile 'bmpexe.asm' you need '64tass' compiler)
2. Overview of the GUI:
=======================
The simple GUI might be straightforward at 1st glance, but let's describe the
main parts:
-At the top you see the magnifiable picture editor, you work here actually.
-At the bottom-left side you can see the preview of the
whole/half/third/quarter picture.
-Right to the preview it's the Toolbar, where drawing modes can be selected.
-Right below the picture-editor it's the palette with the usable C64 colours.
-Then some information-only fields: the used colours, cursor-positions, zoom,
etc.
-And of course the Menu Buttons where you can set parameters and load/save
pictures.
A.The main picture-editor window (Grid):
----------------------------------------
You can use your mouse here for most of the operations:
-draw dots with diameter - left button for Colour 1, right button for Colour 2
-draw shapes - holding down the left/right button defines start-/endpoints
- you can draw lines, circles and rectangles (empty or filled)
*every shape is painted with the selected plot-parameters (see under
'ToolBar')
-zoom in/out (around the pixel under mouse-cursor) with middle mouse-wheel
-move in the zoomed picture by holding down the middle mouse-button
-you can pick a pixel's color by 'TAB' key, or holding down 'Shift' and
pressing mouse left/right button
-you can set a colour in the 8x8 block by holding down 'Control' key and
clicking on a pixel to change colour of
*In AFLI-mode's FLI-bug area this changes the AFLI-bug column's drawing colour
which the mouse is over
B.The Palette:
--------------
-Drawing Colour 1 can be selected by clicking left mouse-button or hexa keys
1..F
-Drawing Colour 2 can be selected by clicking right mouse-button or SHIFT +
keys 1..F
-Border-Colour can be selected by clicking middle mouse-button on the colours
(Border colour refers to the C64 border colours, and is displayed around the
picture.)
-Colour-Change for current Drawing Colour1 on the entire screen can be changed
while holding CONTROL-key down and clicking left mouse-button or pressing
keys 1..F
-Colour 1 and 2 can be exchanged with 'tilde' (with signal: '`' or '~') button
*Note: In AFLI-mode FLI-bug area colour 'F' deletes, every other colours put
pixel in the defined FLI-bug colours.
C.The Preview:
--------------
-Clicking into the picture with left mouse-button can move the zoom-rectangle
to different areas
(Zoom-rectangle shows which part of the picture is zoomed in the grid. If no
zooming it disappears.)
-Normal, 2x, 3x, 4x zooming modes can be selected by the mouse's scroll-wheel
-Saving the Preview as .png picture can be initiated by right mouse-button
*in preview-zooming mode the preview follows the mouse-corsur on the main
screen
D.The Toolbar
-------------
a. Selection: -When this mode selected, you can select a region with left
mouse-button
held down in the main picture-editor window. After releasing
the button
the selection gets copied to the clipboard.
-If the selection goes into down-right direction, simple
copying happens.
-In down-left direction the copied content is mirrored
horizontally.
-In up-right directoin the copied content is mirrored
vertically
-In up-left direction the content is mirrored vertically &
horizontally
-If you pressed Shift during selection, the content even gets
cut from its original place
-Then you can paste the clipboard content with the right
mouse-button
to a position. Holding down the right mouse-button you can
drag&move the content.
If you pressed Shift during right-clicking, the original
selection gets cut ('moving')
*If you pressed the right mouse-button inside the selection, the moving will
happen relative to
the selection's position. If you pressed it outside the selection, the
'paste' operation will
happen exatly from mouse-position downwards.
b. Dithering: -With left mouse-button 3 options are selectable:
no dithering / even dithering / odd dithering
-With right mouse-button you can select 2 dithering modes:
dith-drawing with only one colour / dithering Colour 1 &
Colour 2
c. Dot/Diameter: -1st press selects dot/pixel drawing mode,
2nd click: -left mouse-button: increases dot-diameter
-right mouse-button: decreases dot-diameter
d. Line: -Clicking on it with left mouse-button select line-drawing mode
Lines can be started in the editor-window by pressing and
holding down
left/right mouse-button (Colour1/2), releasing it sets the end
of the line.
e. Rectangle: -1st clicking on it with left mouse-button selects
rectangle-mode
-when the mode is selected, it toggles empty/filled rectangle
mode
f. Circle: -Works the same as the Rectangle button but for Circle-drawing
g. Flood Fill: -Simple colour flood-fill - left-button: Colour1, right-button:
Colour2
h. Undo/Redo: -Left mouse-button: Undo the latest 255 operations
(you can see the step-counter under the button which shows how
much steps you made and can step back)
-Right mouse-button: Redo the latest Undo-ed operations
i. Brightness -this knob can be used to adjust the brightness to see the
picture better...
(If it's not middle-position it can cause slow-downs in systems
with poor graphic-card)
j. CRT-smooth -this slider sets how much the CRT emulation should
blur/smoothen the picture
*Dot/Line/Rectangle/Circle all consists of dots with the adjusted diameter &
dithering.
*Therefore they might take some time to be fully drawn, the progresses appear
in the right-bottom corner of the grid
E.The Menu-Buttons:
-------------------
'CRT emul.' Sets CRT (PAL TV picture) emulation mode ON/OFF for the
Preview or the Grid, or both
(The Grid's CRT emulation is automatically switched off above
a certain magnification.)
'Grid' Sets grid OFF or to modes: Grid around all pixels / grid only
around 8x8 pixel-blocks
'AFLI' Toggles AFLI mode. In this format every valid 8x1 pixel-slice
can contain 2 colours without 'clash'
'TestClash' Selects C64-limitation-aware modes for 8x8 pixelblock
colour-clash testing:
OFF - no checking at all
TEST - Where there are more than 2 colours in a 8x8 block it
blinks. (in Win7 sometimes too fast)
DENY - Doesn't allow to put pixel into a 8x8 which is already
full (has 2 colours)
REUSE- If the 8x8 block is full, painting its existing colours
depending on left/right mouse-button.
(If it's not full, the selected colour is painted
normally.)
SET - If the 8x8 pixelblock is full, its colour will be set
to the selected drawing colour
(Will set the colour which is under the mouse-pointer
in the block.)
*The 'TestClash' setting has effect on all of the drawing modes, even
copy-paste and file-importing.
*The previous three buttons can change backwards too, by clicking on
them with right mouse-button or holding down Shift
'BrightGrid' Toggles compensation for the darkening effect of the grid
ON/OFF.
(Useful for darker pictures, less useful for lighter pictures
containing white.)
'Load Picture' Brings the File Dialog where you can load 5 picture-formats
(detected by extension).
1.".hbm" - custom compressed format including bitmap and
border-colour
2.".bmp" or ".png" - import PC picture formats. When
loading/importing these,
the closest maching C64 colours are found. Only the
first (top-left) 320x200 pixels are taken from the
.bmp/.png picture.
The import will depend on the selected format
(bitmap/AFLI), palette, and the Clash-test settings
3.".prg" - "Art Studio 1"-like hires picture format -
load-address: $2000
bitmap:$2000...$3f40, colours: $3f40...$4327,
border-colour: $4328
"AFLI" hires picture format - load-address: $4000
bitmap:$4000...$5f40, FLI-bug underlay-sprite
1..3: $5f40...$5fff
eight colour-memories & FLIbug-sprite pointers:
$6000..$8000,
border-colour: $7FE8, FLI-bug underlay-sprite
colour 1..3: $7FE9,$7FEA,$7FEB
4.".prg" - Executable C64 file which was saved by HermIRES
previosly. (See 'Save'.)
'Load Palette' You can load custom palettes in .vpl format. (the default is
'Pepto')
(The .bmp importer will also use the loaded palette as
colour-reference)
'Save Picture' The picture can be saved as ".hbm" format, the
HermIRES-specific format
'Clear Picture' Clears the whole screen with Drawing Colour 2.
'Export C64prg' Saves the picture in the above mentioned (3.) ArtStudio-like
picture-format.
(Or AFLI format if AFLI-mode is selected by 'AFLI' button.)
'Export C64exe' Saves a C64 executable .prg file which appends the title too
in the lower border.
(It asks for a title which will be displayed as caption under
the exported picture.
If you delete this name entirely, no title will be displayed,
only the pure borders around the picture.)
'Help': A very short help/cheatsheet with the most essential keys.
'Quit': Exits, but first asks for confirmation....
*You may notice allegro's file-dialog a bit strange. Most of the time it works
better for me with cursor keys, but mouse should be in the field as I
suspect.
(In Allegro5 there's native file-dialog support, but I haven't tried that
yet.)
3.Summary of keyboard-shortcuts:
================================
Colour selection:
-----------------
0..9..F .... Select Drawing Colour 1
Shift + 0..F . Select Drawing Colour 2
Control + 0..F . (except Control+"C") Change the current Colour 1 on the entire
picture
Alt + 0..F . Select Border-colour
TAB .... Pick Drawing Colour 1 from pixel under the mouse-cursor
Tilde (` or ~) . Exchange Colour 1 and 2
Drawing modes:
--------------
F1...F4 .... Select pixelling (pen) mode - with four different pen/dot
diameters
[ ] .... Decrease / Increase dot diameter
F5...F8 .... Select drawing mode: line / rectangle / circle / fill
F9 , F10 .... Select Dithering mode / toggle 2-colour dithering
F11 .... Select 'selection & copy/paste' mode (occipied in some OS for
'full-screen')
Navigation/zoom:
----------------
Left/Right .... Go one 8x8 pixel-block to the left/right
Up/Down ...... Go one 8x8 pixel-block up/down
Home/End ...... Go to the top/bottom of the zoomed screen
PageUp/Dn ..... Go to the left/right edge of the zoomed screen
+ / - ...... Increase/Decrease zooming around the mouse-pointer
SPACE ...... Toggle 32x zoom to the pixel under the mouse-cursor
Shift+Space.... Toggle 16x zoom to the pixel under the mouse-cursor
Region Selection:
-----------------
Control+Cursor . Fine-adjust the starting point of the selection
Alt+Cursor key . Fine-adjust the ending point of the selection
Alt+Home/End ... Escalate the selection till the left/right side of the screen
Alt+PgUp/PgDn .. Escalate the selection till the top/bottom of the screen
Manipulation:
-------------
Del / Backspace Delete the current 8x8 pixel-block to Colour 2
Shift+Del ..... Delete the current 8x8 pixel-block to Colour 1
Control+C ..... Copy current character (8x8 pixelblock) under mouse-cursor to
buffer
(Or copy selection to clipboard if we are in 'Selection' mode)
Control+V ..... Paste character from character-buffer to cursor-position
Control+X ..... Cut and Copy current character (8x8 pixelblock) under
mouse-cursor to buffer
Control+Z ..... Undo last operation (255 steps max.)
Control+Y ..... (or Shift+Control+Z) Redo the last Undo-ed operation (16 steps
max.)
Menu/File:
----------
G ...... Grid display On/OFF
T ...... Colour-Clash Testing ON/OFF
R ...... CRT emulation ON/OFF
L ...... Load .hbm/.prg/.bmp - file dialog
S ...... Save as .hbm - file dialog
Shift+S ...... Save the Preview as .png picture file
P ...... Load Palette
H ...... Short help/cheatsheet
Q / Esc ...... Quit the program
;===============================================================================
added in 1.1:
-more Undo/Redo steps than 16 (Flea asked) - now 255 steps (and memory usage
grown to 26M)
-colour picker (pressing TAB, or l/r mouse-buttons with Shift)
-loadable .vpl palette (might be saved with configuration / .hbm file's end)
-settings and paths/filenames are saved to config-file now
(grid/testclash/gridbright/palette/etc)
*32 bit linux version beside 64bit version (set up a 32bit Lubuntu system for
that)
-grid more intelligent - in lower magnifications only 8x8 grids show up
*possible to change colours in a 8x8 block with control+mousebutton - with
Control+Mouse-button
-blinking selection rectangle and line/shape previews..
added in 1.2:
-program-icon for windows (it can't handle the included .xpm array)
-load/import/export in PNG format too (saving now happens in png format thanks
to AllegroPNG 1.3
-display opened filename and palette-name
-possibility to change border-colour by keys too with 'ALT' + 0..F colour keys
-improved selection: fine modification possible afterwards with Ctrl / Alt +
cursor keys
-[ and ] keys for pen-diameter decrease/increase
-key-bindings F1..F4 now for pen/brush (draw) (no good key was found on left
on left-hand side for "fill")
-Undo/Redo key is repetitive if pressed long (workaround for no allegro
key-repeat in Windows)
-100Hz mouse-polling timer -> possibly smoother mouse-drawing
-PAL CRT emulation of preview and editor screen (when no small grid
displayed)...
-last used file is opened at startup if it can be found
-3x zooming mode for preview as well, preview-zoom can be set by scroll-wheel
too
-sliders for PAL-blur (sharpness) and brightness with reset buttons
*resolution is auto-detected and GUI adjusted for it
*cut©&move function (whith Shift pressed while selecting with left
mouse-button / while pasting with right)
added in 1.25:
-color swapping fast-button - Tilde "`" button (BitBreaker's idea)
-show pen-diameter preview circle if diameter is bigger than the default
*dense (pixel-scale) grid toggleable (in bigger magnifications too).
*added 'Deny painting','Reuse existing colour' and 'Set block colour' mode to
ClashTest - different settings on/off in case clash would happen...
*showing zoomed area in the preview, allow going to area in zoomed mode when
left-clicking on preview
-showing ongoing progresses by text/graphics (loading/converting/drawing...)
-selectable CRT emulation for Preview/Grid only... (for faster operation on slow
machines)
-undo step number displayed (should undo history also be saved?)
added in 1.28:
-AFLI-mode: grid & clash-test & import/export
-added 'older-vice.vpl' palette... (for e.g. 'Plague Dogs' screenshot made from
an older Vice)
added in 1.29:
-if drawing color 1/2 is the same as foreground/background colour, allow to
paint the opposite colour in REUSE mode with the other mouse-button
fixed in 1.1:
-cleaned source file from obsolete comments
-pixel coordinates were displayed when not in drawing area
-ctrl+B was binded twice :O - used Shift+S instead
-corrected colour-mismatches of the examples
*pasting sluggishness on windows (used DrawGrid+blitter instead of direct
'screen', optimized code)
-changed text-background to less eye-catcher blue/purple, as noticed by Flea
-normal faster filled circle and rectangle drawing when no dithering mode or
diameter set
fixed in 1.2:
-HermIRES.cfg is now always saved into the program's folder, and saved when
closing with X or Alt+F4 as well...
-button sluggishness - solved by replacing key-funcions' D_O_K returns with
(D_REDRAWME | D_WANTFOCUS)
-colorize palette-buttons when new .vpl palette is selected
-'Delete / change-color / paste 8x8 pixel block' creates only the required
undo-steps now
-(where only 1 colour in a 8x8 pixel-block and it matches the first (x=0,y=0)
pixel, setting the char. to 0)
-keys are not repeated in Windows - coded custom repeat handler for
toolbar-buttons
-(control+C is binded twice...but leaving it like this as it's more important
than colour-change key-shortcut)
*'pencil' drawing was aggregated sometimes -solution: update TempPosX2 and
TempPosY2 before drawing (which can overlive timer)
-moving in zoomed picture was slow - solution is same as the previous - updatind
positions BEFORE CPU intensive drawing
fixed in 1.25:
-control/shift/alt stucked in Win7 with allegro devpak 4.2... -> using allegro
devpak 4.4.2 version instead!
-reduced overall CPU usage (my machine:~5% when no mouse touched,~25% when grid
moved) - refined timed and pixelling/detection events
-in Windows it was slow (especially in CRT emulation) -> wrote optimized
software CRT-emul.pixelling for GridDrawer, not relying on hw-acceleration
*pressing F1..F4 fucked up (enlightens) toolbar sometimes - solution: timing
stabilizer / thread safety check solved it
-Preview-zoom title-text was overwritten by Grid-Zoom-text in the smallest
resolution mode with 2-digit magnifications
*there was 'allegro error #11' and 'segmentation fault' at lower than required
resolution - it was logical mistake in resolution-decider loop
-made dithered and big-pendiameter filled rectangle/circle drawing faster (set
the steps according to pen-diameter)
*allegro filename-extension detection was wrong - if '.' used in filename and no
extension given, only the name before was saved to disk! -> used ustrcmp &
strcat
*C64-executable format name-tag (caption) now editable (deleting it disables it)
fixed in 1.26:
-pen-shapes are symmetric again. -> solution: 2.23*radius as diameter and 80 as
angle-steps
-pen-preview is more accurate now -> solution: typing some '-1' in PenPreview
function
-0 sized filled rectangle with dither freezed the app -> solution: when start
and end X or Y is equal, only drawing line...
-taking tasbar size (30 pixel high) into the resolution-decider equation - more
probable for GUI to fit into the screen comfortably
-windows - now the program Icon appears again in taskbar and window-title ->
with the new compile.bat (not from DevCpp with Makefile.win)
fixed in 1.28:
-gave 45 pixel taskbar-height for GUI-size auto-detector (more tolerance)
-LoadVPL() is now before LoadFile() in 'main' (by commandline-argument or from
config-setting) so opening .png/.bmp at startup is converted correctly with the
latest palette
-Caption name now doesn't contain the extra letter at the end (string-delimiter
0 was put in wrong place by loop)
fixed in 1.29
-AFLI caption can be fully disabled (AFLIexe-patch included along with
bin2array.exe)
================================================================================
to work-around:
---------------
-dialogs take a lot of CPU (allegro's issue) - (started to create custom dialog,
or may use native gtk.h/windows.h file-dialogs instead)
-Windows7: theme is changed to 'Aero default' without alpha channel (24bit) +
Windows7 display-timing issues in clash 'TEST' mode...
-Bitbreaker reported issue with 24 bit .bmp, program exits with segmentation
fault!, yet another bmp got skewed...this is Allegro-issue, but PNG import
should work...
-OSX port is not stable, key-callbacks cause freeze -> must handle the keys from
the timed function in lower level... then OSX port would be possible
--------------------------------------------------------------------------------
may add later:
-------------
-setting window/GUI Size with a button during operation
-a proper .deb for Ubuntu, .dmg for OSX, and win.installer ...with dependency
check & file-associations
-cursor-key/numpad key based drawing (if the keys could be repeated on
Windows...or make own keyhandler)
*possibility to select/stretch bmp when being imported... (so no other graphic
tool need for that)
-bigger built-in help (in a textbox preferably)
-(maybe sprite-overlay / nufli-export support, (maybe support for sprites in
borders...)
-dithering in bmp-importer (like e.g. in Project one...)
-'continuous lines' drawing mode
-possibility to set size (dimensions) of export to hires (like png2hires.py
does)
-("select colours to be transparent" function for the 'paste' function (kinda
'brush') )
-(bring 'SPRedit' mode/functionality into HermIRES (with namespaces for
different parts))
-(.asm/.inc export to be included in programs directly?)
-(angle-based rotation?)
;===============================================================================
|
aminet net>