Editing GimConv


=Description=
'''G'''raphic '''I'''mage '''M'''...? ([[Multimedia_Formats_and_Tools#GIM|GIM]]) is some kind of container intended to store images, it allows for tenths of different storage settings and by combining settings results in hundreds (or thousands) of different GIM formats, the amount of GIM formats used in PlayStation consoles is limited though (restricted by the graphic enviroment, libraries, etc...). GIM files was found used in PSP and PS3 firmwares inside [[Resource Container (RCO)]] files, [[PlayStation 3 Theme (P3T)]] files, etc...

*GimConv.exe versions:
**'''1.20e''' (GIM files made around 2006 and still present in PS3 4.82 firmware)
**'''1.20h''' released with '''p3tcompiler v2.00''' as part of the [http://uk.playstation.com/ps3/support/settings/detail/linked235336/item85346/Download-PlayStation-3-Custom-Theme-Guidelines/ PS3 Custom Theme Toolbox] (this is the version included in rcomage using a modifyed GimConv.cfg)

*Other notes:
**GIM images can be previewed in PC by using '''Gim Viewer''' (unnofficial app made by hsreina, it has limited support for the "rgba based" GIM formats). See [[Multimedia_Formats_and_Tools#GIM | Multimedia Formats and Tools]]
**The option '''-viewer''' (start gimview.exe when process ends) in the official config file (that was removed for rcomage) is intended to launch an official '''gimview.exe''' that doesnt exists in the public release
**[http://us.playstation.com/support/manuals/psp/pspguides/ PSP Custom Theme Toolbox] admits GIM files as inputs, but doesnt includes a GIM converter
**Some of the settings (such '''merge_mode''') are related with animated images but the support of animated GIM images on PlayStation consoles is unknown, see: http://endlessparadigm.com/forum/showthread.php?tid=5054
**It supports AVI video as input, probably to convert the video frames to static images and build a GIM animation with them, unknown usage
**Gimconv.exe supports an internal script format to automatize image conversions, it can be seen how appears as an option available at bottom of Gimconv.cfg and allows to create GIM-to-GIS conversions. The usage of this scripting features is mostly unknown

=GimConv.exe usage=
Before explaining how works GimConv.exe is needed an introductory explain about how it works GimConv.cfg (the settings file)

GimConv.cfg is divided in sections and is loaded "from top to bottom", at top are the "default settings" where are given a default value, if a setting is repeated below the new value overrides the default. After the "default settings" appears the "options" that defines a group of settings, and this settings inside options overrides the defaults settings at top

==GimConv.exe help screen==
The command line help screen of GimConv.exe displays a very limited list of predefined options with an small explain for them, the example below belongs to the official GimConv.cfg and shows the options sony considered was useful for them

{{Keyboard|content='''C:\PS3_Custom_Theme_v200\GimConv>GimConv.exe'''
gimconv ver 1.20h --- generic picture converter
 Copyright (C) 2006 Sony Computer Entertainment Inc.
  All Rights Reserved.

usage:
        gimconv <input files> [options]

options:
        -interact       input additional options
        -pictures       merge files as pictures
        -frames         merge files as frames
        -levels         merge files as levels
        -prompt         prompt always
        -warning        prompt on warning
        -error          prompt on error
        -viewer         start gimview.exe when process ends
        -o <filename>   specify output file name
        -s <w,h>        resize image data
        -S              output text format
        -P              resize image data to a power of two
        -N              output in normal pixel storage format
        -F              output in faster pixel storage format
        -R              re-convert ( don't swap RGBA <-> ABGR )
}}

==GimConv.exe usage with options==
For GIM-to-PNG conversions is not needed to use special options:
{{Keyboard|content='''gimconv.exe in.gim -o out.png'''}}

If you create a GIM without using special options it will use the "default settings" of GimConv.cfg "from top to bottom", you can achieve that by doing this:
{{Keyboard|content='''gimconv.exe in.png -o out.gim'''}}

Additionally to the options that appears on the help screen there are a lot more special options inside GimConv.cfg, all them can be used in the same way, actually the help screen is just informative and the options that appears in it are not much useful for us

To specify an option is needed to use the name of the '''-option''' at the end of the line. At the time GimConv.exe of processes this command it loads the settings of GimConv.cfg file "from top to bottom" (so it starts loading the default settings) and then it loads the option we have choosen (and the option contains settings that overrides the defaults)
{{Keyboard|content='''gimconv.exe in.gim -o out.gis -S'''}}
{{Boxcode|content=<syntaxhighlight lang="c">
option -S {
	output_object = off
	output_script = on
}
</syntaxhighlight>}}
If you look at GimConv.cfg "from top to bottom" you are going to find the settings '''output_object''' with value '''on''' and '''output_script''' with value '''off''' at top as default settings (by default it outputs a GIM and doesnt outputs a GIS). What the option '''-S''' is doing is to "switch" them (doesnt outputs a GIM but it outpputs a GIS)

==GimConv.exe usage with explicit settings==
This is the most accurate way to have full controll of the settings, if you are picky enought you can write a long line of settings to be sure you are overriding all the defaults (just incase the GimConv.cfg has been modifyed by someone, by doing this you are overriding his/her changes made to default settings). If you are writing an script or any tool that sends actions to gimconv.exe you should use this method
{{Keyboard|content='''gimconv.exe test.png -o test.gim --format_style psp --format_endian big --pixel_order normal'''}}
*Note the 3 options used in the example are overriding the default settings at top of GimConv.cfg (this is an example of the official GimConv.cfg, the one used inside rcomage is different):
{{Boxcode|content=<syntaxhighlight lang="c">
//----------------------------------------------------------------
//  default settings
//----------------------------------------------------------------
	pixel_order = default		// default normal faster
	format_style = psp		// std psp ps3
	format_endian = little		// little big
</syntaxhighlight>}}

==GimConv.exe usage driven by rcomage==
{{Boxwarning1|content='''Dont use this method for PS3'''. GIM files inside RCO files from PS3 firmware uses variated formats, this method applyes the same settings for all them and breaks some}}
This works by sending GIM settings from rcomage.exe to gimconv.exe and is made at the time rcomage.exe is compiling the RCO (see the "compile" help in [[rcomage]] page)

There are 2 options in rcomage specific for this task, named: '''--gimconv-cmd''' and '''--gimconv-flags'''
{{Keyboard|content='''rcomage.exe compile test.xml test.rco --gimconv-cmd ".\gimconv\gimconv.exe" --gimconv-flags "--format_style psp --format_endian big --pixel_order normal"'''}}

=GimConv.cfg=
This is the configuration file that defines the help screen, and contains the default values and all available options. The next example is the configuration file provided by sony as part of the [http://uk.playstation.com/ps3/support/settings/detail/linked235336/item85346/Download-PlayStation-3-Custom-Theme-Guidelines/ PS3 Custom Theme Toolbox]
<div style="height:520px; overflow:auto">
{{Boxcode|content=<syntaxhighlight lang="c">
//================================================================
//  gimconv configuration
//================================================================

usage {
	puts "usage:"
	puts "        gimconv <input files> [options]"
	puts ""
	puts "options:"
	puts "        -interact       input additional options"
	puts "        -pictures       merge files as pictures"
	puts "        -frames         merge files as frames"
	puts "        -levels         merge files as levels"
	puts "        -prompt         prompt always"
	puts "        -warning        prompt on warning"
	puts "        -error          prompt on error"
	puts "        -viewer         start gimview.exe when process ends"
	puts "        -o <filename>   specify output file name"
	puts "        -s <w,h>        resize image data"
	puts "        -S              output text format"
	puts "        -P              resize image data to a power of two"
	puts "        -N              output in normal pixel storage format"
	puts "        -F              output in faster pixel storage format"
	puts "        -R              re-convert ( don't swap RGBA <-> ABGR )"
}

//----------------------------------------------------------------
//  default settings
//----------------------------------------------------------------

default {
	load "lib/*"

	//  main control

	interact_mode = off		// off on ctrl
	merge_mode = off		// off picture frame level plane
					// image palette sequence
	prompt_mode = off		// off on warning error
	output_object = on		// off on
	output_script = off		// off on
	output_directory = auto		// current input auto
	output_filename = ""
	object_extension = .gim
	script_extension = .gis
	userdata_extension = .dat
	glob_extension = .dds .tm2 .tga .bmp .avi
	object_viewer = ""

	//  process control

	filter_script = "Filter"
	image_size = default		// default pow2 $w,$h
	pixel_order = default		// default normal faster
	pixel_alpha = default		// default $alpha
	pixel_channel = default		// default rgba rgab ragb ... etc
	image_format = default		// default rgba8888 rgba4444 rgba5551 rgba5650
					// index4 index8 index16 index32
					// dxt1 dxt3 dxt5 dxt1ext dxt3ext dxt5ext
	palette_format = default	// default rgba8888 rgba4444 rgba5551 rgba5650
	update_userdata = default	// default off on
	update_fileinfo = off		// default off on

	check_limit = on		// off on
	limit_image_width = 4096	// off $count
	limit_image_height = 4096	// off $count
	limit_level_count = 8		// off $count
	limit_frame_count = off		// off $count

	//  output control

	format_style = psp		// std psp ps3
	format_endian = little		// little big

	output_image = on		// off on
	output_palette = on		// off on
	output_sequence = on		// off on

	//  PS3 OSD default settings

	format_endian = big		// -B
	pixel_order = normal		// -N
	pixel_channel = default		// -R
	image_format = rgba8888		// --image_format rgba8888

	extend_edge = off
}

//--------------------------------------------------------
//  format specific
//--------------------------------------------------------

input *.avi {
	pixel_alpha = 255
}

input *.bmp {
	pixel_alpha = 255
}

input *.dds {
}

input *.tga {
}

input *.tm2 {
}

input *.gim {
}

input *.gis {
}

//--------------------------------------------------------
//  mode option
//--------------------------------------------------------

option -interact {
	interact_mode = on
}

option -pictures {
	merge_mode = picture
}

option -frames {
	merge_mode = frame
}

option -levels {
	merge_mode = level
}

option -planes {
	merge_mode = plane
}

option -images {
	merge_mode = image
}

option -palettes {
	merge_mode = palette
}

option -sequences {
	merge_mode = sequence
}

option -prompt {
	prompt_mode = on
}

option -warning {
	prompt_mode = warning
}

option -error {
	prompt_mode = error
}

option -viewer {
	object_viewer = "GimView.exe"
}

//--------------------------------------------------------
//  process option
//--------------------------------------------------------

option -o %filename {
	output_filename = %filename
}

option -s %size {
	image_size = %size
}

option -g %ext {
	glob_extension = %ext
}

option -P {
	image_size = pow2
}

option -N {
	pixel_order = normal
}

option -F {
	pixel_order = faster
}

//--------------------------------------------------------
//  PS3 OSD specific options
//--------------------------------------------------------

option -B {
	format_endian = big
}

option -X {
	pixel_channel = abgr
}

option -R {
	pixel_channel = default
}

option -DXT {
	pixel_order = default
	pixel_channel = default
	image_format = default
}

option -E {
	extend_edge = on
}

//--------------------------------------------------------
//  output option
//--------------------------------------------------------

option -S {
	output_object = off
	output_script = on
}

//--------------------------------------------------------
//  filter script
//--------------------------------------------------------

script Filter %target {
	RescaleImage   %target $image_size
	SetPixelFormat %target $image_format $palette_format
	SetPixelAlpha  %target $pixel_alpha
	SwapPixelChannel %target $pixel_channel
	ConfigureImage %target order $pixel_order
	UpdateUserData %target $update_userdata
	UpdateFileInfo %target $update_fileinfo
	ExtendEdge     %target $extend_edge
	CheckPSP       %target $check_limit
}
</syntaxhighlight>}}
</div>

Note there are some modifications made officially by sony at a later version because GimComv was initially made for PSP (those initial GimComv versions compatibles with "PSP only" probably didnt had this PS3 specific settings), but this public release of GimConv was released as part of a toolkit to build PS3 themes so it has some settings specific for PS3

This group at top on the config file are default settings (for PS3) that overrides other default settings of an older version of GimComv (for PSP). They are overwriting default values because the same option is specifyed before in the file, so the last one overrrides the previous one with the same name (and also was added a new option named '''extend_edge''' that should be PS3 specific)
{{Boxcode|content=<syntaxhighlight lang="c">
//----------------------------------------------------------------
//  default settings
//----------------------------------------------------------------

	//  PS3 OSD default settings

	format_endian = big		// -B
	pixel_order = normal		// -N
	pixel_channel = default		// -R
	image_format = rgba8888		// --image_format rgba8888

	extend_edge = off
</syntaxhighlight>}}

This other group seems to be options for GIM formats used in PS3
{{Boxcode|content=<syntaxhighlight lang="c">
//--------------------------------------------------------
//  PS3 OSD specific options
//--------------------------------------------------------

option -B {
	format_endian = big
}

option -X {
	pixel_channel = abgr
}

option -R {
	pixel_channel = default
}

option -DXT {
	pixel_order = default
	pixel_channel = default
	image_format = default
}

option -E {
	extend_edge = on
}
</syntaxhighlight>}}

==Custom configurations==
The configuration file allows to modify the ''help'' screen of the command line by adding custom labels, or by removing useless options to make room for more custom labels, this labels can be composed of groups of options, there is no need at all to do this because doesnt really enables any new funcionallity as you can specify all the options you need one by one from command line included the hability to override default values, but is good to keep a record of the most common used formats for a console by using custom labels with intuitive names that defines the GIM format

The config file supplyed by [[Rcomage]] contains some custom options for the formats that are used in PSP, some changes in the default settings that was common for PSP (included a size limit that breaks compatibility with PS3), and a group of options was added for PS3 (labeled '''-ps3''') but this group seems to use wrong options. For more info about the modifications made in the config file supplyed with [[rcomage]] see the differences in the {{talk}} page

This wiki section proposes new groups of options with new label names (to be able to use a new modifyed config file without breaking the compatibility of other tools that uses rcomage as a dependency)

*Inside [[explore_plugin]]_full.rco from firmware 4.70 there are 245 images, 201 of them (included the new icon tex_psn.gim) has been made by using this options:
{{Boxcode|content=<syntaxhighlight lang="c">
option -ps3bpp32 {
	format_style = psp
	format_endian = big
	pixel_order = normal
	pixel_alpha = default
	pixel_channel = default
	image_format = rgba8888
	limit_image_width = 4096
	limit_image_height = 4096
}
</syntaxhighlight>}}

*Inside [[explore_plugin]]_full.rco from firmware 4.70 there are 245 images, 14 of them has been made by using this options:
{{Boxcode|content=<syntaxhighlight lang="c">
option -ps3dxt5 {
	format_style = psp
	format_endian = big
	pixel_order = default
	pixel_alpha = default
	pixel_channel = default
	image_format = dxt5
	limit_image_width = 4096
	limit_image_height = 4096
}
</syntaxhighlight>}}

===Variants===
This is just a variant shown here for curiosity sake, because this is what sony did exactly for some (old) GIM files that are still present in modern PS3 firmwares, it seems never was updated, the only difference with what is written above is i added the option '''update_fileinfo''' that adds a footer at the botom of the GIM files. In this footer you can see the name of the user account of the microsoft windows OS where the GIM was created (funny stuff), a timestamp (usually around 2006), the original file name and format (usually a TGA with weird names), etc... To make a custom RCO you dont need to add this footer (so dont create GIM files with this option), if you do open the GIM file in a hexeditor and look at the footer how it was added info from your PC

*Inside [[explore_plugin]]_full.rco from firmware 4.70 there are 245 images, 30 of them has been made by using this options:
{{Boxcode|content=<syntaxhighlight lang="c">
option -ps3old {
	format_style = psp
	format_endian = big
	pixel_order = normal
	pixel_alpha = default
	pixel_channel = default
	image_format = rgba8888
	limit_image_width = 4096
	limit_image_height = 4096
	update_fileinfo = on
}
</syntaxhighlight>}}

=How to identify GIM settings=

*GIM--->GIM method (prefered)
**Use gimconv with .gim files as input and output (this preserves dxt pixel info, because dxt images doesnt suffers a conversion)
{{Keyboard|content='''gimconv.exe test.gim -o test.gim --format_style psp --format_endian big --image_format dxt5 --pixel_channel default --pixel_alpha default'''}}

*GIM--->PNG--->GIM method (fails when there is involved a DXT conversion because DXT conversions are lossy, works fine for rgba**** image formats):
**Use rcomagegui to make an extraction of the contents '''without''' conversion of images (this way the GIM are extracted as GIM)
**Use rcomagegui to make another extraction of the contents '''with''' conversion of images (this way the GIM are extracted as PNG)
**Use gimconv to convert a PNG ---to---> GIM by the old method of test-error by trying some of the options availables that appears in gimonv.cfg
**Use a hexeditor to compare the original GIM extracted in step 1 with the rebuilt GIM from your test, there is no need to make accurate comparisons, just an overview of the first 0x80 bytes of the header, and how the pixel data is ordered starting at offset 0x80
**When the header and pixel data seems similar make a hash comparison, original GIM and rebuild GIM should be exactly the same hash (is posible to create a GIM exactly like the original)

*By using GimConv.exe with the '''-S''' option
**This generates a .GIS file (is a text based file that contains info about the .GIM file, included all the pixel data)
{{Keyboard|content='''GimConv\GimConv.exe -S test.gim -o test.gis'''}}

=GIM formats used in PS3=
PS3 uses at least 2 types of GIM images, both included inside rco's, and in some cases both types in the same rco

When an .RCO contains 2 or more images that was created with different .GIM settings... it means is not posible to compile the .RCO with rcomage by using .PNG images as source (because rcomage.exe sends the GIM settings to gimconv.exe to make the PNG--->GIM image conversion and this settings are applyed to all PNG images)

In other words, the only way to compile this RCO's is in 2 steps. In the first step is needed to make the different .GIM conversions with gimconv.exe (and all the other conversions in case exists .VAG audio a WAV2VAG conversion or a JS2VSMX for the .VSMX script). In the second step is needed to compile the .RCO with rcomage.exe by using the .GIM's .VAG's and .VSMX's as sources without any kind of file conversions

Also means we have a big problem to document in wiki wich settings are used for each image (there are thousands of images so initially seems not posible), but probably they follows a rule, so the solution is to deduce or imagine the real reason of why the ps3 is using different gim formats inside the .rco's

{| class="wikitable"
|-
! image group or rco !! gim settings !! notes
|-
| '''ps3bpp32''' || --format_style psp --format_endian big --image_format rgba8888 --pixel_order normal || Most used GIM format inside .rco's
|-
| '''ps3dxt5''' || --format_style psp --format_endian big --image_format dxt5 || Second most used GIM format inside rco's
|}

'''Notes about [[explore_plugin]]_full.rco from firmware 4.70''':
*There are 245 images
**201 was created by using options: ''--format_style psp --format_endian big --image_format rgba8888 --pixel_order normal'' (exact match of gims after rebuilding gim--->png--->gim)
**030 was created by using options: ''--format_style psp --format_endian big --image_format rgba8888 --pixel_order normal --update_fileinfo on'' (exact match of gims after removing footer from originals and rebuilding gim--->png--->gim)
**014 was created by using options: ''--format_style psp --format_endian big --image_format dxt5'' (exact match of gims after rebuilding gim--->gim)
***item_tex_trophy.gim, trophy_tex_grade_bronze.gim, trophy_tex_grade_gold.gim, trophy_tex_grade_hidden.gim, trophy_tex_grade_platinum.gim, trophy_tex_grade_silver.gim, item_tex_CardBallon.gim, item_tex_Profile_Game.gim, item_tex_Profile_Highlight.gim, item_tex_Profile_Onlines.gim, tex_indi_Me.gim, tex_sb_base.gim, tex_sb_base_s.gim, tex_sb_slider.gim

This is the footer of item_tex_cam_icon.gim (was added to the gim by enabling '''update_fileinfo''' option, variable size)
 '''Offset(h) 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F'''
 
 00006AD0  00 FF 00 00 00 00 00 4C 00 00 00 4C 00 00 00 10  .ÿ.....L...L....
 00006AE0  53 70 61 6E 61 2E 74 67 61 00 73 30 30 30 39 33  Spana.tga.s00093
 00006AF0  37 00 53 75 6E 20 41 70 72 20 32 33 20 31 38 3A  7.Sun Apr 23 18:
 00006B00  33 39 3A 34 38 20 32 30 30 36 00 47 69 6D 43 6F  39:48 2006.GimCo
 00006B10  6E 76 20 31 2E 32 30 65 00 00 00 00              nv 1.20e....

And this is the footer of a rebuild gim where the footer was added in the rebuild process
 '''Offset(h) 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F'''
 
 00002300  00 FF 00 00 00 00 00 54 00 00 00 54 00 00 00 10  .ÿ.....T...T....
 00002310  74 65 78 5F 70 73 6E 2E 70 6E 67 00 41 64 6D 69  tex_psn.png.Admi
 00002320  6E 69 73 74 72 61 64 6F 72 00 53 61 74 20 4D 61  nistrador.Sat Ma
 00002330  72 20 30 37 20 30 31 3A 33 32 3A 30 31 20 32 30  r 07 01:32:01 20
 00002340  31 35 00 47 69 6D 43 6F 6E 76 20 31 2E 32 30 68  15.GimConv 1.20h
 00002350  00 00 00 00                                      ....

It seems the reason why this images are slighty different is because are ancient (has not been updated lot of firmwares ago, and uses the format from the first firmwares)

As interesting details, in the footer of original files it can be seen the name and format of the original image (.tga), the windows user name, timestamp (from 2006), an the version of GimConv (an old 1.20e)

The '''00 00 00 4C''' (repeated 2 times) at top of the footer in the original gim example is the size of the whole footer (usefull to make the calculation to remove the footer and update the filesize at gim header)

==Speculation==
Initially... it seems the gim format depends of who is the responsible of displaying them (as an example, in the link above it seems the images reported as "rare" belongs to "tex_indi_***" (are textures for the "indicator", is the information bar at top-right of xmb, are the tiny icons that appears eventually when you receive a message, etc..)

<strike>Note is posible to group them based in how his names starts, all "tex_indi" belongs to indicator so should share the same gim format, even if there are more "tex_indi" inside other rco's, doesnt matters in wich .rco are located what matters is his purpose is the same (to be displayed inside the indicator)</strike> This assumption seems wrong

{{File Formats}}
<noinclude>[[Category:Main]]</noinclude>