Editing GimConv


=Description=
'''GimConv v1.20h''' was 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]

It manages the [[Multimedia Formats and Tools | GIM]] image conversions to use inside [[Resource Container (RCO)]] files, [[PlayStation 3 Theme (P3T)]] files, etc...

*Other notes:
**[http://us.playstation.com/support/manuals/psp/pspguides/ PSP Custom Theme Toolbox] admits .GIM files as input, but doesnt includes a gim converter
**The option '''-viewer (start gimview.exe when process ends)''' in the config file points to an official gim viewer that doesnt exists in the public release
**Speculation about animated images support http://endlessparadigm.com/forum/showthread.php?tid=5054

=Usage=
The command line help of GimConv.exe displays a very limited list of options with an small explain, some are generic for the tool usage and others are loading another option from the config file (GimConv.cfg)

{{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==
By specifying an option, or a group of options from command line by his labels (using the names that appears in the help screen, or using the names that appears inside the GimConv.cfg file)
{{Keyboard|content='''gimconv.exe tex_psn.png -o tex_psn.gim --DXT'''}}

By specifying the options strictly from command line (using the names that appears inside the GimConv.cfg file) This is the most accurate way to specify options
{{Keyboard|content='''gimconv.exe tex_psn.png -o tex_psn.gim --format_style psp --format_endian big --pixel_order normal'''}}

By passing GIM settings from rcomage.exe ---to---> gimconv.exe when 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 ...}}
<!-- rcomage.exe compile explore_plugin_full.xml explore_plugin_full.rco --pack-hdr zlib --zlib-method default --zlib-level 9 ...INCOMPLETE_IS_MISSING_GIM_SETTINGS-->
<!-- and i cant make this 2 options work, is driving me nuts, grrr -->

==GimConv.cfg==
In this file is where are listed all the options availables of the tool and his default values

This is the original configuration file not modifyed, for more info about the modifications made in the config file supplyed with [[rcomage]] see the differences in the {{talk}} page
<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>

===Custom configurations===
The configuration file allows to modify the ''help'' screen of the command line, and to add your own options that can be composed of groups of settings, there is no need at all to do this (because doesnt really enables any new funcionallity) but is good to keep a record of the most common used formats for a console, also because allows to use cutom names so is posible to label them with an intuitive name that defines his format

The config file supplyed by rcomage contains some custom options for the formats used in PSP, some default settings changed that was common for PSP (that doesnt really affects much to the usage for PS3), and it also had one group of options added for PS3 (labeled '''-ps3''' at this time) but this group seems to use wrong options

This wiki section proposes some new groups 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)

The label names proposed here doesnt makes sense at this point, feel free to add more groups of settings with any label name following this same method, also add some info abot how many images uses this format (if posible)

*The images inside [[explore_plugin]]_full.rco from firmware 4.70 has been made by using this 3 options (only verifyed for tex_psn.gim)
{{Boxcode|content=<syntaxhighlight lang="c">
option -ps3wiki1 {
	format_style = psp
	format_endian = big
	pixel_order = normal
}
</syntaxhighlight>}}

*Any other (this 2 options seems to be common for all ps3 4.70 rco's)
{{Boxcode|content=<syntaxhighlight lang="c">
option -ps3wiki3 {
	format_style = psp
	format_endian = big
}
</syntaxhighlight>}}

=How to identify GIM settings=
*To identify the settings that was used to build a GIM file:
**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)

=GIM formats used in PS3=
Has been said [http://endlessparadigm.com/forum/showthread.php?tid=19501&pid=350611#pid350611 here] that PS3 uses at least 2 types of GIM images, both included inside rco's, and in some cases both types in the same rco

If an rco contains 2 or more images that was created with different gim settings... it means is not posible to compile this .rco with rcomage by using .png images as source (because rcomage.exe needs to pass some gim settings to gimconv.exe to make the png--->gim conversion and this settings are applyed to all png)

In other words, the only way to compile this rco's is in 2 steps, first is needed to make the different gim conversions with comconv.exe (and all the other conversions in case exists vag audio or a vsmx script), and then is needed to compile the .rco with rcomage.exe by using the gims as source

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
|-
| explore_plugin_full.rco (and other explore_plugin_***.rco ?) || --format_style psp --format_endian big --pixel_order normal || candidate to "standard" gim format for main xmb images
|-
| xmb_plugin_normal.rco (and other xmb_***.rco ?) || ? || uses some variant of dxt5 ?
|}

==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..)

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)

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