GeeXLab > Rootard Guide > Tutorials

ZIP Files

Last update: 2018.12.10 by JeGX

>> Back <<

Since version 0.26+, it is possible to store data (textures, fonts, scripts, etc.) in zip files and to load and use this data in a GeeXLab demo / application.

Data in a ZIP file

Let's start with a simple case: creating a texture with the function gh_texture.create_from_zip_file().


zip_filename = gh_utils.get_demo_dir() .. "demo.zip"
image_filename = "assets/image01.jpg"
upload_to_gpu = 1
mipmap = 1
compressed_format = ""
PF_U8_RGB = 1
PF_U8_RGBA = 3
tex_id = gh_texture.create_from_zip_file(zip_filename, image_filename, upload_to_gpu, PF_U8_RGB, 0, mipmap, compressed_format)

Same thing for an TTF font:


zip_filename = gh_utils.get_demo_dir() .. "demo.zip"
font_filename = "assets/mykoolfont.ttf"
font_height = 24
atlas_width = 512
atlas_height = 512
char_offset_start = 32
num_chars = 256
font_id = gh_font.create_from_zip(zip_filename, font_filename, font_height, atlas_width, atlas_height, char_offset_start, num_chars)

It is also possible to retrieve the content of a text file and parse it line by line (see the article on Buffers):


zip_filename = demo_dir .. "demo.zip"
filename = "params.txt"

buffer, buffer_size = gh_utils.zip_buffer_create(zip_filename, filename)
offset = 0
line, line_len = gh_utils.buffer_read_line(buffer, buffer_size, size, offset)
while (line_len > 0) do
  gh_utils.trace(line)
  offset = offset + line_len -- next line please!
  line, line_len = gh_utils.buffer_read_line(ptr, size, offset)
end

gh_utils.zip_buffer_kill(buffer)

One can also execute code Lua or Python stored in the zip archive:


zip_filename = demo_dir .. "demo.zip"
script_filename = "init_textures.lua"
if (gh_utils.do_file_from_zip(zip_filename, script_filename) == 1) then
  -- ok
end

Again, buffers can also be used:


zip_filename = demo_dir .. "demo.zip"
script_filename = "init_textures.lua"
buffer, buffer_size = gh_utils.zip_buffer_create(zip_filename, script_filename)
if (gh_utils.execute_from_buffer(buffer, buffer_size) == 1) then
  -- ok
end
gh_utils.zip_buffer_kill(buffer)

ImageMagick and buffers?


zip_filename = demo_dir .. "demo.zip"
image_filename = "assets/image01.jpg"
buffer, buffer_size = gh_utils.zip_buffer_create(zip_filename, image_filename)

PF_U8_RGB = 1
PF_U8_RGBA = 3
pixel_format = PF_U8_RGBA
gen_mipmaps = 1
free_cpu_memory = 1
upload_to_gpu = 1

gh_imagemagick.texture_create_from_buffer(buffer, buffer_size, pixel_format, gen_mipmaps, free_cpu_memory, upload_to_gpu)

gh_utils.zip_buffer_kill(buffer)

If the buffers do not appeal to you:


zip_filename = demo_dir .. "demo.zip"
image_filename = "assets/image01.jpg"

PF_U8_RGB = 1
PF_U8_RGBA = 3
pixel_format = PF_U8_RGBA
gen_mipmaps = 1
free_cpu_memory = 1
upload_to_gpu = 1

gh_imagemagick.texture_create_from_zip_file(zip_filename, image_filename, pixel_format, gen_mipmaps, free_cpu_memory, upload_to_gpu)

Complete demo in a ZIP file

Thanks to the support of ZIP files, it is now possible to store the complete demo in a zip archive. When I say complete demo, I mean main XML file, Lua / Python files and assets. It is therefore possible to deliver a single zip file that the user will just let go in GeeXLab to enjoy the new demo!

But there is a good and a bad news.

The good news is that there is not much to do. Just zip the complete demo. But you have to respect one condition: the main XML file of the demo must be at the root of the zip file and named main.xml.

The bad news is that you have to manually manage the loading of data from the zip. What I mean is that it is still possible to load a texture from a normal file (a user image that is not in the demo zip) on the disk or to load a texture from the zip of the demo.

GeeXLab 0.26+ comes with a new function to handle this case: gh_utils.get_demo_zip_filename().

get_demo_zip_filename () returns the zip file name of the demo. If get_demo_zip_filename() returns an empty string, it means that the demo was started as in the good old days, from an XML file on disk. If get_demo_zip_filename() returns a nonempty string, the demo was started from a zip file.

It is now up to the developer of the GeeXLab demo / application to manage the source of the data: from disk or from a zip.

A small example is always more telling:


local demo_zip_filename = gh_utils.get_demo_zip_filename()

-- A texture
--
local PF_U8_RGB = 1
local PF_U8_RGBA = 3

if (demo_zip_filename == "") then
  tex0 = gh_texture.create_from_file_v5(demo_dir .. "./assets/image01.jpg", PF_U8_RGB)

else
  local upload_to_gpu = 1
  local mipmap = 1
  local compressed_format = ""
  tex0 = gh_texture.create_from_zip_file(demo_zip_filename, "assets/image01.jpg", upload_to_gpu, PF_U8_RGB, 0, mipmap, compressed_format)

end  

tex_width, tex_height = gh_texture.get_size(tex0)
tex_aspect = tex_width / tex_height