MosASCII Graphics Library Format (MGL) 1.0A
Written by Robert DeFusco

This document contains information about the MosASCII Graphics Library file format.

The extension for a MosASCII Graphics Library file is *.MGL

OVERVIEW
---------
MosASCII Graphics Library files are used by the Graphics Library feature in MosASCII.
Early versions of MosASCII had directories full of images which were used for the
graphics library. To make the system more efficient, the MGL file was created.

An MGL file contains 1 or more images, and information about the image (file name).
The file is compressed, and therefore is far superior to the earlier method.

MGL FORMAT OVERVIEW
-------------------
	MGL11 (HEADER ID, 5 BYTE)
	COMPRESSED DATA (ANY SIZE)

HEADER ID
---------
MGL file headers start with "MGL", then are followed by the 2 digit version of
the format.

The header ID must be 5 bytes.

MGL11 = Version 1.1

Version information must be stored in the format #.#, minus the decimal.
Therefore 1.0 = 10, and 2.5 = 25

COMPRESSED DATA
---------------
The compressed data in an MGL file is compressed using the Catalyst File Encoding
ActiveX Control, CSFED32.OCX.

READING THE FILE
----------------
You must first read the header. If bytes 1,2,3 are not M,G,L the file is invalid.
Next you must load the version information, this is used for compatibility with older
versions of MosASCII.

	EXAMPLE CODE (BASIC)

		Dim sMGLHeader As String * 5
		Dim F as Variant
		F = FreeFile

		Open sFileName For Binary Access Read As F
		    Get #F, , sMGLHeader
		Close F

		sMGLHeader = Trim(sMGLHeader)

		If Left(sMGLHeader, 3) = "MGL" Then
			Dim lVersion As Long
			lVersion = CLng(Right(sMGLHeader, Len(sMGLHeader) - 3))
			If lVersion < 10 Then MsgBox "This MGL file contains a 5K image limit!"
			If lVersion > 11 Then MsgBox "This MGL file contains a 45K image limit!"
		Else
			MsgBox "Invalid MGL File!"
		End If

To load the compressed data, simply go from byte 6 to EOF, then write that data to a
temporary file. Pass this file location to the CSFED32.OCX ExpandFile function.

	EXAMPLE CODE (BASIC)

		Open sFileName For Binary Access Read As F
		    sTheData = Input(LOF(F), #F)
		Close F

		sTheNewData = Right(sTheData, Len(sTheData) - 5)
		Open "temp.000" For Output As F
		    Print #F, sTheNewData
		Close F

		Call FileEncoder1.ExpandFile("temp.000", "temp.001")
		Kill "temp.000" ' first temp file (contained compressed data) is no longer needed

		Open "temp.001" For Binary Access Read As F
		    sTheData = Input(LOF(F), #F)
		Close F
		Kill "temp.001" ' second temp file (contained uncompressed data) is no longer needed

		For i = 1 To Len(sTheData)
		    ' Count MGL-FS: headers, and new line characters. Used for the data array
		    If Mid(sTheData, i, 2) = vbCrLf Then iNewLine = iNewLine + 1
		    If Mid(sTheData, i, 7) = "MGL-FS:" Then iMGLFS = iMGLFS + 1
		Next i

		ReDim sDataArray(iNewLine)
		ReDim sMGLFArray(iMGLFS)

		sDataArray = Split(sTheData, vbCrLf)
		On Error Resume Next
		For i = 0 To iNewLine
		    If Mid(sDataArray(i), 1, 7) = "MGL-FS:" Then
		        sMGLFInfo = Right(sDataArray(i), Len(sDataArray(i)) - 7)
		        sMGLFNArray = Split(sMGLFInfo, "|")
		        iDLen = iDLen + Len(sMGLFInfo) + 7 + 2
		        sImageData = Mid(sTheData, iDLen + 1, sMGLFNArray(1))
		        iDLen = iDLen + Len(sBlah) + 2
		        Open sMGLFNArray(0) For Output As F
		            Print #F, sImageData
		        Close F
		    End If
		Next i

		
You will now have extracted all image files in the MGL archive.

	EXAMPLE COMPRESSED MGL FILE

MGL11[compressed binary data]

	EXAMPLE UNCOMPRESSED MGL FILE

MGL-FS:File1.bmp|1024
[1024 BYTES OF DATA]
MGL-FS:File2.bmp|2054
[2054 BYTES OF DATA]
MGL-FS:File3.bmp|4024
[4024 BYTES OF DATA]
[NEW LINE]

NOTES
-----
All the code above was written for this document and may not be the optimal way to read an MGL file.
The code may have bugs, or may not function at all, it should only be used as an example to help you
write your own loading code.

This document should also help you create MGL files, simply create the raw data, then compress it with
CSFED32.OCX, and append it a valid MGL header.

	* IMPORTANT VERSION INFORMATION *

	MGL 1.0 - FIRST DRAFT
	MGL 1.1 - 45K IMAGE SIZE LIMIT

	1.1
	-----------
	
	MOSASCII BETA 5 AND NEWER HAVE 45K IMAGE SIZE LIMIT
	MosASCII Beta 5 increased the image size limit from the previous (beta 4), 4K limit, to a larger
	45K limit.
	Loading MGL 1.1 files in MosASCII Beta 4 or older may cause problems.
	Loading MGL 1.0 files in MosASCII Beta 5 or higher should not cause any problems.


	1.0 ISSUES
	-----------

	FIRST RELEASE
	MGL 1.0 (MGL10) is compatible with MosASCII Beta 4 and higher.
	* Since MosASCII Beta 4 has been phased out, Please upgrade to 1.1 to support the larger image
	file size limit *

The first PUBLIC release of MosASCII to contain MosASCII Graphics Library support is version 1.0.131


DOCUMENTATION BY Robert DeFusco
MosASCII is Copyright (c) 1998-2001 Robert DeFusco

Questions/Comments can be sent to mgl@mosascii.com

LAST MODIFIED: 11:31 PM 12/30/2001

#EOF#

