Permalink
Browse files

C client: Add some minimal documentation in some header files

  • Loading branch information...
UnknownShadow200 committed Oct 11, 2018
1 parent c8c2225 commit 427532a98a829b74c257365c2b4bc08f6a35c089
Showing with 150 additions and 35 deletions.
  1. +4 −4 src/Audio.c
  2. +9 −9 src/AxisLinesRenderer.c
  3. +2 −4 src/Constants.h
  4. +1 −2 src/Graphics.h
  5. +8 −8 src/GraphicsCommon.c
  6. +3 −3 src/Platform.c
  7. +91 −3 src/Platform.h
  8. +31 −1 src/Stream.h
  9. +1 −1 src/Vorbis.c
View
@@ -367,10 +367,10 @@ static ReturnCode Music_PlayOgg(struct Stream* source) {
/* so we may end up decoding slightly over a second of audio */
int i, chunkSize = fmt.Channels * (fmt.SampleRate + vorbis.BlockSizes[1]);
int samplesPerSecond = fmt.Channels * fmt.SampleRate;
data = Mem_Alloc(chunkSize * AUDIO_MAX_CHUNKS, 2, "Ogg - final PCM output");
data = Mem_Alloc(chunkSize * AUDIO_MAX_BUFFERS, 2, "Ogg - final PCM output");
/* fill up with some samples before playing */
for (i = 0; i < AUDIO_MAX_CHUNKS && !res; i++) {
for (i = 0; i < AUDIO_MAX_BUFFERS && !res; i++) {
res = Music_Buffer(i, &data[chunkSize * i], samplesPerSecond, &vorbis);
}
if (music_pendingStop) goto cleanup;
@@ -382,7 +382,7 @@ static ReturnCode Music_PlayOgg(struct Stream* source) {
for (;;) {
int next = -1;
for (i = 0; i < AUDIO_MAX_CHUNKS; i++) {
for (i = 0; i < AUDIO_MAX_BUFFERS; i++) {
res = Audio_IsCompleted(music_out, i, &completed);
if (res) { music_pendingStop = true; break; }
if (completed) { next = i; break; }
@@ -425,7 +425,7 @@ static void Music_RunLoop(void) {
char pathBuffer[FILENAME_SIZE];
ReturnCode res = 0;
Audio_Init(&music_out, AUDIO_MAX_CHUNKS);
Audio_Init(&music_out, AUDIO_MAX_BUFFERS);
while (!music_pendingStop && count) {
int idx = Random_Range(&rnd, 0, count);
View
@@ -9,9 +9,9 @@
#include "Entity.h"
GfxResourceID axisLines_vb;
#define axisLines_numVertices 12
#define axisLines_size (1.0f / 32.0f)
#define axisLines_length 3.0f
#define AXISLINES_NUM_VERTICES 12
#define AXISLINES_THICKNESS (1.0f / 32.0f)
#define AXISLINES_LENGTH 3.0f
static void AxisLinesRenderer_ContextLost(void* obj) {
Gfx_DeleteVb(&axisLines_vb);
@@ -35,18 +35,18 @@ void AxisLinesRenderer_Render(double delta) {
if (!Game_ShowAxisLines || Gfx_LostContext) return;
/* Don't do it in a ContextRecreated handler, because we only want VB recreated if ShowAxisLines in on. */
if (!axisLines_vb) {
axisLines_vb = Gfx_CreateDynamicVb(VERTEX_FORMAT_P3FC4B, axisLines_numVertices);
axisLines_vb = Gfx_CreateDynamicVb(VERTEX_FORMAT_P3FC4B, AXISLINES_NUM_VERTICES);
}
Gfx_SetTexturing(false);
Vector3 P = LocalPlayer_Instance.Base.Position; P.Y += 0.05f;
VertexP3fC4b vertices[axisLines_numVertices];
VertexP3fC4b vertices[AXISLINES_NUM_VERTICES];
Vector3 coords[5]; coords[2] = P;
Vector3_Add1(&coords[0], &P, -axisLines_length);
Vector3_Add1(&coords[1], &P, -axisLines_size);
Vector3_Add1(&coords[3], &P, axisLines_size);
Vector3_Add1(&coords[4], &P, axisLines_length);
Vector3_Add1(&coords[0], &P, -AXISLINES_LENGTH);
Vector3_Add1(&coords[1], &P, -AXISLINES_THICKNESS);
Vector3_Add1(&coords[3], &P, AXISLINES_THICKNESS);
Vector3_Add1(&coords[4], &P, AXISLINES_LENGTH);
static uint8_t indices[36] = {
2,2,1, 2,2,3, 4,2,3, 4,2,1, /* X arrow */
View
@@ -7,14 +7,12 @@
#define PROGRAM_MAX_CMDARGS 5
#define PROGRAM_APP_NAME "ClassiCube 0.99.9.2"
#define USE16_BIT FALSE
/* Max number of characters strings can have. */
#define STRING_SIZE 64
/* Max number of characters filenames can have. */
#define FILENAME_SIZE 260
/* Chunk axis length, in blocks. */
/* Chunk axis length in blocks. */
#define CHUNK_SIZE 16
#define HALF_CHUNK_SIZE 8
#define CHUNK_SIZE_2 (CHUNK_SIZE * CHUNK_SIZE)
@@ -24,7 +22,7 @@
#define CHUNK_MAX 15
#define CHUNK_SHIFT 4
/* Chunk axis length (and neighbours), in blocks. */
/* Chunk axis length (plus neighbours) in blocks. */
#define EXTCHUNK_SIZE 18
#define EXTCHUNK_SIZE_2 (EXTCHUNK_SIZE * EXTCHUNK_SIZE)
#define EXTCHUNK_SIZE_3 (EXTCHUNK_SIZE * EXTCHUNK_SIZE * EXTCHUNK_SIZE)
View
@@ -93,8 +93,7 @@ void Gfx_CalcPerspectiveMatrix(float fov, float aspect, float zNear, float zFar,
/* Outputs a .png screenshot of the backbuffer */
ReturnCode Gfx_TakeScreenshot(struct Stream* output, int width, int height);
/* Adds a warning to game's chat if this graphics API has problems with the current user's GPU.
Returns boolean of whether legacy rendering mode is needed. */
/* Warns if this graphics API has problems with the user's GPU. Returns whether legacy rendering mode is needed. */
bool Gfx_WarnIfNecessary(void);
void Gfx_BeginFrame(void);
void Gfx_EndFrame(void);
View
@@ -60,10 +60,10 @@ void GfxCommon_Draw2DFlat(int x, int y, int width, int height, PackedCol col) {
VertexP3fC4b verts[4];
VertexP3fC4b v; v.Z = 0.0f; v.Col = col;
v.X = (float)x; v.Y = (float)y; verts[0] = v;
v.X = (float)(x + width); verts[1] = v;
v.Y = (float)(y + height); verts[2] = v;
v.X = (float)x; verts[3] = v;
v.X = (float)x; v.Y = (float)y; verts[0] = v;
v.X = (float)(x + width); verts[1] = v;
v.Y = (float)(y + height); verts[2] = v;
v.X = (float)x; verts[3] = v;
Gfx_SetBatchFormat(VERTEX_FORMAT_P3FC4B);
GfxCommon_UpdateDynamicVb_IndexedTris(GfxCommon_quadVb, verts, 4);
@@ -74,9 +74,9 @@ void GfxCommon_Draw2DGradient(int x, int y, int width, int height, PackedCol top
VertexP3fC4b v; v.Z = 0.0f;
v.X = (float)x; v.Y = (float)y; v.Col = top; verts[0] = v;
v.X = (float)(x + width); verts[1] = v;
v.Y = (float)(y + height); v.Col = bottom; verts[2] = v;
v.X = (float)x; verts[3] = v;
v.X = (float)(x + width); verts[1] = v;
v.Y = (float)(y + height); v.Col = bottom; verts[2] = v;
v.X = (float)x; verts[3] = v;
Gfx_SetBatchFormat(VERTEX_FORMAT_P3FC4B);
GfxCommon_UpdateDynamicVb_IndexedTris(GfxCommon_quadVb, verts, 4);
@@ -104,7 +104,7 @@ void GfxCommon_Make2DQuad(struct Texture* tex, PackedCol col, VertexP3fT2fC4b**
VertexP3fT2fC4b v; v.Z = 0.0f; v.Col = col;
v.X = x1; v.Y = y1; v.U = tex->U1; v.V = tex->V1; ptr[0] = v;
v.X = x2; v.U = tex->U2; ptr[1] = v;
v.Y = y2; v.V = tex->V2; ptr[2] = v;
v.Y = y2; v.V = tex->V2; ptr[2] = v;
v.X = x1; v.U = tex->U1; ptr[3] = v;
*vertices += 4;
}
View
@@ -1260,7 +1260,7 @@ static ReturnCode Audio_AllCompleted(AudioHandle handle, bool* finished);
#ifdef CC_BUILD_WIN
struct AudioContext {
HWAVEOUT Handle;
WAVEHDR Headers[AUDIO_MAX_CHUNKS];
WAVEHDR Headers[AUDIO_MAX_BUFFERS];
struct AudioFormat Format;
int Count;
};
@@ -1359,8 +1359,8 @@ ReturnCode Audio_IsFinished(AudioHandle handle, bool* finished) { return Audio_A
#ifdef CC_BUILD_NIX
struct AudioContext {
ALuint Source;
ALuint Buffers[AUDIO_MAX_CHUNKS];
bool Completed[AUDIO_MAX_CHUNKS];
ALuint Buffers[AUDIO_MAX_BUFFERS];
bool Completed[AUDIO_MAX_BUFFERS];
struct AudioFormat Format;
int Count;
ALenum DataFormat;
View
@@ -15,8 +15,11 @@ typedef uintptr_t SocketPtr;
typedef int SocketPtr;
#endif
extern char* Platform_NewLine; /* Newline for text */
/* Newline for console and text files. */
extern char* Platform_NewLine;
/* Character in a path that distinguishes directories. (usually / or \) */
extern char Directory_Separator;
/* Name of default system font used. (e.g. Arial) */
extern char* Font_DefaultName;
extern ReturnCode ReturnCode_FileShareViolation;
extern ReturnCode ReturnCode_FileNotFound;
@@ -25,102 +28,187 @@ extern ReturnCode ReturnCode_SocketInProgess;
extern ReturnCode ReturnCode_SocketWouldBlock;
extern ReturnCode ReturnCode_InvalidArg;
/* Encodes a string in platform specific format. (e.g. unicode on windows, UTF8 on linux) */
/* NOTE: Only useful for platform specific function calls - do NOT try to interpret the data. */
void Platform_ConvertString(void* dstPtr, const String* src);
/* Initalises the platform specific state */
void Platform_Init(void);
/* Frees the platform specific state */
void Platform_Free(void);
/* Sets current directory to directory executable is in */
void Platform_SetWorkingDir(void);
/* Exits the process with the given return code */
void Platform_Exit(ReturnCode code);
/* Gets the command line arguments passed to the program. */
int Platform_GetCommandLineArgs(int argc, STRING_REF const char** argv, String* args);
/* Starts the platform's shell with the given arguments. (e.g. open http:// url in web browser) */
ReturnCode Platform_StartShell(const String* args);
/* Allocates a block of memory, with undetermined contents. Exits process on allocation failure. */
NOINLINE_ void* Mem_Alloc(uint32_t numElems, uint32_t elemsSize, const char* place);
/* Allocates a block of memory, with contents of all 0. Exits process on allocation failure. */
NOINLINE_ void* Mem_AllocCleared(uint32_t numElems, uint32_t elemsSize, const char* place);
/* Reallocates a block of memory, with undetermined contents. Exits process on reallocation failure. */
NOINLINE_ void* Mem_Realloc(void* mem, uint32_t numElems, uint32_t elemsSize, const char* place);
/* Frees an allocated a block of memory. Does nothing when passed NULL. */
NOINLINE_ void Mem_Free(void* mem);
/* Sets the contents of a block of memory to the given value. */
void Mem_Set(void* dst, uint8_t value, uint32_t numBytes);
/* Copies a block of memory to another block. NOTE: These blocks MUST NOT overlap. */
void Mem_Copy(void* dst, void* src, uint32_t numBytes);
/* Logs a debug message to console. */
void Platform_Log(const String* message);
void Platform_LogConst(const char* message);
void Platform_Log1(const char* format, const void* a1);
void Platform_Log2(const char* format, const void* a1, const void* a2);
void Platform_Log3(const char* format, const void* a1, const void* a2, const void* a3);
void Platform_Log4(const char* format, const void* a1, const void* a2, const void* a3, const void* a4);
/* Returns the current UTC time, as number of milliseconds since 1/1/0001 */
TimeMS DateTime_CurrentUTC_MS(void);
/* Returns the current UTC Time. */
/* NOTE: Generally DateTime_CurrentUTC_MS should be used instead. */
void DateTime_CurrentUTC(DateTime* time);
/* Returns the current local Time. */
void DateTime_CurrentLocal(DateTime* time);
/* Takes a platform-specific stopwatch measurement. */
/* NOTE: The value returned is platform-specific - do NOT try to interpret the value. */
void Stopwatch_Measure(uint64_t* timer);
/* Returns total elapsed microseconds since the given stopwatch measurement. */
int Stopwatch_ElapsedMicroseconds(uint64_t* timer);
/* Returns whether the given directory exists. */
bool Directory_Exists(const String* path);
/* Attempts to create a new directory. */
ReturnCode Directory_Create(const String* path);
/* Callback function invoked for each file found. */
typedef void Directory_EnumCallback(const String* filename, void* obj);
/* Invokes a callback function on all filenames in the given directory (and its sub-directories) */
ReturnCode Directory_Enum(const String* path, void* obj, Directory_EnumCallback callback);
/* Returns whether the given file exists. */
bool File_Exists(const String* path);
/* Returns the last time the file was modified, as number of milliseconds since 1/1/0001 */
ReturnCode File_GetModifiedTime_MS(const String* path, TimeMS* ms);
/* Attempts to create a new (or overwrite) file for writing. */
ReturnCode File_Create(void** file, const String* path);
/* Attempts to open an existing file for reading. */
ReturnCode File_Open(void** file, const String* path);
/* Attempts to open (or create) a file, for appending data to the end of the file. */
ReturnCode File_Append(void** file, const String* path);
/* Attempts to read data from the file. */
ReturnCode File_Read(void* file, uint8_t* buffer, uint32_t count, uint32_t* bytesRead);
/* Attempts to write data to the file. */
ReturnCode File_Write(void* file, uint8_t* buffer, uint32_t count, uint32_t* bytesWrote);
/* Attempts to close the given file. */
ReturnCode File_Close(void* file);
/* Attempts to seek to a position in the given file. */
ReturnCode File_Seek(void* file, int offset, int seekType);
/* Attempts to get the current position in the given file. */
ReturnCode File_Position(void* file, uint32_t* position);
/* Attempts to retrieve the length of the given file. */
ReturnCode File_Length(void* file, uint32_t* length);
/* Blocks the current thread for the given number of milliseconds. */
void Thread_Sleep(uint32_t milliseconds);
typedef void Thread_StartFunc(void);
/* Starts a new thread, optionally immediately detaching it. (See Thread_Detach) */
void* Thread_Start(Thread_StartFunc* func, bool detach);
/* Frees the platform specific persistent data associated with the thread. */
/* NOTE: You must either detach or join threads, as this data otherwise leaks. */
void Thread_Detach(void* handle);
/* Blocks the current thread, until the given thread has finished. */
/* NOTE: Once a thread has been detached, you can no longer use this method. */
void Thread_Join(void* handle);
/* Allocates a new mutex. (used to synchronise access to a shared resource) */
void* Mutex_Create(void);
/* Frees an allocated mutex. */
void Mutex_Free(void* handle);
/* Locks the given mutex, blocking other threads from entering. */
void Mutex_Lock(void* handle);
/* Unlocks the given mutex, allowing other threads to enter. */
void Mutex_Unlock(void* handle);
/* Allocates a new waitable. (used to conditionally wake-up a blocked thread) */
void* Waitable_Create(void);
/* Frees an allocated waitable. */
void Waitable_Free(void* handle);
/* Signals a waitable, waking up blocked threads. */
void Waitable_Signal(void* handle);
void Waitable_Wait(void* handle);
/* Blocks the calling thread until the waitable gets signalled. */
void Waitable_Wait(void* handle);
/* Blocks the calling thread until the waitable gets signalled, or milliseconds delay passes. */
void Waitable_WaitFor(void* handle, uint32_t milliseconds);
/* Gets the list of all supported font names on this platform. */
NOINLINE_ void Font_GetNames(StringsBuffer* buffer);
/* Allocates a new font from the given arguments. */
NOINLINE_ void Font_Make(FontDesc* desc, const String* fontName, int size, int style);
/* Frees an allocated font. */
NOINLINE_ void Font_Free(FontDesc* desc);
/* Measures dimensions of the given text, if it was drawn with the given font. */
NOINLINE_ Size2D Platform_TextMeasure(struct DrawTextArgs* args);
/* Draws the given text with the given font onto the given bitmap. */
NOINLINE_ Size2D Platform_TextDraw(struct DrawTextArgs* args, Bitmap* bmp, int x, int y, PackedCol col);
/* Allocates a new socket. */
void Socket_Create(SocketPtr* socket);
/* Returns how much data is available to be read from the given socket. */
ReturnCode Socket_Available(SocketPtr socket, uint32_t* available);
/* Sets whether operations on this socket block the calling thread. */
/* e.g. if blocking is on, calling Connect() blocks until a response is received. */
ReturnCode Socket_SetBlocking(SocketPtr socket, bool blocking);
/* Returns (and resets) the last error generated by this socket. */
ReturnCode Socket_GetError(SocketPtr socket, ReturnCode* result);
/* Attempts to initalise a TCP connection to the given IP address:port. */
ReturnCode Socket_Connect(SocketPtr socket, const String* ip, int port);
/* Attempts to read data from the given socket. */
ReturnCode Socket_Read(SocketPtr socket, uint8_t* buffer, uint32_t count, uint32_t* modified);
/* Attempts to write data to the given socket. */
ReturnCode Socket_Write(SocketPtr socket, uint8_t* buffer, uint32_t count, uint32_t* modified);
/* Attempts to close the given socket. */
ReturnCode Socket_Close(SocketPtr socket);
/* Attempts to poll the socket for reading or writing. */
ReturnCode Socket_Select(SocketPtr socket, int selectMode, bool* success);
/* Initalises the platform specific http library state. */
void Http_Init(void);
/* Performs a http request, setting progress as data is received. */
/* NOTE: NOT thread safe - you should always use AsyncDownloader for making requests. */
ReturnCode Http_Do(struct AsyncRequest* req, volatile int* progress);
/* Frees the platform specific http library state. */
ReturnCode Http_Free(void);
#define AUDIO_MAX_CHUNKS 4
#define AUDIO_MAX_BUFFERS 4
/* Information about a source of audio. */
struct AudioFormat { uint16_t Channels, BitsPerSample; int SampleRate; };
#define AudioFormat_Eq(a, b) ((a)->Channels == (b)->Channels && (a)->BitsPerSample == (b)->BitsPerSample && (a)->SampleRate == (b)->SampleRate)
typedef int AudioHandle;
/* Allocates an audio context. */
void Audio_Init(AudioHandle* handle, int buffers);
/* Frees an allocated audio context. */
/* NOTE: Audio_StopAndFree should be used, because this method can fail if audio is playing. */
ReturnCode Audio_Free(AudioHandle handle);
/* Stops playing audio, unqueues buffers, then frees the audio context. */
ReturnCode Audio_StopAndFree(AudioHandle handle);
/* Returns the format audio is played in. */
struct AudioFormat* Audio_GetFormat(AudioHandle handle);
/* Sets the format audio to play is in. */
/* NOTE: Changing the format can be expensive, depending on the platform. */
ReturnCode Audio_SetFormat(AudioHandle handle, struct AudioFormat* format);
/* Sets the audio data in the given buffer. */
/* NOTE: You should ensure Audio_IsCompleted returns true before calling this. */
ReturnCode Audio_BufferData(AudioHandle handle, int idx, void* data, uint32_t dataSize);
/* Begins playing audio. Audio_BufferData must have been used before this. */
ReturnCode Audio_Play(AudioHandle handle);
/* Immediately stops the currently playing audio. */
ReturnCode Audio_Stop(AudioHandle handle);
/* Returns whether the given buffer has finished playing. */
ReturnCode Audio_IsCompleted(AudioHandle handle, int idx, bool* completed);
/* Returns whether all buffers have finished playing. */
ReturnCode Audio_IsFinished(AudioHandle handle, bool* finished);
#endif
Oops, something went wrong.

0 comments on commit 427532a

Please sign in to comment.