From 76dd7aecb12e4f67e642d7a58d00bd5f86ac4241 Mon Sep 17 00:00:00 2001 From: iovar Date: Tue, 14 Nov 2006 10:41:47 +0000 Subject: documented all fuctions in header git-svn-id: https://recordmydesktop.svn.sourceforge.net/svnroot/recordmydesktop/trunk@165 f606c939-3180-4ac9-a4b8-4b8779d57d0a --- recordmydesktop/include/recordmydesktop.h | 374 +++++++++++++++++++++++++++++- 1 file changed, 370 insertions(+), 4 deletions(-) (limited to 'recordmydesktop/include/recordmydesktop.h') diff --git a/recordmydesktop/include/recordmydesktop.h b/recordmydesktop/include/recordmydesktop.h index 7cc3037..811389f 100644 --- a/recordmydesktop/include/recordmydesktop.h +++ b/recordmydesktop/include/recordmydesktop.h @@ -712,40 +712,406 @@ int capture_busy, /**Function prototypes*/ -/** TODO document all the functions*/ +/** +* Loop calling XNextEvent.Retrieve and place on +* list damage events that arive, create damage for new windows. +* \param pdata ProgData struct containing all program data +*/ void *PollDamage(ProgData *pdata); + +/** +* Retrieve frame form xserver, and transform to a yuv buffer, +* either directly(full shots) or by calling UpdateImage. +* \param pdata ProgData struct containing all program data +*/ void *GetFrame(ProgData *pdata); + +/** +* feed a yuv buffer to the theora encoder and submit outcome to +* the ogg stream. +* \param pdata ProgData struct containing all program data +*/ void *EncodeImageBuffer(ProgData *pdata); + +/** +* Query theora and vorbis streams for ready packages and +* flush them on the disk +* \param pdata ProgData struct containing all program data +*/ void *FlushToOgg(ProgData *pdata); -void UpdateYUVBuffer(yuv_buffer *yuv,unsigned char *data,int x,int y,int width,int height); + +/** +* Clean up a list of areas marked for update. +* \param root Root entry of the list +*/ void ClearList(RectArea **root); + +/** +* Insert a new rectangle on the list, making sure it doesn't overlap +* with the existing ones +* \param root Root entry of the list +* +* \param wgeom New area to be inserted +* +* \returns Number of insertions during operation +* +* \note This function is reentrant and recursive. The number +* of insertions takes this into account. +*/ int RectInsert(RectArea **root,WGeometry *wgeom); + +/** +* Collide two rectangles and dictate most sane action for insertion, +* as well as provide the updated rectangle(s) +* \param wgeom1 resident rectangle +* +* \param wgeom2 New rectangle +* +* \param wgeom_return Pointer to rectangles to be inserted +* +* \param ngeoms number of entries in wgeom_return +* +* \retval 0 No collision +* +* \retval 1 wgeom1 is covered by wgeom2 +* +* \retval 2 wgeom2 is covered by wgeom1 +* +* \retval -1 wgeom1 was broken (new is picked up in wgeom_return) +* +* \retval -2 wgeom2 was broken (new is picked up in wgeom_return) +* +* \retval -10 Grouping the two geoms is possible +* +*/ int CollideRects(WGeometry *wgeom1,WGeometry *wgeom2,WGeometry **wgeom_return,int *ngeoms); + +/** +* Broadcast time condition variable, increment frame count. +* +* \param signum Number of signal received(unused, always SIGALRM) +* +*/ void SetExpired(int signum); + +/** +* Set up all callbacks and signal handlers +* \param pdata ProgData struct containing all program data +*/ void RegisterCallbacks(ProgArgs *args); -void UpdateImage(Display * dpy,yuv_buffer *yuv,pthread_mutex_t *yuv_mutex,DisplaySpecs *specs,RectArea **root,BRWindow *brwin,EncData *enc,char *datatemp,int noshmem,int no_quick_subsample); + +/** +* Retrieve and apply all changes, if xdamage is used. +* +* \param dpy Connection to the server +* +* \param yuv yuv_buffer that is to be modified +* +* \param yuv_mutex lock on the buffer +* +* \param specs DisplaySpecs struct with information about the display to be recorded +* +* \param root Root entry of the list with damaged areas +* +* \param brwin BRWindow struct contaning the recording window specs +* +* \param enc Encoding options +* +* \param datatemp Buffer for pixel data to be retrieved before placed on the yuv buffer +* +* \param noshmem don't use MIT_Shm extension +* +* \param no_quick_subsample Don't do quick subsampling +* +*/ +void UpdateImage(Display * dpy, + yuv_buffer *yuv, + pthread_mutex_t *yuv_mutex, + DisplaySpecs *specs, + RectArea **root, + BRWindow *brwin, + EncData *enc, + char *datatemp, + int noshmem, + int no_quick_subsample); + +/** +* Rerieve pixmap data from xserver +* +* \param dpy Connection to the server +* +* \param root root window of the display +* +* \param data (preallocated)buffer to place the data +* +* \param x x position of the screenshot +* +* \param y y position of the screenshot +* +* \param x x position of the screenshot +* +* \param width width of the screenshot +* +* \param height height position of the screenshot +* +* \param x x position of the screenshot +* +* \returns 0 on Success 1 on Failure +*/ int GetZPixmap(Display *dpy,Window root,char *data,int x,int y,int width,int height); + +/** +* Fill ProgArgs struct with arguments entered at execution +* +* \param argc argc as entered from main +* +* \param argv argv as entered from main +* +* \param arg_return ProgArgs struct to be filled with the options +* +* \returns 0 on Success 1 on Failure +*/ int ParseArgs(int argc,char **argv,ProgArgs *arg_return); + +/** +* Check if needed extensions are present +* +* \param dpy Connection to the server +* +* \param args ProgArgs struct containing the user-set options +* +* \param damage_event gets filled with damage event number +* +* \param damage_error gets filled with damage error number +* +* \note Can be an exit point if extensions are not found +*/ void QueryExtensions(Display *dpy,ProgArgs *args,int *damage_event,int *damage_error); + +/** +* Check and align window size +* +* \param dpy Connection to the server +* +* \param brwin BRWindow struct contaning the initial and final window +* +* \param specs DisplaySpecs struct with information about the display to be recorded +* +* \param args ProgArgs struct containing the user-set options +* +* \returns 0 on Success 1 on Failure +*/ int SetBRWindow(Display *dpy,BRWindow *brwin,DisplaySpecs *specs,ProgArgs *args); + +/** +* Create an array containing the data for the dummy pointer +* +* \param specs DisplaySpecs struct with information about the display to be recorded +* +* \param size Pointer size, always square, always 16.(exists only for the possibility to create +* more dummy cursors) +* \param color 0 white, 1 black +* +* \param type Always 0.(exists only for the possibility to create +* more dummy cursors) +* +* \param npxl Return of pixel value that denotes non-drawing, while applying the cursor +* on the target image +* +* \returns Pointer to pixel data of the cursor +*/ unsigned char *MakeDummyPointer(DisplaySpecs *specs,int size,int color,int type,unsigned char *npxl); + +/** +* Sound capturing thread. Data are placed on a list to be picked up by other threads. +* +* \param pdata ProgData struct containing all program data +*/ void *CaptureSound(ProgData *pdata); + +/** +* Sound encoding thread. Picks up data from the buffer queue , encodes and places them +* on the vorbis stream. +* +* \param pdata ProgData struct containing all program data +*/ void *EncodeSoundBuffer(ProgData *pdata); -snd_pcm_t *OpenDev(const char *pcm_dev,unsigned int *channels,unsigned int *frequency,snd_pcm_uframes_t *periodsize,unsigned int *periodtime,int *hardpause); + +/** +* Open sound device, with the desired parameters +* +* \param pcm_dev name of the device +* +* \param channels desired number of channels(gets modified with the acieved value) +* +* \param frequency desired frequency(gets modified with the acieved value) +* +* \param periodsize Size of a period +* +* \param periodtime Duration of a period +* +* \param hardpause Set to 1 when the device has to be stopped during pause +* and to 0 when it supports pausing +* +* \returns snd_pcm_t handle on success, NULL on failure +*/ +snd_pcm_t *OpenDev( const char *pcm_dev, + unsigned int *channels, + unsigned int *frequency, + snd_pcm_uframes_t *periodsize, + unsigned int *periodtime, + int *hardpause); +/** +* Initialize theora,vorbis encoders, and their respective ogg streams. +* +* \param pdata ProgData struct containing all program data +* +* \param enc_data_t Encoding options +* +* \param buffer_ready when 1, the yuv buffer must be preallocated +* when 0 InitEncoder will alocate a new one +* +*/ void InitEncoder(ProgData *pdata,EncData *enc_data_t,int buffer_ready); + +/** +* Fill Yr,Yg,Yb,Ur,Ug.Ub,Vr,Vg,Vb arrays(globals) with values. +*/ void MakeMatrices(); +/** +*Align the recording window to a divisible by 2 pixel start and +*and a size divisible by 16. +* +* \param start x or y of the recording window +* +* \param size width or height of the recording window +* +* \param limit width or height of the Display +* +* \note This is called separately for width and height. +*/ void SizePack2_8_16(int *start,int *size,int limit); + +/** +* Image caching thread. Copies the yuv buffer, compares with the last one and +* caches the result. +* +* \param pdata ProgData struct containing all program data +* +*/ void *CacheImageBuffer(ProgData *pdata); + +/** +* Initializes paths and everything else needed to start caching +* +* \param pdata ProgData struct containing all program data +* +* \param enc_data_t Encoding options +* +* \param cache_data_t Caching options +* +*/ void InitCacheData(ProgData *pdata,EncData *enc_data_t,CacheData *cache_data_t); + +/** +* Sound caching thread. Simply writes the pcm buffers on disk +* +* \param pdata ProgData struct containing all program data +* +*/ void *CacheSoundBuffer(ProgData *pdata); + +/** +* Cache loading and processing thread +* +* \param pdata ProgData struct containing all program data +* +*/ void *LoadCache(ProgData *pdata); + +/** +* As EncodeImageBuffer, only with the assumption that this is not a thread on it's own +* +* \param pdata ProgData struct containing all program data +* +*/ void SyncEncodeImageBuffer(ProgData *pdata); + +/** +* Stop the timer +*/ void CancelTimer(void); + +/** +* As EncodeSoundBuffer, only with the assumption that this is not a thread on it's own +* +* \param pdata ProgData struct containing all program data +* +*/ void SyncEncodeSoundBuffer(ProgData *pdata,signed char *buff); + +/** +*Check current running window manager. +* +* \param dpy Connection to the server +* +* \param root root window of the display +* +* \returns Window manager name +*/ char *rmdWMCheck(Display *dpy,Window root); + +/** +*Construct an number postfixed name +* +* \param name base name +* +* \param newname modified name +* +* \n number to be used as a postfix +* +*/ void CacheFileN(char *name,char **newname,int n); + +/** +* Change file pointer to a new file while writting +* (file name is incremented with CacheFileN) +* +* \param name base file name +* +* \param n number to be used as a postfix +* +* \param fp File pointer if compression is used(must be NULL otherwise) +* +* \param ucfp File pointer if compression is NOT used(must be NULL otherwise) +* +* \returns 0 on Success 1 on Failure +*/ int SwapCacheFilesWrite(char *name,int n,gzFile **fp,FILE **ucfp); + +/** +* Change file pointer to a new file while reading +* (file name is incremented with CacheFileN) +* +* \param name base file name +* +* \param n number to be used as a postfix +* +* \param fp File pointer if compression is used(must be NULL otherwise) +* +* \param ucfp File pointer if compression is NOT used(must be NULL otherwise) +* +* \returns 0 on Success 1 on Failure +*/ int SwapCacheFilesRead(char *name,int n,gzFile **fp,FILE **ucfp); + +/** +* Delete all cache files +* +* \param cache_data_t Caching options(file names etc.) +* +* \returns 0 if all files and folders where deleted, 1 otherwise +*/ int PurgeCache(CacheData *cache_data_t,int sound); #endif -- cgit v1.2.1