ClassiCube/C-client-notes.md

Compiling on linux

Install appropriate libs as required. Build steps are still WIP, but current way I'm using is:

Cross compiling for windows: i586-mingw32msvc-gcc *.c -o ClassiCube.exe -mwindows -lws2_32 -lwininet -lopengl32

Compiling for linux: gcc *.c -o Classicube -lX11 -lpthread -lGL -lm

Platform

Although the majority of the code is designed to be platform-independent, some per-platform functionality is required.

Some of the per-platform functionality you'll be required to implement is:

• 3D graphics API (shader support is not required)
• File I/O, Directory I/O, Socket I/O
• Error handling (including unhandled errors/exceptions)
• Application window, keyboard state, mouse state
• Text drawing, fonts
• Threading, signalable wait, mutex
• Stopwatch timer, current system time
• Http and https, getting command line args
• Memory allocation, copying, setting

Types

• Integers and real numbers are always of a fixed size, see Typedefs.h
• There are a few typedefs of integer types to provide better context in some functions
• structs are rarely typedef-ed
• bool is an alias for 8 bit unsigned integer
• GfxResourceID is not constant type - can be pointer or integer, depending on underlying 3D graphics API
• PackedCol field order differs depending on the underlying 3D graphics API

As such, your compiler is required to support:

• explicit 8/16/32/64 bit signed and unsigned integers
• 32 and 64 bit floating point numbers

I may not have defined the appropriate types for your compiler, so you may need to modify Typedefs.h

Strings

Strings are one of the most troublesome aspects of C. In this software, strings consist of:

• Pointer to 8 bit unsigned characters (code page 437)
• Number of characters currently used (length)
• Maximum number of characters / buffer size (capacity)

Although this makes substrings / concatenating very fast, it also means STRINGS MIGHT NOT BE NULL TERMINATED (although they will be in most cases)

Note: Several functions will take raw UInt8* for performance, but this is not encouraged

String arguments

A attribute macro is applied to string parameters and/or return types in functions. The three types are:

• STRING_PURE - String is not modified, no reference is kept
• STRING_TRANSIENT - Characters in string may be modified, no reference is kept
• STRING_REF - Characters in string may be modified, reference is kept to characters

To make it extra clear, functions with STRING_REF arguments usually also have _UNSAFE_ as part of their name.

For example, consider the function STRING_REF String StringsBuffer_UNSAFE_Get(buffer, index). The returned string has characters pointing to within buffer, so modifying them also changes the contents of buffer.

In general, use of STRING_PURE or STRING_TRANSIENT is preferred when possible.

String formatting

An API is provided for formatting strings similiar to printf in C or String.Format in C#. The functions for formatting strings are in String.h:

void String_Format1(str, format, a1);
void String_Format2(str, format, a1, a2);
void String_Format3(str, format, a1, a2, a3);
void String_Format4(str, format, a1, a2, a3, a4);

Formatting specifiers

Specifier	Meaning	Example
%b	UInt8	%b of 46 = 46
%i	Int32	%i of -5 = -5
%f[0-9]	Real32	%f2 of 321.3519 = 321.35
%p[0-9]	Int32, padded	%p3 of 5 = 005
%t	Boolean	%t of 1 = true
%c	UInt8*	%c of "ABCD" = ABCD
%s	String	%s of {"ABCD", 2, 4} = AB
%r	UInt8, raw	%r of 47 = \
%x	UInt64, hex	%x of 31 = 2F
%y	UInt32, hex	%y of 11 = B