physfs.h
changeset 644 1cb5533d369c
parent 625 60b5f566a258
child 646 86be93f03eb7
equal deleted inserted replaced
643:95824caf2dbf 644:1cb5533d369c
  1818  *          any sort of 64-bit support.
  1818  *          any sort of 64-bit support.
  1819  */
  1819  */
  1820 __EXPORT__ int PHYSFS_writeUBE64(PHYSFS_file *file, PHYSFS_uint64 val);
  1820 __EXPORT__ int PHYSFS_writeUBE64(PHYSFS_file *file, PHYSFS_uint64 val);
  1821 
  1821 
  1822 
  1822 
       
  1823 /* Everything above this line is part of the PhysicsFS 1.0 API. */
       
  1824 
       
  1825 
       
  1826 /**
       
  1827  * \typedef PHYSFS_memhandle
       
  1828  * \brief Used to represent memory blocks.
       
  1829  *
       
  1830  * (This is for limited, hardcore use. If you don't immediately see a need
       
  1831  *  for it, you can probably ignore this forever.)
       
  1832  *
       
  1833  * The allocator routines will pass these around. They are void pointers
       
  1834  *  because it's convenient for systems to have handles be the same size
       
  1835  *  as a pointer, but they shouldn't be assumed to point to valid memory
       
  1836  *  (or to memory at all). The allocator in use will convert from memhandles
       
  1837  *  to valid pointers to allocated memory.
       
  1838  *
       
  1839  * \sa PHYSFS_allocator
       
  1840  * \sa PHYSFS_setAllocator
       
  1841  */
       
  1842 typedef void *PHYSFS_memhandle;
       
  1843 
       
  1844 
       
  1845 /**
       
  1846  * \struct PHYSFS_allocator
       
  1847  * \brief PhysicsFS allocation function pointers.
       
  1848  *
       
  1849  * (This is for limited, hardcore use. If you don't immediately see a need
       
  1850  *  for it, you can probably ignore this forever.)
       
  1851  *
       
  1852  * You create one of these structures for use with PHYSFS_setAllocator.
       
  1853  *  It should be noted that, in order to accomodate platforms like PalmOS,
       
  1854  *  we don't just ask for a block of memory and get a pointer. We work on
       
  1855  *  a "handle" system, which requires PhysicsFS to "lock" before accessing,
       
  1856  *  and "unlock" when not using. This is also useful for systems that are
       
  1857  *  concerned about memory fragmentation; you can rearrange unlocked memory
       
  1858  *  blocks in your address space, since PhysicsFS will re-request the pointer
       
  1859  *  by relocking the block.
       
  1860  *
       
  1861  * Locked memory is assumed to be non-reentrant, and locking an already-locked
       
  1862  *  handle (and unlocking an unlocked handle) has undefined results. Use
       
  1863  *  mutexes if not sure.
       
  1864  *
       
  1865  * \sa PHYSFS_memhandle
       
  1866  * \sa PHYSFS_setAllocator
       
  1867  */
       
  1868 typedef struct
       
  1869 {
       
  1870     PHYSFS_memhandle (*malloc)(size_t);
       
  1871     PHYSFS_memhandle (*realloc)(PHYSFS_memhandle, size_t);
       
  1872     void (*free)(PHYSFS_memhandle);
       
  1873     void *(*lock)(PHYSFS_memhandle);
       
  1874     void *(*unlock)(PHYSFS_memhandle);
       
  1875 } PHYSFS_allocator;
       
  1876 
       
  1877 
       
  1878 /**
       
  1879  * \fn int PHYSFS_setAllocator(PHYSFS_allocator *allocator)
       
  1880  * \brief Hook your own allocation routines into PhysicsFS.
       
  1881  *
       
  1882  * (This is for limited, hardcore use. If you don't immediately see a need
       
  1883  *  for it, you can probably ignore this forever.)
       
  1884  *
       
  1885  * By default, PhysicsFS will use ANSI C malloc/realloc/calloc/free calls
       
  1886  *  to manage dynamic memory, but in some uncommon cases, the app might want
       
  1887  *  more control over the library's memory management. This lets you redirect
       
  1888  *  physfs to use your own allocation routines instead. You can only call this
       
  1889  *  function before PHYSFS_init(); if the library is initialized, it'll
       
  1890  *  reject your efforts to change the allocator mid-stream. You may call this
       
  1891  *  function after PHYSFS_deinit() if you are willing to shutdown the library
       
  1892  *  and restart it with a new allocator; this is a safe and supported
       
  1893  *  operation. The allocator remains intact between deinit/init calls.
       
  1894  *  If you want to return to the default allocator, pass a NULL in here.
       
  1895  *
       
  1896  * If you aren't immediately sure what to do with this function, you can
       
  1897  *  safely ignore it altogether.
       
  1898  *
       
  1899  *    \param allocator Structure containing your allocator's entry points.
       
  1900  *   \return zero on failure, non-zero on success. This call only fails
       
  1901  *           when used between PHYSFS_init() and PHYSFS_deinit() calls.
       
  1902  */
       
  1903 __EXPORT__ int PHYSFS_setAllocator(PHYSFS_allocator *allocator);
       
  1904 
       
  1905 
       
  1906 /* Everything above this line is part of the PhysicsFS 2.0 API. */
       
  1907 
       
  1908 
  1823 #ifdef __cplusplus
  1909 #ifdef __cplusplus
  1824 }
  1910 }
  1825 #endif
  1911 #endif
  1826 
  1912 
  1827 #endif  /* !defined _INCLUDE_PHYSFS_H_ */
  1913 #endif  /* !defined _INCLUDE_PHYSFS_H_ */